###########################################
Sora E2EE ライブラリ
###########################################

.. warning:: Sora E2EE ライブラリは現時点で実験的機能として提供しています。

:URL: https://github.com/shiguredo/sora-e2ee

概要
====

WebRTC SFU Sora 利用時に E2EE をブラウザで実現するためのライブラリです。
これ単体では利用できず Sora JS SDK と組み合わせて利用します。

メディアフレームの暗号化と複合以外はすべて Go から生成した WebAssembly バイナリを利用して行っています。

WebAssembly バイナリは Go の `syscall/js <https://golang.org/pkg/syscall/js/>`_ を利用して生成しています。

機能
====

- X3DH の処理

  - X25519 鍵ペアの生成
  - Ed25519 鍵ペアの生成
  - Ed25519 から X25519 鍵の生成
- Dobule Ratchet の処理

  - AES-GCM での暗号化 / 復号
- 公開鍵の管理
- 共通鍵の管理
- 共通鍵の更新
- 鍵交換メッセージの生成
- 鍵共有メッセージの生成
- 鍵交換メッセージの処理
- 鍵共有メッセージの処理

利用技術
========

- `WebAssembly <https://webassembly.org/>`_
- Go "syscall/js"

  - `js - The Go Programming Language <https://golang.org/pkg/syscall/js/>`_
- The X3DH Key Agreement Protocol

  - `Signal >> Specifications >> The X3DH Key Agreement Protocol <https://signal.org/docs/specifications/x3dh/>`_
- The Double Ratchet Algorithm

  - `Signal >> Specifications >> The Double Ratchet Algorithm <https://signal.org/docs/specifications/doubleratchet/>`_

メッセージプロトコル
====================

- WebRTC SFU Sora のシグナリングの WebSocket 経由で送られます
- Connection ID は `Clockwork Base32 <https://gist.github.com/szktty/228f85794e4187882a77734c89c384a8>`_ の文字列をそのまま利用しています

メッセージヘッダー仕様
======================

.. code-block:: erlang

    -define(E2EE_PRE_KEY_MESSAGE_TYPE, 0).
    -define(E2EE_CIPHER_MESSAGE_TYPE,  1).

    <<MessageType:8, Reserved:8, CiphertextLength:16>>.

PreKey メッセージ仕様
-----------------------

.. code-block:: erlang

    <<?E2EE_PRE_KEY_MESSAGE_TYPE:8, 0:8, 0:16,
      SrcConnectionId:26/binary, DstConnectionId:26/binary,
      IdentityKey:32/binary, EphemeralKey:32/binary>>.

Cipher メッセージ仕様
-----------------------

.. code-block:: erlang

    <<?E2EE_CIPHER_MESSAGE_TYPE:8, 0:8, CiphertextLength:16,
      SrcConnectionId:26/binary, DstConnectionId:26/binary,
      %% ここは CipherMessage ヘッダー
      RachetPublicKey:32/binary, N:32, NP:32,
      %% 本体
      Ciphertext:CiphertextLength/binary>>.

Ciphertext 仕様
---------------

.. code-block:: erlang

    <<KeyId:32, SecretkeyMaterial:32/binary>>.

利用方法
========

.. code-block:: javascript

    // E2EE の状態を初期化します
    e2ee.init();

    // 自分の ConnectionID をわたして E2EE を開始します
    e2ee.start(selfConnectionId);

    // シグナリングキーで送られてきた参加した端末の Connection ID と PreKey バンドルをわたします
    e2ee.startSession(remoteConnectionId, remoteIdentityKey, remoteSignedPreKey, remotePreKeySignature);

    // シグナリング経由で送られてきたバイナリメッセージをわたします
    e2ee.receiveMessage(message);

    // シグナリング経由で送られてきた離脱した端末の Connection ID をわたします
    e2ee.stopSession(remoteConnectionId);

    // シグナリング経由で送られてきた PreKey バンドルを登録します
    e2ee.addPreKeyBundle(remoteIdentityKey, remoteSignedPreKey, remotePreKeySignature)

    // シグナリングで送られてきた参加者の IdentityKey の Fingerprint を返します
    e2ee.remoteFingerprints()

    // 自分の IdentityKey の Fingerprint を返します
    e2ee.selfFingerprint()

    // ライブラリのバージョンを返します
    e2ee.version()