Verschlüsselung der Vonage Video API

Mit der OpenTok-Verschlüsselung können Sie OpenTok-Archive erstellen, in denen die Daten niemals unverschlüsselt gespeichert werden.

Sie können Ihre OpenTok-Archive auf folgende Weise sichern:

Archivspeicher-Ausweichlösung deaktivieren — Standardmäßig speichert Vonage eine Archivdatei auf OpenTok-Servern, wenn das Hochladen der Datei auf den von Ihnen angegebenen Amazon S3- oder Microsoft Azure-Server nicht möglich war. Sie können diese Ausweichspeicherung verhindern, indem Sie die OpenTok-REST-API verwenden, um das Ziel für den Archiv-Upload festzulegen.
Verwenden Sie die OpenTok-Verschlüsselung – damit können Sie OpenTok- Archive erstellen, in denen die Daten niemals unverschlüsselt gespeichert werden. Dies gewährleistet ein Höchstmaß an Sicherheit.
Verwenden Sie die serverseitige Verschlüsselung von Amazon S3 – Dabei werden von Amazon S3 verwaltete Verschlüsselungsschlüssel zur Verschlüsselung verwendet. Weitere Informationen finden Sie unter dieses Entwicklerhandbuch.

Mit der OpenTok-Verschlüsselung werden Video- und Audiodaten in einem OpenTok- Archiv mithilfe eines öffentlichen Schlüsselzertifikats verschlüsselt, das Sie Vonage zur Verfügung stellen.

Das ist wichtig: Die OpenTok-Verschlüsselungsfunktion ist als Add-on-Feature. Kontakt um diese Funktion für Ihre OpenTok-Projektschlüssel zu aktivieren.

Überblick über die Funktionen

Mit der Funktion zur verschlüsselten Archivierung der OpenTok-Plattform können Sie Archive erstellen, bei denen die Daten zu keinem Zeitpunkt unverschlüsselt gespeichert werden.

Erstellen Sie zunächst ein öffentliches und ein privates RSA-Schlüsselpaar für die Verwendung mit Ihren OpenTok-Archiven. Über einen OpenTok-REST-API-Aufruf geben Sie das Zertifikat des öffentlichen Schlüssels an Vonage weiter. (Im selben REST-Aufruf übermitteln Sie Angaben zum Amazon S3- oder Microsoft Azure-Upload-Ziel, das für Ihre Archive verwendet werden soll. Für die verschlüsselte Archivierungsfunktion müssen Sie ein Upload-Ziel festlegen.) Den privaten Schlüssel speichern Sie lokal für Ihre Nur für den privaten Gebrauch.

Vonage verschlüsselt anschließend jedes Archiv mit einem zufällig generierten Passwort, verschlüsselt es mit dem Zertifikat und speichert das verschlüsselte Passwort auf unseren Servern. Sobald das Archiv fertig ist, werden Sie über einen Rückruf an Ihren Server benachrichtigt und können das Passwort abfragen. Vonage speichert zu keinem Zeitpunkt das unverschlüsselte Passwort, und Vonage hat keine Möglichkeit, das Passwort zu entschlüsseln (nur der Besitzer des privaten Schlüssels kann das Passwort entschlüsseln).

Anschließend können Sie das Passwort mit dem privaten Schlüssel entschlüsseln und das Passwort verwenden, um das verschlüsselte Archiv zu entschlüsseln. Die entschlüsselte Archivdatei liegt im MPEG-TS-Format vor.

Vonage verwendet den AES-256-Algorithmus zur Verschlüsselung des Archivs. Das generierte Passwort wird mithilfe der RSA-Verschlüsselung mit OAEP-Padding verschlüsselt. Beachten Sie, dass Sie die verschlüsselte Archivierung nur bei zusammengesetzten Archiven verwenden können, nicht jedoch bei einzelnen Stream- Archiven.

Dieses Dokument umfasst die folgenden Abschnitte:

Erstellung eines verschlüsselten Archivierungszertifikats

Das verschlüsselte Archivierungszertifikat an Vonage senden

Entschlüsseln eines Archivs

Deaktivieren der verschlüsselten Archivierung

Bekannte Probleme

Erstellung eines verschlüsselten Archivierungszertifikats

Erstellen Sie ein X.509-PEM-Zertifikat und einen entsprechenden privaten Schlüssel zur Verwendung mit Ihren Archiven:

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

(Hinweis: Dies wurde mit OpenSSL 1.0.1 getestet).

