Encryption Key

Applies To:

HTTP LargeThis platform has been optimized to cache and deliver static content (e.g., HTML, CSS, JavaScript, ISO, multimedia, and software downloads, etc.) over HTTP or HTTPS.

HTTP SmallLegacy. If you are currently serving traffic over this platform, then you may continue to do so. However, we recommend that you serve your traffic over our more robust HTTP Large platform.

ADNThe Application Delivery Network platform has been optimized to deliver dynamic content (e.g., login credentials, account information, etc.) over HTTP or HTTPS. Typically, user-specific and database-driven content are served over this platform.

TBAThe Token-Based Authentication feature enforces authentication prior to content delivery. Authentication takes place via an encoded token value that must be included in the request URL. This token value is then decrypted on an edge server. The requested content will only be delivered when the user meets the requirement(s) defined in the token.

An encryption key must be defined for each platform on which Token-Based Authentication will be applied. This service leverages this platform-specific encryption key to encrypt and decrypt token values.

Key information:

An encryption key may consist of any combination of alphanumeric characters. All other characters, including spaces, are not valid for encryption keys.
An encryption key is case-sensitive. In other words, the case of an encryption key affects the encryption and decryption of token values.
The maximum length of an encryption key is 250 characters.
A minimum encryption version must be assigned to each key.
- V2: Indicates that the key may be used to generate both version 2.0 and 3.0 tokens. This option should only be used when transitioning from a legacy version 2.0 encryption key to version 3.0.
- V3 (Recommended): Indicates that the key may only be used to generate version 3.0 tokens.
It may take up to an hour for changes, such as setting an encryption key or adding directory authentication, to take effect.
By default, a token value is only specific to an encryption key and not to a folder or a platform. This means that it may be possible for a client to use a single token value to gain access to protected content from various folders across different platforms.
- Cross-Platform Access: Assign a unique encryption key to each platform to prevent a single token from being used across multiple platforms.
- Cross-Folder Access: Leverage the Allow URL parameter to ensure that a token may only be used for a specific directory or for a particular file.

To set an encryption key

Navigate to the Token Auth page corresponding to the desired platform.
Set the desired encryption key in the Primary Key option.
Make sure that the primary key's Minimum Encryption Version option is set to "V3."
Click Update.

Best Practices

Ensure token security by following these guidelines when defining an encryption key:

Set it to a random value.
Make sure that the encryption key candidate meets or exceeds the recommended length (i.e., 64 characters).

Do not exceed a key length size of 250 characters.

OpenSSL

A standard method for generating random values is to use the OpenSSL tool to perform hexadecimal encoding.

Syntax:

rand -hex

Hexadecimal encoding doubles the specified length. For example, specifying a length of "32" will generate a value containing 64 characters.

Example:

OpenSSL> rand -hex 32

Loading 'screen' into random state - done

70ae02ac9f8270e160eadbaefdd5df37c8e13750d1793dcd55b00943fff3b829

Switching to a New Encryption Key

Tokens may only be decrypted using either the primary or backup encryption key defined on the Token Auth page corresponding to the platform over which traffic will be served. If the requested content contains a token generated using an old encryption key, then the request will be denied.

The following factors may prevent you from instantly switching to a new encryption key:

The amount of time it takes to update all of your links to secured content.
Cached assets whose links contain old token values.
The amount of time it takes for a new encryption key to take effect (approximately 1 hour).

As a result of all of these factors, it is recommended to leverage two active encryption keys to ensure uninterrupted access to your content. This procedure requires that the old key be assigned as a backup key when creating a new encryption key. Since the old key is still an active encryption key, links that contain old tokens may still be used to authenticate.

Remove the old encryption key once the following events have taken place:

The new encryption key has taken effect.
All of your links have been updated.
Cached content that leverage an old token is no longer being served.

The above process ensures a smooth transition to a new encryption key.

To change your encryption key (recommended procedure)

Navigate to the Token Auth page corresponding to the desired platform.
From the Token-Based Authentication section, copy the value from the Primary Key option to the Backup Key option.
In the Primary Key option, type your new encryption key.
Make sure that the primary key's Minimum Encryption Version option is set to "V3."
Click Update to save your changes.

It may take up to an hour for your primary key to become active.
Generate new tokens using the new primary key.
Update all links to content secured by Token-Based Authentication to use the tokens generated in the previous step.
Purge the content updated in the previous step.
Clear the Backup Key option.
Click Update to save your changes.

It may take up to an hour for your backup key to become deactivated. After which, links that use token values based on the old encryption key will be rejected.