Documentation

Unblu 6 (latest)

Video & Voice chat archiving, including the encryption of archives and geofencing, are part of our optional Compliance Package. This guide describes how to configure Unblu, Vonage and other components to archive voice and video calls.

Unblu Video & Voice Chat are based on the Vonage Video API (formerly TokBox OpenTok). Recording, encrypting, and archiving these calls relies on the same technology.

The archive of a call made with Unblu Video & Voice Chat is always a composed archive. A composed archive is a single MP4 file containing all of the media streams involved in a call. The resolution of video calls is always 640x480 pixels.

End-to-end encryption

If you activate archiving for Voice & Video Chat, calls are no longer encrypted end-to-end. Calls must be routed via Vonage’s media servers where the media stream is decrypted as part of the archiving process and to manage group sessions.

The streams are re-encrypted before being transmitted to the call participants. Vonage never transmits unencrypted media streams on the open internet.

Please review the Vonage security page for further information.

Preliminary considerations

Before you start configuring call archiving for Video & Voice Chat, you need to decide on answers to the following questions:

  • Where do you want your archives to be stored? Do you want to use the OpenTok Cloud or do you want to provide your own upload target?

  • Do you want to encrypt the archives? If you do, you will have to provide an upload target for the archive files.

  • Do you want to store archives from different geographical areas, business units or environments in distinct upload targets? This would require setting up more than one Vonage project, as well.

  • Do you have any geofencing requirements for the processing of Video & Voice Chat? If you do, you need to inform us when we set up your Vonage project.

Create upload target

To encrypt your archives, you must specify a target where the archives can be stored for you to retrieve them. Since you will need to provide Vonage with details of the target, we recommend setting it up before you configure your Vonage project.

The target must be one of the following:

  • An Amazon S3 bucket

  • A bucket at an S3-compliant storage provider

  • An Azure blob storage container

IAM user and policy

This section is only relevant if your upload target is an Amazon S3 bucket.

Amazon recommends that you use IAM users to access AWS services such as S3. Vonage provide an example IAM user policy in their documentation. The following IAM user policy is based on the Vonage example. Replace instances of <bucket-name> with the name of your S3 bucket.