Sie senden das Zertifikat an Vonage, das damit ein verschlüsseltes Passwort generiert, das zum Entschlüsseln des Archivs benötigt wird. Das Passwort kann mit Ihrem privaten Schlüssel entschlüsselt werden, und das Archiv kann mit dem Passwort entschlüsselt werden. Das Passwort ist für jedes Archiv unterschiedlich.

Die Größe des Schlüssels muss 2048 Bit oder weniger betragen. Sie senden das Zertifikat als JSON-Daten an die OpenTok-REST-API, um das Archivziel festzulegen (siehe nächsten Abschnitt). Da das Zertifikat in den JSON-Daten enthalten ist, senden Sie die Daten in Base64-Kodierung oder ersetzen Sie Zeilenumbruchzeichen im Zertifikat durch „\n“.

Im folgenden Beispiel wird das Zertifikat in Base64 kodiert:

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

Eine Base64-kodierte Zertifikatszeichenfolge sieht wie folgt aus:

"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0..."

Eine Zertifikatszeichenfolge, in der Zeilenumbruchzeichen ersetzt wurden, sieht wie folgt aus:

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

Übermittlung des verschlüsselten Archivierungszertifikats an Vonage

Um das Zertifikat einzurichten und die Archivverschlüsselung zu aktivieren, senden Sie eine HTTP-PUT-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-Projekt-API-Schlüssel.

Authentifizieren Sie die REST-API-Anfrage mithilfe eines benutzerdefinierten HTTP-Headers: X-OPENTOK-AUTH. Legen Sie hierfür ein JSON-Web-Token fest (siehe die Dokumentation zur OpenTok-REST-API ):

X-OPENTOK-AUTH: <JSON_web_token>

Erstellen Sie das JSON-Web-Token mit den folgenden Angaben:

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

Satz iss zu Ihrem OpenTok-API-Schlüssel (den Sie in Ihrer Vonage Account auf der Seite Projekt).
Satz ist zu "Projekt".
Satz iat zum aktuellen Unix-Epochen-Zeitstempel (zum Zeitpunkt der Erstellung des Tokens), in Sekunden.
Satz exp bis zum Ablauf des Tokens. Aus Sicherheitsgründen empfehlen wir Ihnen, eine Ablaufzeit zu wählen, die nahe am Zeitpunkt der Token-Erstellung liegt (zum Beispiel 3 Minuten nach der Erstellung), und für jeden REST-API-Aufruf ein neues Token zu erstellen. Der maximal zulässige Ablaufzeitraum beträgt 5 Minuten.
Satz jti auf einen eindeutigen Bezeichner für das JWT. Dies ist optional. Siehe die JSON Web-Token-Spezifikation für Einzelheiten.

