Secure Uploading

Secure Uploading 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 Secure Uploading flow implies you have a backend-enabled product: uploading any file will require a token that should be generated on your end.

With Secure Uploading, 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 Secure Uploading, provide your engineering team with this reference to dig into or contact us in case you have any questions.

Let’s break down enabling Secure Uploading in four steps.

Switching to Secure Uploading in Your Project

A project is a separate environment that stores unique 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 “Secure Uploading” 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 should be created on your back end.

The signature is an HMAC/SHA256 with an expire string as a message (expiration time) and secret_key as a key.

Here's how to 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)

Making signature in 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);

Making signature in 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

The expire string sets the expiration date and time for a signature. It has a Unix time format (e.g., 1454903856). The expire function in the examples above includes a calculation from the moment of generation plus some duration. For example, 30 minutes.

Here's a signature expiration line of code in Python:

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

Secure Uploading 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 Secure Uploading 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 Secure Uploading

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.