Listing 1. IAM policy to write call archives to an S3 bucket
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1427497452000",
            "Effect": "Allow",
            "Resource": [
                "*"
            ],
            "Action": [
                "s3:ListAllMyBuckets"
            ]
        },
        {
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::<bucket-name>"
            ],
            "Action": [
                "s3:ListBucket"
            ]
        },
        {
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::<bucket-name>/*"
            ],
            "Action": [
                "s3:PutObject"
            ]
        }
    ]
}

We recommend that you specify a dedicated IAM user to whom you can apply the policy. Once you have done so, you should create an access key for them. Make a note of the access key Id and the access key secret. You will need to provide Vonage with this information so that they can upload your call archive to your S3 bucket.

Delete failed multipart uploads automatically from your S3 bucket

This section is only relevant if your upload target is an Amazon S3 bucket.

It is possible to upload data in multiple parts. If such an upload fails, the parts uploaded thus far remain in your S3 bucket, using space and costing money. To avoid this, add a lifecycle rule to the configuration of your S3 bucket that cleans up incomplete multipart uploads automatically:

  1. Open the S3 bucket in the IAM console by clicking on the name of the bucket.

  2. Select the Management tab.

  3. Click on + Add Lifecycle rule.

  4. Give the lifecycle the name auto-delete-aborted-multipart-upload.

    • Select Apply to all objects in the bucket as the rule scope, then press the Next button.

  5. In the Transitions step, press the Next button.

  6. In the Expirations step, check the option Clean up incomplete multipart uploads. You can leave the time frame on its default value of 7 days.

  7. In the Review step, check the acknowledgement and press Save.

Set up archive encryption

Please also review the relevant Vonage documentation that these instructions are based on.

To ensure your call data are never in an unencrypted state, you can configure your archives to use OpenTok encryption. In this setup, you must generate an X.509 PEM public key certificate and a corresponding private key. You then transmit the public key certificate to Vonage.

The encryption and decryption is designed to ensure that only you can decrypt archives:

  • Vonage encrypt each archive with a randomly generated password.

  • They then encrypt the password using your certificate. Only the encrypted password is stored on Vonage’s servers.

  • When you want to download an archive, you first retrieve the encrypted password from Vonage.

  • You then use your private key to decrypt the password.

  • Finally, you use the password to decrypt the archive.

Create a certificate

First, create an X.509 PEM public key certificate and a private key, then base64-encode the certificate. These two steps can be accomplished with the following commands:

Listing 2. Create an X.509 PEM certificate and corresponding private key, then base64-encode the certificate
openssl req -new -x509 -days 365 -newkey rsa:2048 -out cert.pem -keyout key.pem
openssl enc -base64 -in cert.pem -out cert.pem.encoded -A

Replace every newline character in the base64-encoded certificate string with \n.

Configure Vonage project

To use the Video & Voice Chat features in Unblu, you will need at least one Vonage project. Unblu handles the initial setup of the project.

If you want Unblu to configure your project’s upload target, we will need you to provide us with additional information. Alternatively, you can configure the archive storage target yourself with a call to the Vonage REST API.

Once we have set up your Vonage project, we will send you the unencoded API key, the encoded API key, and the secret for your Vonage project. You will need this information to configure the Unblu Collaboration Server and make calls to the Vonage REST API.

Provide Unblu with upload target information

For S3 buckets, you need to provide us with the following information:

  • The name of the S3 bucket

  • The access key ID

  • The secret access key

  • The endpoint if you are using an S3 compatible storage provider other than Amazon.

If you opted to use Azure as a storage target, we need the following information:

  • The Azure storage account name

  • The Azure storage account access key

  • The Azure blob (storage container) name

  • The Azure domain in which the container resides (optional)

Additionally, you must decide whether you want to activate the fallback option for archiving. If you do, Vonage will store archives that they failed to upload to you storage target in the OpenTok cloud for 72 hours, and you can download the archives from there. If you don’t activate the fallback option, archives that cannot be uploaded to your storage target will not be available.

Send upload target details to Vonage

You can call the Vonage REST API to send the details of your upload target to Vonage. The endpoint to use is https://api.opentok.com/v2/project/<api_key>/archive/storage.

Authentication for all Vonage REST API calls takes place by means of the custom HTTP header X-OPENTOK-AUTH containing an encoded JSON Web Token (JWT). Please refer to the Authentication section of Vonage’s REST API reference for further details on authentication.

Use the unencoded Vonage API key provided by Unblu in the JWT and in the API endpoints.

If you are using Amazon AWS S3 or an S3-compliant cloud storage provider, the body of the PUT request should look like the following example:

Listing 3. PUT payload to send X.509 certificate to Vonage, S3 storage target
{
    "type": "s3",
    "config": {
        "bucket": "S3BucketName", (1)
        "secretKey": "S3Secret", (2)
        "accessKey": "S3AccessKeyID", (3)
        "endpoint": "S3EndpointURL" (4)
    },
    "fallback": "none", (5)
    "certificate": "PEMEncodedCertificate" (6)
}
1 The name you gave the S3 bucket to store the call archives
2 Your AWS secret access key
3 Your AWS access key ID
4 The S3 endpoint. This is only required if you chose an S3 compatible storage provider other than Amazon S3. Omit the property if you are using Amazon S3.
5 Set the "fallback" property to "opentok" if you want the archive to be stored by Vonage if the upload to your storage target fails. Set the property to "none" or omit it if you do not want Vonage to store your archives if the upload fails.
6 If you decided to configure archive encryption, use this property to transmit your base64-encoded X.509 PEM certificate.

The body of the PUT request for an Azure storage target should follow the example below:

Listing 4. PUT payload to send X.509 certificate to Vonage, Azure storage target
{
    "type": "azure",
    "config": {
        "accountName": "azureUsername", (1)
        "accountKey": "azureKey", (2)
        "container": "containerName" (3)
    },
    "fallback": "none", (4)
    "certificate": "PEMEncodedCertificate" (5)
}
1 The name of your Azure account
2 The key for your Azure account
3 The name of the Azure container to use as an upload target.
4 Set the "fallback" property to "opentok" if you want the archive to be stored by Vonage if the upload to your storage target fails. Set the property to "none" or omit it if you do not want Vonage to store your archives if the upload fails.
5 If you decided to configure archive encryption, use this property to transmit your base64-encoded X.509 PEM certificate.
You must configure the storage target for each of your Vonage projects.

Configure Unblu

The final step in setting up Video & Voice Chat archiving is configuring the Unblu Collaboration Server. Doing so requires the following settings:

You might also have to set the following two configuration properties:

Retrieve archives

If you followed the instructions in this guide, Video & Voice Chat calls will be archived. This alone is of little use if you lack the ability to retrieve an archive if and when you need it.

Exactly how you retrieve an archive will depend on whether you opted to use the OpenTok Cloud or chose to specify an upload target. In either case, however, you will have to make calls to the Vonage REST API.

Authentication for all Vonage REST API calls takes place via the custom HTTP header X-OPENTOK-AUTH containing an encoded JSON Web Token (JWT). Please refer to the Authentication section of Vonage’s REST API reference for details on authentication.

Use the unencoded Vonage API key provided by Unblu in the JWT and in the API endpoints.

Retrieve archives from the OpenTok cloud

To retrieve the archive for a particular conversation, complete the following steps:

  1. Retrieve the tokboxSessionID from the conversation’s data.

  2. Make a GET call to the Vonage REST API endpoint https://api.opentok.com/v2/project/<api_key>/archive?sessionId=<tokboxSessionId>. Replace <api_key> and <tokboxSessionId> with the appropriate values.

    The body of the response will contain the property "url", the value of which will be a URL where you can download the call archive.

  3. Call the URL from the "url" property to download the archive.

If you wish to download all available archives, you could use the procedure outlined below:

  1. Make a GET call to the Vonage REST API endpoint https://api.opentok.com/v2/project/<api_key>/archive. This will return a list of items describing all archives, including the URLs to download each of them.

  2. Iterate through the items with the status "available", extract the URL from each item’s "url" property, and download the archive.

  3. Once you have downloaded an archive, you can make a DELETE call to the API endpoint https://api.opentok.com/v2/project/<api_key>/archive/<id>, replacing <api_key> with your Vonage API key and <id> with the archive ID. The archive ID is the value of the "id" property of the items returned when you list all archives. This will remove the record of the archive for the list of archives. It will also remove the archive file itself.

Retrieve archives from your upload target

In the storage you specified as the upload target, all archives are saved to a directory named after your unencoded Vonage API key. In that directory, each archive is saved in a subdirectory named after the archive’s ID.

For example, if your Vonage API key is 11235813, and the archive ID for a particular call is ab0baa3d-2539-43a6-be42-b41ff1488af3, the unencrypted archive file of the call will be available at the following location in you S3 bucket or Azure container:

11235813/ab0baa3d-2539-43a6-be42-b41ff1488af3/archive.mp4

If you chose to encrypt your call archives, the archive file will be called archive.ts, and the location will be the following:

11235813/ab0baa3d-2539-43a6-be42-b41ff1488af3/archive.ts

To retrieve the archive for a particular conversation from your S3 bucket or Azure container, complete the following steps:

  1. Retrieve the "tokboxSessionID" from the conversation’s data.

  2. Make a GET call to the Vonage REST API endpoint https://api.opentok.com/v2/project/<api_key>/archive?sessionId=<tokboxSessionId>. Replace <api_key> and <tokboxSessionId with the appropriate values.

    The body of the response will contain the property "id". The value of "id" will be the name of the subdirectory in your storage target that contains the call archive.

  3. With this information, you can download the archive file from your storage target by whichever means your storage provider makes available to you.

To retrieve all available archives, you can proceed as follows:

  1. Make a GET call to the Vonage REST API endpoint https://api.opentok.com/v2/project/<api_key>/archive. This will return a list of items describing all archives. The value of "id" will be the name of the subdirectory in your storage target that contains the call archive.

  2. Iterate through the items with the status "uploaded" and retrieve the value of the "id" property. This will be the name of the subdirectory in your storage target that contains the archive for that particular call.

    If you chose to encrypt your archives, the property "password" will contain the encoded and encrypted password that you will need to decrypt the archive.

  3. With this information, you can access your storage target, retrieve the archive file for each call from its subdirectory, and decrypt it if necessary.

  4. When you have downloaded the archives, you can take the steps necessary to delete the archives from your storage. You can also make a DELETE call to the Vonage REST API endpoint https://api.opentok.com/v2/project/<api_key>/archive/<id>, replacing <api_key> with your Vonage API key and <id> with the archive ID. This will remove the record of the archive for the list of archives.

Decrypt archives

If you opted for archive encryption, you will have to decrypt the archives once you have retrieved them. Doing so involves several steps:

  1. Retrieve the archive information with the Vonage REST API.

  2. Decode the password. In the example below, replace "password-from-tokbox" with the appropriate value.

    openssl enc -base64 -d -A <<< "password-from-tokbox" -out password.enc
  3. Decrypt the password using the private key you generated when setting up archive encryption.

    openssl rsautl -decrypt -oaep -inkey key.pem -in password.enc -out password.bin
  4. Decrypt the archive using the password. In the example below, replace the file names with appropriate values.

    openssl enc -d -aes-256-cbc -nopad -in your_archive_file.ts \
      -out your_decrypted_file.mp4 \
      -K $(xxd -s 3 -l 32 -c 32 -p password.bin) \
      -iv $(xxd -s 35 -l 16 -c 16 -p password.bin)