Secure uploads

Signed Uploads is a feature allowing you to implement access management in your file uploading workflows. It is available on any plan and works with both Uploadcare File Uploader and Upload API.

Switching to the Signed Uploads flow implies you have a backend-enabled product: uploading any file will require a token that should be generated on your end.

With Signed Uploads, you can control who and when can upload files to a certain Uploadcare project.

From here, you can continue reading to learn how to enable Signed Uploads, provide your engineering team with this reference to dig into or contact us in case you have any questions.

Let’s break down enabling Signed Uploads in four steps.

Switching to Signed Uploads in Your Project

Projects are separate environments holding different sets of keys and settings, including security options. Navigate to your Dashboard and pick an existing project or create a new one.

Then, go to “Signed uploads” and hit “Enable.” This project will now require additional parameters provided in every request to Upload API: signature and expire. From here, your next step is choosing how you upload files: by making API requests or using our File Uploader.

Choosing Your Uploading Flow and Generate Signatures

Technically, the choice is about making API requests or configure an API client to do this for you. Uploadcare File Uploader is an Upload API client; on top of that, it adapts to your app’s layout and flow, allows uploading files from different sources like Social Media and Cloud Storage Providers, and provides tools to preview uploaded images and edit them in any browser.

No matter the flow you implement, you will need to generate signature and expire to either pass those as request parameters or file uploader options.

Once switched on in your project’s settings via our dashboard, this option requires an extra token sent to Upload API for your project to receive the upload. The extra token is called signature and is derived using the two params: secret_key and expire. And here is an example how you make it in python.

Making signature

signature is a string sent along with your upload request. It requires your Uploadcare project secret key and hence should be crafted on your back end.

The signature is an HMAC/SHA256 with expire string (which stands for a time in the future when your signature expires) as a message and secret_key as a key.

Below is how you make a signature in Python,

import time
import hashlib
import hmac

def generate_secure_signature(secret, expire):
    k, m = secret, str(expire).encode('utf-8')
    if not isinstance(k, (bytes, bytearray)):
        k = k.encode('utf-8')

    return hmac.new(k, m, hashlib.sha256).hexdigest()

# Expire in 30 min e.g. 1454903856
expire = int(time.time()) + 60 * 30

# Secret key of your project
secret = 'project_secret_key'

# Example result: '9890adc8886d27c93befed595abfbca514b7592a88e2f64dbddbea2d369a68dc'
signature = generate_secure_signature(secret, expire)

NodeJS,

const crypto = require('crypto');

function generateSignature(secret, expire) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(expire);
  return hmac.digest('hex');
}

// secret key
const secret = 'project_secret_key';

// define expiry (e.g. 120 seconds)
const expire = (Math.round(Date.now() / 1000) + 120).toString();
const signature = generateSignature(secret, expire);

Ruby,

require "openssl" # if necessary

def generate_signature(secret, expire_at)
OpenSSL::HMAC.hexdigest("SHA256", secret, expire_at.to_i.to_s)
end

secret = 'secret'
expire_at = Time.now + 60 * 2 # 2 minutes from now
generate_signature(secret, expire_at)

expire explained

As mentioned above, expire sets the time until your signature is valid. It is a Unix time, e.g., 1454902434.

Signed Uploads example

Request:

curl -F "UPLOADCARE_PUB_KEY=caa9d29da887ee88ffe6" \
     -F "signature=46f70d2b4fb6196daeb2c16bf44a7f1e" \
     -F "expire=1454903856" \
     -F "file=@image.jpg" \
     "https://upload.uploadcare.com/base/"

Response:

{
  "file": "c0d776d4-8c8e-47df-9e92-03b68b99c2ba"
}

Possible errors

If you enable Signed Uploads for one of your projects, then both signature and expire parameters are required for every upload request. Otherwise, you’ll receive one of the following errors:

[HTTP 400] 'signature' is required.
[HTTP 400] 'expire' is required.

If expire is not a valid Unix timestamp,

[HTTP 400] 'expire' must be a UNIX timestamp.

If your signature has expired, i.e., expire < now,

[HTTP 403] Expired signature.

If signature is incorrect,

[HTTP 403] Invalid signature.

Now that you know how to generate the parameters, it’s time for a hands-on.

Testing Signed Uploads

With Upload API, you make a request providing signature and expire. Don’t forget to specify your Public API Key in UPLOADCARE_PUB_KEY. We’ve got ready-made request and response examples here.

With Uploadcare File Uploader, your first step is configuring and installing it. Then you specify the Secure signature and Secure expire file uploader options.

Note, you will still be able to upload files to your project directly via the “Files” tab.