Archive Encryption

Vonage Video encryption allows you to create archives in which the data is never at rest in an unencrypted state.

You can secure your archives in the following ways:

• Turn off archive storage fallback — By default, Vonage stores an archive file on its servers if it was unable to upload the file to your specified Amazon S3 or Microsoft Azure server. You can prevent this fallback storage by using the REST API to set the archive upload target.
• Use Vonage video encryption — This lets you create archives where the data is never at rest in an unencrypted state. This provides the highest level of security.
• Use Amazon S3 server-side encryption — This uses Amazon S3-managed encryption keys for encryption. For details, see this developer guide.

With Vonage video encryption, video and audio data in a Vonage archive is encrypted using a public key certificate you provide Vonage.

Feature overview

The Vonage Video platform's encrypted archiving feature allows you to create archives where the data is never at rest in an unencrypted state.

First, create a public and private RSA key pair to use with your archives. Using a REST API call, you share the public key certificate with Vonage. (In the same REST call, you send details on the Amazon S3 or Microsoft Azure upload target to use for your archives.

The encrypted archiving feature requires you to set an upload target.) You save the private key locally for your private use only.

Vonage then encrypts each archive using a randomly generated password, encrypts it with the certificate, and stores the encrypted password in our servers.

When the archive is ready, you will be notified via a callback to your server, and can query for the password. At no time does Vonage store the unencrypted password, and Vonage has no way of decrypting the password (only the keeper of the private key can decrypt the password).

You can then decrypt the password using the private key, and use the password to decrypt the encrypted archive. The decrypted archive file is in MPEG-TS format.

Vonage uses the AES-256 algorithm to encrypt the archive.

The generated password is encrypted using RSA encryption with OAEP padding. Note that you can only use encrypted archiving with composed archives, not with individual stream archives.

In this guide we will look at the following:

Creating an encrypted archiving certificate

Sending the encrypted archiving certificate to Vonage

Decrypting an archive

Disabling encrypted archiving

Known issues

Creating an encrypted archiving certificate

Create an X.509 PEM certificate and a corresponding private key to use with your archives:

(Note: This has been tested with OpenSSL 1.0.1.)

You will send the certificate to Vonage, which will use it to generate an encrypted password, needed to decrypt the archive. The password can be decrypted with your private key, and the archive can be decrypted with the password. The password will be different for each archive.

The size of the key must be 2048 bits or smaller. You will send the certificate in JSON data to the Vonage video REST API for setting the archive target (see the next section). Since the certificate will be included in JSON data, send the data base64 encoded or replace newline characters in the cert with "\n".

The following example base64 encodes the certificate:

A base64-encoded certificate string looks like this:

A certificate string with newline characters replaced looks like this:

Sending the encrypted archiving certificate to Vonage

To set the certificate, and enable archive encryption, submit an HTTP PUT request to the following URL:

Replace appId with your project App ID.

Authenticate the REST API request using the Authorization header:

Create the JSON web token with the following claims:

• Set iss to your Vonage Video App ID (provided to you in your Vonage Account on the Project page).
• Set ist to "project".
• Set iat to the current Unix epoch timestamp (when the token was created), in seconds.
• Set exp to the expiration time for the token. For security, we recommend that you use an expiration time close to the token creation time (for example, 3 minutes after creation) and that you create a new token for each REST API call. The maximum allowed expiration time range is 5 minutes.
• Set jti to a unique identifier for the JWT. This is optional. See the JSON web token spec for details.

Use your project private key as the JWT secret key and sign this with the HMAC-SHA256 encryption algorithm. (Your private key is provided to you on your Video API account on the Project page.) For example, the following Python code creates a token that can be used in a REST API call:

Replace my-project-API-key and my-project-API-secret with the Vonage Video project App ID and secret. Set the Content-type header for the REST API call to application/json:

Replace the newline characters in the certificate with "\n", so that you can use it in the string literal in the JSON data. Pass in the public key certificate as a property of the JSON data you send when you call the REST method for setting archive storage. See the next sections.

Setting up encrypted archiving for an Amazon S3 target

To specify a public key certificate to use with an Amazon S3 target, set the JSON data in the REST API call to use the following format:

Set bucket to the name of the Amazon S3 bucket you want to use for archive upload. Set the secretKey and accessKey properties to the Amazon S3 secret key and access key for that bucket.

Set the fallback property to "none" to prevent archive files from being stored in the Vonage video cloud if the upload fails. Set the property to "opentok" to have the archive available on your dashboard if upload fails.

