エンド・ツー・エンドの暗号化
重要な注意事項
- OpenTok.js 2.27.0+ では、以前のバージョンの OpenTok.js を使用しているクライアントに接続する場合、エンドツーエンドの暗号化は機能しません。OpenTok.js 2.27.0+ を使用するようにアプリをアップグレードする際、アプリがエンドツーエンド暗号化を使用する場合は、すべてのクライアントが OpenTok.js 2.27.0+ を使用していることを確認してください。
- WebKitベースのブラウザ(例:macOS/iOS版のSafariやiOS版のChromeなど)でサポートされているエンドツーエンド暗号化は、OpenTok.js バージョン2.30.0以降でのみ利用可能です。
このトピックでは、OpenTok.js Vonage Video Client SDK におけるエンドツーエンド暗号化の使用方法について詳しく説明しています:
- コンテンツセキュリティポリシー(CSP)に関する注意事項
- シークレットを使用したセッションの初期化
- デバイスがエンドツーエンド暗号化に対応しているかを確認する
- 秘密の変更
- イベントとエラー
- エンドツーエンド暗号化なしのセッションでシークレットを設定する
エンドツーエンド暗号化の概要については、以下を参照してください。 本題.
コンテンツセキュリティポリシー(CSP)に関する注意事項
もし script-src ディレクティブが設定されていることを確認してください。 'wasm-unsafe-eval' が指定されている。そうでない場合、エンドツーエンドの暗号化に必要なWebAssemblyは、ページ上での読み込みと実行がブロックされます。
シークレットを使用したセッションの初期化
エンドツーエンド暗号化されたセッションは、サーバーAPIを使用して作成されます(参照: REST APIを使用して暗号化を有効にする).ウェブクライアントがエンドツーエンドで暗号化されたセッションに参加するには OT.initSession() メソッドを使用する:
const session = OT.initSession(
'api-key',
'session-id',
{
encryptionSecret: 'initialEncryptionSecret'
}
});
有効な秘密は8文字以上256文字以下の文字列である。秘密は後で Session.setEncryptionSecret() メソッド 秘密の変更以下同様)。
ブラウザがエンドツーエンド暗号化に対応しているかを確認する
を使用する。 OT.hasEndToEndEncryptionSupport() メソッドを使用して、クライアントのブラウザがエンドツーエンドの暗号化をサポートしているかどうかをチェックします:
if (OT.hasEndToEndEncryptionSupport()) {
// Proceed with connecting to the session
}
else {
// Notify the user that they cannot join the session
}
秘密の変更
シークレットは Session.setEncryptionSecret() メソッドを呼び出す:
await session.setEncryptionSecret('newEncryptionSecret');
セッションでエンドツーエンド暗号化が有効になっていない場合、シークレットを設定すると、 OT_ENCRYPTION_NOT_ENABLED エラー。参照: エンドツーエンド暗号化なしのセッションでシークレットを設定する.
イベントとエラー
イベントとエラーは、ユーザー主導の暗号化の動作を管理するために不可欠である。エンドツーエンドの暗号化は、共有秘密モデルを使用します。セッション内の全員が、自分のメディアを暗号化し、他の全員のメディアを復号化するために、同じ秘密を使用することが期待されています。
サブスクライバオブジェクトは encryptionSecretMismatch イベントは、加入者がストリームのメディアをデコードできないときに発生する。接続障害やオーディオ/ビデオのバグが原因ではなく、暗号化の不一致が原因でメディ アが受信できないことをユーザーに伝えることが重要である:
subscriber.on('encryptionSecretMismatch', () => {
// Activate a UI element communicating that there's been an encryption secret mismatch.
});
また、暗号化が正常に有効化されたことをユーザーに伝えることも重要です。Subscriber オブジェクトは、 encryptionSecretMatch 以前の不一致の後、サブスクライバーがストリームのメディアをデコードできるようになった際に発生するイベント。
subscriber.on('encryptionSecretMatch', () => {
// Activate a UI element communicating that the media is being properly decrypted.
});
について Session.connect() クライアントが無効な暗号化シークレットで初期化されたエンドツーエンド暗号化セッションに接続しようとすると、エラーとともにコールバックが呼び出されます。有効なシークレットは、8文字から256文字の文字列です。最適なユーザー体験を実現するため、アプリケーションは、OT.initSession() メソッドを使用します。以下の例では、セッションが空の(つまり無効な)secretで初期化され、接続時にエラーが発生します:
const session = OT.initSession(
'api-key',
'e2ee-session-id',
{
encryptionSecret: '',
}
)
session.connect('token', (error) => {
if (error && error.name === 'OT_INVALID_ENCRYPTION_SECRET') {
/*
The application should communicate that the secret was invalid.
*/
}
});
について Session.connect() コールバックは、エンドツーエンド暗号化をサポートしていないブラウザでエンドツーエンド暗号化セッションに接続しようとすると、エラーとともに呼び出されます。
const session = OT.initSession(
'api-key',
'e2ee-session-id',
{
encryptionSecret: 'validEncryptionSecret',
}
)
session.connect('token', (error) => {
if (error && error.name === 'OT_UNSUPPORTED_BROWSER') {
/*
The error will have the message 'Tried to connect an e2ee session but the browser does not support e2ee'
The application should communicate that the browser does not support encryption.
*/
}
});
ユーザーが暗号化シークレットを指定せずにエンドツーエンドで暗号化されたセッションで公開しようとすると Session.publish() コールバックはエラーで呼び出される。最高のユーザーエクスペリエンスを得るためには、アプリケーションは session.publish() メソッドを使用する:
session.publish(publisher, (error) => {
if (error && error.name === 'OT_STREAM_CREATE_FAILED') {
/*
The error will have the message 'Tried to publish to an e2ee session but encryption secret was not set'
The application should communicate that the secret was not set.
*/
}
});
もしユーザーが暗号化シークレットを指定せずにエンドツーエンドで暗号化されたセッションに参加しようとした場合、次のようになる。 Session.subscribe() コールバックはエラーで呼び出される。最高のユーザーエクスペリエンスを得るためには、アプリケーションは Session.subscribe() メソッドを使用する:
subscriber = session.subscribe(stream, target, opts, (error) => {
if (error && error.name === 'OT_UNABLE_TO_SUBSCRIBE') {
/*
The error will have the message 'Tried to subscribe to an e2ee stream but encryption secret was not set'
The application should communicate that the secret was not set.
*/
}
});
エンドツーエンド暗号化なしのセッションでシークレットを設定する
注: この機能は、SDK バージョン 2.36.0 以降で利用可能です。
エンドツーエンド暗号化が有効な状態でセッションが作成されなかった場合、そのセッションに暗号化シークレットを設定すると、 OT_ENCRYPTION_NOT_ENABLED エラー。エラーが発生する場所は、接続、公開、および購読に対して、シークレットがいつ設定されたかによって異なります。
注: このセクションのシナリオでは、クライアントのブラウザがエンドツーエンド暗号化に対応していることを前提としています。対応していないブラウザでエンドツーエンド暗号化を使用すると、 OT_UNSUPPORTED_BROWSER 代わりにエラーが発生します。詳しくは ブラウザがエンドツーエンド暗号化に対応しているかを確認する そして イベントとエラー.
接続前にシークレットを設定する
接続する前に秘密鍵が設定されている場合( encryptionSecret ~の選択肢 OT.initSession() またはお電話にて Session.setEncryptionSecret() — セッションの接続に成功しました。エラーは Session.publish() そして Session.subscribe() コールバック:
// Option 1: set the secret when initializing the session
const session = OT.initSession('api-key', 'non-e2ee-session-id', {
encryptionSecret: 'encryptionSecret',
});
// Option 2: set the secret before connecting
// await session.setEncryptionSecret('encryptionSecret');
session.connect('token', (error) => {
if (error) {
return;
}
session.publish(publisher, (error) => {
if (error && error.name === 'OT_ENCRYPTION_NOT_ENABLED') {
/*
The application should communicate that end-to-end encryption
is not enabled for this session.
*/
}
});
session.subscribe(stream, target, opts, (error) => {
if (error && error.name === 'OT_ENCRYPTION_NOT_ENABLED') {
// Same handling as for the publisher.
}
});
});
接続後にシークレットを設定する
もし Session.setEncryptionSecret() セッションの接続完了後にこのメソッドが呼び出されると、このメソッドはエラーを返して呼び出しを拒否します。その後の Session.publish() または Session.subscribe() また、そのコールバック内でエラーを返します:
session.connect('token', async (error) => {
if (error) {
return;
}
try {
await session.setEncryptionSecret('encryptionSecret');
} catch (error) {
if (error.name === 'OT_ENCRYPTION_NOT_ENABLED') {
/*
The application should communicate that end-to-end encryption
is not enabled for this session.
*/
}
}
});
公開または購読時のシークレットの設定
もし Session.setEncryptionSecret() クライアントがすでにパブリッシュまたはサブスクライブを行っている状態でこのメソッドが呼び出されると、メソッドはエラーを返して処理を拒否し、アクティブなすべての Publisher および Subscriber オブジェクトが encryptionNotEnabled イベント。その後、SDKはそれらのパブリッシャーとサブスクライバーを自動的に停止するため、 Session.unpublish() または Session.unsubscribe():
publisher.on('encryptionNotEnabled', (event) => {
// The publisher is stopped by the SDK. No need to call session.unpublish().
});
subscriber.on('encryptionNotEnabled', (event) => {
// The subscriber is stopped by the SDK. No need to call session.unsubscribe().
});
try {
await session.setEncryptionSecret('encryptionSecret');
} catch (error) {
if (error.name === 'OT_ENCRYPTION_NOT_ENABLED') {
// An encryptionNotEnabled event is also dispatched on every
// active publisher and subscriber (handled above).
}
}
エラーからの復旧
これらのエラーが発生しても、セッションは有効なままです。再度パブリッシュまたはサブスクライブするには、以下を呼び出してシークレットをクリアしてください。 Session.setEncryptionSecret() と null. その後、その同じ Publisher オブジェクトを Session.publish() 再び
await session.setEncryptionSecret(null);
session.publish(publisher, (error) => {
// Publishing proceeds without end-to-end encryption.
});