Verwenden Sie Ihren OpenTok-Projekt-API-Schlüssel als JWT-Geheimschlüssel und signieren Sie diesen mit dem HMAC-SHA256-Verschlüsselungsalgorithmus. (Ihr API-Schlüssel wird Ihnen in Ihrer Video API-Konto (auf der Projektseite.)

Der folgende Python-Code erstellt beispielsweise ein Token, das in einem OpenTok-REST-API-Aufruf verwendet werden kann:

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')

Ersetzen Sie my-OpenTok-project-API-key und my-OpenTok-project-API-secret mit dem API-Schlüssel und dem Geheimcode des OpenTok-Projekts.

Setzen Sie die Content-type Header für den REST-API-Aufruf an application/json:

Content-Type:application/json

Ersetzen Sie die Zeilenumbruchzeichen im Zertifikat durch "\n", damit Sie es im String-Literal in den JSON-Daten verwenden können.

Übergeben Sie das Zertifikat des öffentlichen Schlüssels als Eigenschaft der JSON-Daten, die Sie beim Aufruf der REST-Methode zum Einrichten des Archivspeichers senden.

Siehe die folgenden Abschnitte.

Einrichten der verschlüsselten Archivierung für ein Amazon S3-Ziel

Um ein Zertifikat mit öffentlichem Schlüssel für die Verwendung mit einem Amazon S3-Ziel anzugeben, müssen Sie die JSON-Daten im REST-API-Aufruf so formatieren, dass sie das folgende Format verwenden:

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

Satz bucket auf den Namen des Amazon S3-Buckets, den Sie für den Archiv-Upload verwenden möchten. Legen Sie den secretKey und accessKey Eigenschaften des Amazon S3-Geheimschlüssels und des Zugriffsschlüssels für diesen Bucket.

Setzen Sie die Fallback-Eigenschaft auf "none" um zu verhindern, dass Archivdateien in der OpenTok-Cloud gespeichert werden, falls der Upload fehlschlägt. Setzen Sie die Eigenschaft auf "opentok" damit das Archiv im OpenTok-Dashboard verfügbar ist, falls der Upload fehlschlägt.

Legen Sie die Zertifikats-Eigenschaft auf das Zertifikat mit dem öffentlichen Schlüssel fest, das Vonage zur Verschlüsselung des Archivs verwendet. Achten Sie darauf, das Zertifikat in Base64 zu kodieren oder Zeilenumbruchzeichen im Zertifikat durch "\n", damit Sie es im String-Literal in den JSON-Daten verwenden können.

Einrichten der verschlüsselten Archivierung für ein Microsoft Azure-Ziel

Um ein Zertifikat mit öffentlichem Schlüssel für die Verwendung mit einem Microsoft Azure-Ziel anzugeben, müssen Sie die JSON-Daten im REST-API-Aufruf so einstellen, dass sie das folgende Format verwenden:

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

Stellen Sie den Container so ein, dass er dem Namen Ihres Microsoft Azure-Containers entspricht. Setzen Sie die accountName und accountKey Eigenschaften mit Ihren Microsoft Azure-Speicheranmeldeinformationen übereinstimmen.

Setzen Sie die fallback Eigenschaft zu "none" um zu verhindern, dass Archivdateien in der OpenTok-Cloud gespeichert werden, falls der Upload fehlschlägt. Setzen Sie die Eigenschaft auf "opentok" damit das Archiv im OpenTok-Dashboard verfügbar ist, falls der Upload fehlschlägt.

Setzen Sie die certificate Eigenschaft des öffentlichen Schlüsselzertifikats, das Vonage zur Verschlüsselung des Archivs verwendet. Achten Sie darauf, das Zertifikat in Base64 zu kodieren oder Zeilenumbruchzeichen im Zertifikat durch "\n", damit Sie es im String-Literal in den JSON-Daten verwenden können. Eine Base64-kodierte Zertifikatszeichenfolge sieht wie folgt aus:

"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0..."

REST-API-Antworten

Eine Antwort mit dem Statuscode 200 zeigt den Erfolg an.

Eine Antwort mit dem Statuscode 400 bedeutet, dass Sie ungültige JSON-Daten angegeben haben oder dass Sie das Upload-Ziel nicht angegeben haben.

Eine Antwort mit dem Statuscode 403 bedeutet, dass Sie einen ungültigen OpenTok-Projekt-API-Schlüssel oder ein ungültiges API-Geheimnis übergeben haben.

Beispiele

Das folgende Befehlszeilenbeispiel legt das Zertifikat sicher fest, das Vonage bei der Verschlüsselung von Archiven verwenden soll, die in einen Amazon S3-Bucket hochgeladen werden sollen:

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

Legen Sie den Wert für api_key auf Ihren OpenTok-Projekt-API-Schlüssel. Legen Sie den Wert für json_web_token in ein JSON-Web-Token.

Legen Sie die Werte für your-s3-bucket und your-s3-access-key so, dass sie mit Ihren Amazon S3-Anmeldedaten übereinstimmen. Ersetzen Sie den Wert für das Zertifikat durch die Zertifikatszeichenfolge.

Das folgende Beispiel für eine Befehlszeile legt sicher das Zertifikat fest, das Vonage bei der Verschlüsselung von Archiven verwenden soll, die in einen Microsoft Azure-Bucket hochgeladen werden sollen:

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

Legen Sie den Wert für api_key für Ihren OpenTok-Projekt-API-Schlüssel. Legen Sie den Wert für json_web_token in ein JSON-Web-Token.

Legen Sie die Werte für your-azure-account-name, your-azure-account-name, und your-azure-container damit diese mit Ihren Amazon S3-Anmeldedaten übereinstimmen. Ersetzen Sie den Wert „Zertifikat“ durch die Zertifikatszeichenfolge.

Entschlüsseln eines Archivs

Sie können über das OpenTok-Dashboard einen Callback für den Archivierungsstatus einrichten. Siehe „Änderungen des Archivierungsstatus“ im OpenTok-Archivierung – Entwicklerhandbuch.

Nachdem das Archiv erstellt wurde, enthalten die POST-Anfragen zum Archivstatus an Ihre Callback-URL eine Eigenschaft „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"
}