Set the certificate property to the public key certificate Vonage will use to encrypt the archive. Be sure to base64 encode the certificate or replace newline characters in the certificate with "\n", so that you can use it in the string literal in the JSON data.

Setting up encrypted archiving for a Microsoft Azure target

To specify a public key certificate to use with a Microsoft Azure target, set the JSON data in the REST API call to use the following format:

Set container to match your Microsoft Azure container name. Set the accountName and accountKey properties to match your Microsoft Azure storage credentials.

Set the fallback property to "none" to prevent archive files from being stored in the Vonage video cloud if the upload fails. Set the property to "opentok" to have the archive available on the dashboard if upload fails.

Set the certificate property to the public key certificate Vonage will use to encrypt the archive. Be sure to base64 encode the certificate or replace newline characters in the certificate with "\n", so that you can use it in the string literal in the JSON data. A base64-encoded certificate string looks like this:

REST API responses

• A response with status code 200 indicates success.
• A response with a 400 status code indicates that you have included invalid JSON data or that you did not specify the upload target.
• A response with a 403 status code indicates you passed in an invalid project App ID or Private key.

Examples

The following command line example securely sets the certificate for Vonage to use when encrypting archives to be uploaded to an Amazon S3 bucket:

Set the value for app_id to your Vonage Video project App ID. Set the values for your-s3-bucket and your-s3-access-key to match your Amazon S3 credentials. Replace the certificate value with the certificate string.

The following command line example securely sets the certificate for Vonage to use when encrypting archives to be uploaded to a Microsoft Azure bucket:

Set the value for app_id to your Vonage Video project App ID. Set the values for your-azure-account-name, your-azure-account-name, and your-azure-container to match your Amazon S3 credentials. Replace the certificate value with the certificate string.

Decrypting an archive

You can set an archive status callback using the dashboard. See "Archive status changes" in the Archiving developer guide.

After the archive is created, the archive status POST requests to your callback URL include a password property:

The password is a certificate-encrypted AES key and initialization vector, in the form of base64-encoded binary data.

The first three bytes of the binary data represent the version (one byte), the algorithm (one byte) and the mode (one byte). In this version, the length is set to 1, the algorithm is set to 1 (indicating AES-256), and the mode is set to 1 (indicating CBC).

The next 32 bytes are the key. The remaining 16 bytes are the initialization vector.

First, decode the password, and then decrypt it using your private key:

Then, use the password to decrypt the archive file:

-K is the key -iv is the initialization vector xxd turns the binary decoded and decrypted password into hex so that it can be fed to openssl. Read the xxd man page for more info on switches.

Disabling encrypted archiving

To disable encrypted archiving, submit an HTTP PUT request to archive storage URL (see Sending the encrypted archiving certificate to Vonage), but set the certificate to null in the JSON data you send with the request.

Disabling encrypted archiving for an Amazon S3 target

To remove a public key certificate for an Amazon S3 archive target (and remove encryption from the archives), call the REST API with the following JSON data:

Set bucket to the name of the Amazon S3 bucket you want to use for archive upload. Set the secretKey and accessKey properties to the Amazon S3 secret key and access key for that bucket. Set the fallback property to "none" to prevent archive files from being stored in the Vonage cloud if the upload fails. Set the property to "opentok" to have the archive available at the Vonage dashboard if upload fails. Set the certificate property to null.

Disabling encrypted archiving for a Microsoft Azure target

To remove a public key certificate for a Microsoft Azure archive target (and remove encryption from the archives), call the REST API with the following JSON data:

Set container to match your Microsoft Azure container name. Set the accountName and accountKey properties to match your Microsoft Azure storage credentials. Set the fallback property to "none" to prevent archive files from being stored in the Vonage cloud if the upload fails. Set the property to "opentok" to have the archive available at the Vonage dashboard if upload fails. Set the certificate property to null.

REST API responses

• A response with status code 200 indicates success in disabling encryption.
• A response with a 400 status code indicates that you have included invalid JSON data or that you did not specify the upload target.
• A response with a 403 status code indicates you passed in an invalid project App ID or partner secret.

Example

The following command line example disables encrypted archiving for an S3 target:

Set the value for app_id to your Vonage Video App ID. Set the values for your-s3-bucket and your-s3-access-key to match your Amazon S3 credentials.

Known issues

The duration of an encrypted archive is always reported as 0, in all Vonage Video REST API calls, in methods of the Vonage Video server SDKs, and in archive status change callbacks.