Signatures
Last updated: Oct-31-2023
Cloudinary uses digital signatures both to verify the integrity of a message and to provide authentication for communicating over the Internet using the HTTP protocol. Signatures can help ensure that the message was not tampered with during transit and provide an additional layer of security to ensure that even if the transport channel has been compromised, the contents can still be verified.
Cloudinary's SDKs take care of the signature generation where needed for communication with Cloudinary, so you will only need to manually write the code for generating a signature when NOT using our SDKs or when you want to verify a signature that was sent from Cloudinary.
The following table summarizes Cloudinary's signature usage and the payload signed in each case.
Signature usage | Example use case | Payload to sign |
---|---|---|
Generating authentication signatures | Authenticating a POST request | A string with the parameters used in the POST request to Cloudinary:
|
Verifying notification signatures | Verifying a signature in the header of a notification sent from Cloudinary | A string containing the entire response body with the X-Cld-Timestamp value appended on the end of the string. |
Generating delivery URL signatures | The signature component of a signed delivery URL of the format:/s--SIGNATURE--/
|
A string including all the components of the delivery URL that will come after the signature component. |
Verifying signatures in the JSON response | Verifying the signature parameter returned in the response to a method call. | A string with the public_id and version parameters, separated from their values with an = and then joined together with an & . |
Signature generation
To generate the signature, append your API secret to the end of the payload to sign described above, and then create a hexadecimal message digest (hash value) of the string using an SHA cryptographic function.
signature_algorithm
SDK configuration parameter to sha256
. If you want to limit your account to allow only the SHA-256 digest for all your validations, submit a request.For example:
Using Cloudinary backend SDKs to generate SHA authentication signatures
You can use one of Cloudinary's backend SDKs to generate the authentication signature. The api_sign_request
method uses the SHA-1 algorithm by default, but you can use the SHA-256 algorithm instead by setting the signature_algorithm
SDK configuration parameter to sha256
. Make sure that the timestamp is included in the params_to_sign
object.
The following Node.js app contains two examples of using the api_sign_request
method to provide a signature for uploading files:
- signed-uploads/modules/signuploadwidget.js provides a signature for uploading files using the upload widget (corresponding to signed-uploads/public/js/uploadclientwidget.js)
- signed-uploads/modules/signuploadform.js provides a signature for uploading files using a form (corresponding to signed-uploads/public/js/uploadclientform.js)
- Click Remix to Edit
- Enter your Cloudinary product environment credentials in signed-uploads/public/js/config.js
- Click View App
- Try both upload options
This code is also available in GitHub.
Important considerations for authentication signatures
When generating authentication signatures keep in mind the following:
- The
api_secret
, which is a required element of the signature, should never be revealed to anyone who is not authorized, and therefore your signature should never be generated on the client side or inside your native application. - For mobile and other client-side applications, you must either use unsigned upload or have a server for processing the signature.
- Signatures are valid for one hour from the
timestamp
value used to generate the signature. - Make sure to regenerate the signature if you dynamically change the payload of an upload request.
See the Upload API reference for a list of API methods, parameters, and response samples.
111