Das Passwort besteht aus einem zertifikatsverschlüsselten AES-Schlüssel und einem Initialisierungsvektor in Form von Base64-kodierten Binärdaten.

Die ersten drei Bytes der Binärdaten stehen für die Version (ein Byte), den Algorithmus (ein Byte) und den Modus (ein Byte). In dieser Version ist die Länge auf 1 gesetzt, der Algorithmus auf 1 (was AES-256 bedeutet) und der Modus auf 1 (was CBC bedeutet).

Die nächsten 32 Bytes bilden den Schlüssel. Die verbleibenden 16 Bytes bilden den Initialisierungsvektor.

Entschlüsseln Sie zunächst das Passwort und entschlüsseln Sie es anschließend mit Ihrem privaten Schlüssel:

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

Verwenden Sie dann das Passwort, um die Archivdatei zu entschlüsseln:

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 ist der Schlüssel

-iv ist der Initialisierungsvektor

xxd Wandelt das binär dekodierte und entschlüsselte Passwort in Hexadezimalzahlen um, damit es an OpenSSL übergeben werden kann. Weitere Informationen zu den Optionen finden Sie in der xxd-Manpage.

Deaktivieren der verschlüsselten Archivierung

Um die verschlüsselte Archivierung zu deaktivieren, senden Sie eine HTTP-PUT-Anfrage an die URL des Archivspeichers (siehe Das verschlüsselte Archivierungszertifikat an Vonage senden), aber setzen Sie das Zertifikat in den JSON-Daten, die Sie mit der Anfrage senden, auf „null“.

Deaktivieren der verschlüsselten Archivierung für ein Amazon S3-Ziel

Um ein Zertifikat mit öffentlichem Schlüssel für ein Amazon S3-Archivziel zu entfernen (und die Verschlüsselung der Archive aufzuheben), rufen Sie die REST-API mit den folgenden JSON-Daten auf:

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

Setzen Sie die fallback Eigenschaft to "none" um zu verhindern, dass Archivdateien in der OpenTok-Cloud gespeichert werden, falls der Upload fehlschlägt. Setzen Sie die Eigenschaft auf "opentok" damit das Archiv im OpenTok-Dashboard verfügbar ist, falls der Upload fehlschlägt.

Setzen Sie die certificate Eigenschaft auf Null.

Deaktivieren der verschlüsselten Archivierung für ein Microsoft Azure-Ziel

Um ein Zertifikat mit öffentlichem Schlüssel für ein Microsoft Azure-Archiv zu entfernen (und die Verschlüsselung der Archive aufzuheben), rufen Sie die REST-API mit den folgenden JSON-Daten auf:

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

Satz container entsprechend Ihrem Microsoft Azure-Containernamen. Legen Sie den accountName und accountKey Eigenschaften mit Ihren Microsoft Azure-Speicheranmeldeinformationen übereinstimmen. Legen Sie die fallback Eigenschaft zu "none" um zu verhindern, dass Archivdateien in der OpenTok-Cloud gespeichert werden, falls der Upload fehlschlägt. Setzen Sie die Eigenschaft auf "opentok" damit das Archiv im OpenTok-Dashboard verfügbar ist, falls der Upload fehlschlägt. Legen Sie die certificate Eigenschaft zu null.

REST-API-Antworten

Eine Antwort mit dem Statuscode 200 zeigt an, dass die Deaktivierung der Verschlüsselung erfolgreich war.

Eine Antwort mit dem Statuscode 400 bedeutet, dass Sie ungültige JSON-Daten angegeben haben oder dass Sie das Upload-Ziel nicht angegeben haben.

Eine Antwort mit dem Statuscode 403 bedeutet, dass Sie einen ungültigen OpenTok-Projekt-API-Schlüssel oder ein ungültiges Partner-Secret übergeben haben.

Beispiel

Das folgende Beispiel für eine Befehlszeile deaktiviert die verschlüsselte Archivierung für ein S3-Ziel:

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

Legen Sie den Wert für api_key für Ihren OpenTok-API-Schlüssel. Legen Sie den Wert für json_web_token in ein JSON-Web-Token. Legen Sie die Werte für your-s3-bucket und your-s3-access-key mit Ihren Amazon S3-Anmeldedaten übereinstimmen.

Bekanntes Problem

Die Dauer eines verschlüsselten Archivs wird stets mit 0 angegeben, und zwar bei allen OpenTok-REST-API-Aufrufen, in den Methoden der OpenTok-Server-SDKs sowie in Callbacks bei Änderungen des Archivstatus.