diff --git a/docs/olm.rst b/docs/olm.rst index 30d2146..78c9731 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -16,7 +16,8 @@ The setup takes four Curve25519 inputs: Identity keys for Alice and Bob, :math:`E_A` and :math:`E_B`. A shared secret, :math:`S`, is generated using Triple Diffie-Hellman. The initial 256 bit root key, :math:`R_0`, and 256 bit chain key, :math:`C_{0,0}`, are derived from the shared secret using an -HMAC-based Key Derivation Function (HKDF) with default salt. +HMAC-based Key Derivation Function (HKDF) with default salt and ``"OLM_ROOT"`` +as the info. .. math:: \begin{align} @@ -34,7 +35,7 @@ ratchet key :math:`T_i`. The even ratchet keys are generated by Alice. The odd ratchet keys are generated by Bob. A shared secret is generated using Diffie-Hellman on the ratchet keys. The next root key, :math:`R_i`, and chain key, :math:`C_{i,0}`, are derived from the shared secret using an HKDF -using :math:`R_{i-1}` as the salt. +using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the info. .. math:: \begin{align} @@ -224,6 +225,18 @@ Olm Authenticated Encryption Version 1 ~~~~~~~~~ -Version 1 of Olm uses AES-256 in CBC mode for encryption and HMAC-SHA-256 for -authentication. The 256 bit AES key, 256 bit HMAC key, and 128 bit AES IV are -derived from the message key using HKDF. +Version 1 of Olm uses AES-256 in CBC mode with PCKS#7 padding for encryption +and HMAC-SHA-256 for authentication. The 256 bit AES key, 256 bit HMAC key, +and 128 bit AES IV are derived from the message key using HKDF-SHA-256 using +the default salt and an info of ``"OLM_KEYS"``. + +First the plain-text, :math:`P_{i,j}`, is encrypted to get the cipher-text +:math:`X_{i,j}`. Then the entire message, both the headers and cipher-text, +are HMAC'd and the MAC is appended to the message. + +.. math:: + + \begin{align} + AES\_KEY_{i,j}\;\parallel\;HMAC\_KEY_{i,j}\;\parallel\;AES\_IV_{i,j} + &= HKDF\left(M_{i,j},\,\text{"OLM\_RATCHET"}\right) \\ + \end{align}