Criptografia da Video API da Vonage

A criptografia do OpenTok permite criar arquivos do OpenTok nos quais os dados nunca ficam armazenados em estado não criptografado.

Você pode proteger seus arquivos do OpenTok das seguintes maneiras:

  • Desativar o armazenamento de fallback do arquivo — Por padrão, a Vonage armazena um arquivo de backup nos servidores da OpenTok caso não consiga fazer o upload do arquivo para o servidor Amazon S3 ou Microsoft Azure especificado por você. Você pode impedir esse armazenamento de fallback ao usar a API REST da OpenTok para definir o destino do upload do arquivo.

  • Use a criptografia do OpenTok — Isso permite que você crie arquivos do OpenTok nos quais os dados nunca ficam armazenados em um estado não criptografado. Isso oferece o mais alto nível de segurança.

  • Use a criptografia do lado do servidor do Amazon S3 — Essa opção utiliza chaves de criptografia gerenciadas pelo Amazon S3 para a criptografia. Para obter mais detalhes, consulte este guia para desenvolvedores.

Com a criptografia do OpenTok, os dados de vídeo e áudio em um arquivo do OpenTok são criptografados por meio de um certificado de chave pública que você fornece à Vonage.

Importante: O recurso de criptografia do OpenTok está disponível como um recurso adicional. Entre em contato conosco para ativar esse recurso para as chaves do seu projeto OpenTok.

Visão geral dos recursos

O recurso de arquivamento criptografado da Plataforma OpenTok permite criar arquivos nos quais os dados nunca ficam armazenados em estado não criptografado.

Primeiro, crie um par de chaves RSA pública e privada para usar com seus arquivos do OpenTok. Por meio de uma chamada à API REST do OpenTok, você compartilha o certificado da chave pública com a Vonage. (Na mesma chamada REST, você envia detalhes sobre o destino de upload no Amazon S3 ou no Microsoft Azure a ser usado para seus arquivos. O recurso de arquivamento criptografado exige que você defina um destino de upload.) Você salva a chave privada localmente para seu uso exclusivamente privado.

A Vonage, então, criptografa cada arquivo usando uma senha gerada aleatoriamente, criptografa-a com o certificado e armazena a senha criptografada em nossos servidores. Quando o arquivo estiver pronto, você será notificado por meio de uma chamada de retorno ao seu servidor e poderá solicitar a senha. Em nenhum momento a Vonage armazena a senha não criptografada, e a Vonage não tem como descriptografar a senha (apenas o detentor da chave privada pode descriptografar a senha).

Em seguida, você pode descriptografar a senha usando a chave privada e usar a senha para descriptografar o arquivo compactado. O arquivo compactado descriptografado está no formato MPEG-TS.

A Vonage utiliza o algoritmo AES-256 para criptografar o arquivo. A senha gerada é criptografada por meio da criptografia RSA com preenchimento OAEP. Observe que só é possível usar o arquivamento criptografado com arquivos compostos, e não com arquivos de fluxo individuais.

Este documento inclui as seguintes seções:

Criação de um certificado de arquivamento criptografado

Envio do certificado de arquivamento criptografado para a Vonage

Descompactar um arquivo

Desativando o arquivamento criptografado

Problemas conhecidos

Criação de um certificado de arquivamento criptografado

Crie um certificado X.509 no formato PEM e uma chave privada correspondente para usar com seus arquivos:

openssl req -new -x509 -days 365 -newkey rsa:2048 -out cert.pem -keyout key.pem

(Observação: Isso foi testado com o OpenSSL 1.0.1.)

Você enviará o certificado à Vonage, que o utilizará para gerar uma senha criptografada, necessária para descriptografar o arquivo compactado. A senha pode ser descriptografada com sua chave privada, e o arquivo compactado pode ser descriptografado com a senha. A senha será diferente para cada arquivo compactado.

O tamanho da chave deve ser de 2.048 bits ou menos. Você enviará o certificado em formato JSON para a API REST do OpenTok para definir o destino do arquivo (consulte a próxima seção). Como o certificado será incluído nos dados JSON, envie os dados codificados em base64 ou substitua os caracteres de nova linha no certificado por "\n".

O exemplo a seguir codifica o certificado em base64:

openssl enc -base64 -in cert.pem -out cert.pem.encoded -A

Uma string de certificado codificada em base64 tem a seguinte aparência:

"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0..."

Uma string de certificado com os caracteres de nova linha substituídos fica assim:

"-----BEGIN CERTIFICATE-----\n...\n...\n
-----END CERTIFICATE-----"

Envio do certificado de arquivamento criptografado para a Vonage

Para configurar o certificado e ativar a criptografia do arquivo, envie uma solicitação HTTP PUT para a seguinte URL:

https://api.opentok.com/v2/project/<apiKey>/archive/storage

Substituir <apiKey> com a chave da API do seu projeto OpenTok.

Autentique a solicitação da API REST usando um cabeçalho HTTP personalizado: X-OPENTOK-AUTH. Defina esse valor como um token JSON Web (consulte a documentação da API REST do OpenTok ):

X-OPENTOK-AUTH: <JSON_web_token>

Crie o token JSON da web com as seguintes reivindicações:

{
    "iss": "your_api_key",
    "ist": "project",
    "iat": current_timestamp_in_seconds,
    "exp": expire_timestamp_in_seconds,
    "jti": "jwt_nonce"
}

  • Conjunto iss à sua chave da API do OpenTok (fornecida a você em seu Vonage Account (na página do Projeto).

  • Conjunto ist para “projeto”.

  • Conjunto iat até o timestamp da época Unix atual (quando o token foi criado), em segundos.

  • Conjunto exp até o prazo de validade do token. Por motivos de segurança, recomendamos que você utilize um prazo de validade próximo à hora de criação do token (por exemplo, 3 minutos após a criação) e que crie um novo token para cada chamada à API REST. O intervalo máximo permitido para o prazo de validade é de 5 minutos.

  • Conjunto jti para um identificador exclusivo do JWT. Isso é opcional. Consulte o Especificação do JSON Web Token para mais detalhes.

Use o segredo da API do seu projeto OpenTok como chave secreta do JWT e assine-o com o algoritmo de criptografia HMAC-SHA256. (O segredo da API é fornecido a você em seu Account da Video API (na página do Projeto.)

Por exemplo, o código Python a seguir cria um token que pode ser usado em uma chamada à API REST do OpenTok:

import jwt # See https://pypi.python.org/pypi/PyJWT
import time
import uuid
print jwt.encode({"iss": "my-OpenTok-project-API-key",
  "iat": int(time.time()),
  "exp": int(time.time()) + 180,
  "ist": "project",
  "jti": str(uuid.uuid4())()},
  'my-OpenTokproject-API-secret',
  algorithm='HS256')

Substituir my-OpenTok-project-API-key e my-OpenTok-project-API-secret com a chave de API e o segredo do projeto OpenTok.

Defina o Content-type cabeçalho para a chamada da API REST para application/json:

Content-Type:application/json

Substitua os caracteres de nova linha no certificado por "\n", para que você possa usá-lo no literal de string nos dados JSON.

Passe o certificado da chave pública como uma propriedade dos dados JSON que você envia ao chamar o método REST para configurar o armazenamento de arquivos.

Consulte as próximas seções.

Configurando o arquivamento criptografado para um destino do Amazon S3

Para especificar um certificado de chave pública a ser usado com um destino do Amazon S3, defina os dados JSON na chamada da API REST de modo a utilizar o seguinte formato:

{
    "type": "s3",
    "config": {
        "bucket": "example.com.archive-bucket",
        "secretKey": "BvKwyshsmEATx5mngeloHwgKrYMbP+",
        "accessKey": "AWFS7BAO536E6MXA"
    },
    "fallback": "none",
    "certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0..."
}

Conjunto bucket para o nome do bucket do Amazon S3 que você deseja usar para o envio de arquivos. Defina o secretKey e accessKey propriedades da chave secreta e da chave de acesso do Amazon S3 para esse bucket.

Defina a propriedade “fallback” como "none" para impedir que os arquivos de arquivo sejam armazenados na nuvem da OpenTok caso o upload falhe. Defina a propriedade como "opentok" para que o arquivo fique disponível no painel do OpenTok caso o upload falhe.

Defina a propriedade do certificado como o certificado de chave pública que a Vonage utilizará para criptografar o arquivo compactado. Certifique-se de codificar o certificado em base64 ou substituir os caracteres de nova linha no certificado por "\n", para que você possa usá-lo no literal de string nos dados JSON.

Configurando o arquivamento criptografado para um destino no Microsoft Azure

Para especificar um certificado de chave pública a ser usado com um destino do Microsoft Azure, defina os dados JSON na chamada da API REST de modo a utilizar o seguinte formato:

{
    "type": "azure",
    "config": {
        "accountName":"myAccountname",
        "accountKey":"myAccountKey",
        "container": "containerName"
    },
    "fallback": "none",
    "certificate" : "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0...
}

Defina o nome do contêiner para que corresponda ao nome do seu contêiner no Microsoft Azure. Defina o accountName e accountKey propriedades que correspondam às suas credenciais de armazenamento do Microsoft Azure.

Defina o fallback propriedade para "none" para impedir que os arquivos de arquivo sejam armazenados na nuvem da OpenTok caso o upload falhe. Defina a propriedade como "opentok" para que o arquivo fique disponível no painel do OpenTok caso o upload falhe.

Defina o certificate propriedade do certificado de chave pública que a Vonage utilizará para criptografar o arquivo compactado. Certifique-se de codificar o certificado em base64 ou substituir os caracteres de nova linha no certificado por "\n", para que você possa usá-lo no literal de string nos dados JSON. Uma string de certificado codificada em base64 tem a seguinte aparência:

"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0..."

Respostas da API REST

Uma resposta com o código de status 200 indica sucesso.

Uma resposta com o código de status 400 indica que você incluiu dados JSON inválidos ou que não especificou o destino do upload.

Uma resposta com o código de status 403 indica que você inseriu uma chave de API ou um segredo de API inválidos do projeto OpenTok.

Exemplos

O exemplo de linha de comando a seguir configura com segurança o certificado que a Vonage deve usar ao criptografar arquivos a serem enviados para um bucket do Amazon S3:

api_key=12345 data='{"type":"s3","config":{"bucket":"your-s3-bucket","secretKey":"your-s3-secret-key","accessKey":"your-s3-access-key"},"certificate" : "...your-cert..."}' curl \ -i \ -H "Content-Type: application/json" \ -X PUT -H "X-OPENTOK-AUTH:$json_web_token" -d '$data' \ https://api.opentok.com/v2/project/$api_key/archive/storage

Defina o valor para api_key para a chave da API do seu projeto OpenTok. Defina o valor para json_web_token para um token JSON da Web.

Defina os valores para your-s3-bucket e your-s3-access-key para corresponder às suas credenciais do Amazon S3. Substitua o valor do certificado pela sequência de caracteres do certificado.

O exemplo de linha de comando a seguir configura com segurança o certificado que a Vonage deve usar ao criptografar arquivos compactados a serem enviados para um bucket do Microsoft Azure:

api_key=12345 data='{"type":"azure","config":{"accountName":"your-azure-account-name","accountKey":"your-azure-account-key", "container":"your-azure-container"}, "certificate": "...your-cert..."}' curl \ -i \ -H "Content-Type:application/json" \ -X PUT -H "X-OPENTOK-AUTH:$json_web_token" -d "$data" \ https://api.opentok.com/v2/project/$api_key/archive/storage

Defina o valor para api_key para a chave de API do seu projeto OpenTok. Defina o valor para json_web_token para um token JSON da Web.

Defina os valores para your-azure-account-name, your-azure-account-name, e your-azure-container para corresponder às suas credenciais do Amazon S3. Substitua o valor do certificado pela string do certificado.

Descompactar um arquivo

Você pode configurar um callback de status de arquivamento usando o painel do OpenTok. Consulte “Alterações no status de arquivamento” na Guia do desenvolvedor do OpenTok Archiving.

Após a criação do arquivo, as solicitações POST de status do arquivo enviadas para sua URL de retorno incluem uma propriedade “password”:

{
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "event": "archive",
    "createdAt" : 1384221380000,
    "duration" : 328,
    "name" : "Foo",
    "partnerId" : 123456,
    "reason" : "",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "uploaded",
    "password" : "e42c...d23"
}

A senha consiste em uma chave AES criptografada por certificado e um vetor de inicialização, na forma de dados binários codificados em base64.

Os três primeiros bytes dos dados binários representam a versão (um byte), o algoritmo (um byte) e o modo (um byte). Nesta versão, o comprimento é definido como 1, o algoritmo é definido como 1 (indicando AES-256) e o modo é definido como 1 (indicando CBC).

Os próximos 32 bytes constituem a chave. Os 16 bytes restantes constituem o vetor de inicialização.

Primeiro, decodifique a senha e, em seguida, descriptografe-a usando sua chave privada:

openssl enc -base64 -d -A <<< "password-from-tokbox" \ -out password.enc openssl rsautl -decrypt -oaep -inkey key.pem \ -in password.enc -out password.bin

Em seguida, use a senha para descriptografar o arquivo compactado:

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

-K é a chave

-iv é o vetor de inicialização

xxd converte a senha decodificada e descriptografada em binário para o formato hexadecimal, de modo que possa ser passada para o OpenSSL. Leia a página de manual do xxd para obter mais informações sobre as opções.

Desativando o arquivamento criptografado

Para desativar o arquivamento criptografado, envie uma solicitação HTTP PUT para a URL do armazenamento de arquivos (consulte Envio do certificado de arquivamento criptografado para a Vonage), mas defina o certificado como nulo nos dados JSON que você enviar com a solicitação.

Desativando o arquivamento criptografado para um destino do Amazon S3

Para remover um certificado de chave pública de um destino de arquivamento do Amazon S3 (e remover a criptografia dos arquivos), chame a API REST com os seguintes dados JSON:

{
    "type": "s3",
    "config": {
        "bucket": "example.com.archive-bucket",
        "secretKey": "BvKwyshsmEATx5mngeloHwgKrYMbP+",
        "accessKey": "AWFS7BAO536E6MXA"
    },
    "fallback": "none",
    "certificate" : null
}

Conjunto bucket para o nome do bucket do Amazon S3 que você deseja usar para o envio de arquivos. Defina o secretKey e accessKey propriedades da chave secreta e da chave de acesso do Amazon S3 para esse bucket.

Defina o fallback propriedade to "none" para impedir que os arquivos de arquivo sejam armazenados na nuvem da OpenTok caso o upload falhe. Defina a propriedade como "opentok" para que o arquivo fique disponível no painel do OpenTok caso o upload falhe.

Defina o certificate propriedade para null.

Desativando o arquivamento criptografado para um destino do Microsoft Azure

Para remover um certificado de chave pública de um destino de arquivamento do Microsoft Azure (e remover a criptografia dos arquivos), chame a API REST com os seguintes dados JSON:

{
    "type": "azure",
    "config": {
        "accountName":"myAccountname",
        "accountKey":"myAccountKey",
        "container": "containerName"
    },
    "certificate" : null
}

Conjunto container para corresponder ao nome do seu contêiner do Microsoft Azure. Defina o accountName e accountKey propriedades que correspondam às suas credenciais de armazenamento do Microsoft Azure. Defina o fallback propriedade para "none" para impedir que os arquivos de arquivo sejam armazenados na nuvem da OpenTok caso o upload falhe. Defina a propriedade como "opentok" para que o arquivo fique disponível no painel do OpenTok caso o upload falhe. Defina o certificate propriedade para null.

Respostas da API REST

Uma resposta com o código de status 200 indica que a desativação da criptografia foi bem-sucedida.

Uma resposta com o código de status 400 indica que você incluiu dados JSON inválidos ou que não especificou o destino do upload.

Uma resposta com o código de status 403 indica que você inseriu uma chave de API ou um segredo de parceiro inválido do projeto OpenTok.

Exemplo

O exemplo de linha de comando a seguir desativa o arquivamento criptografado para um destino S3:

api_key=12345 data='"type": "s3","config": {"bucket": "your-s3-bucket","secretKey": "your-s3-secret-key","accessKey": "your-s3-access-key"},{"certificate" : null}' curl \ -i \ -H "Content-Type:application/json" \ -X PUT -H "X-OPENTOK-AUTH:$json_web_token" -d "$data" \ https://api.opentok.com/v2/project/$api_key/archive/storage

Defina o valor para api_key à sua chave da API do OpenTok. Defina o valor para json_web_token para um token JSON da Web. Defina os valores para your-s3-bucket e your-s3-access-key para corresponder às suas credenciais do Amazon S3.

Problema conhecido

A duração de um arquivo criptografado é sempre informada como 0, em todas as chamadas da API REST do OpenTok, nos métodos dos SDKs do servidor OpenTok e nos callbacks de alteração de status do arquivo.