diff options
| -rw-r--r-- | docs/olm.rst | 44 |
1 files changed, 27 insertions, 17 deletions
diff --git a/docs/olm.rst b/docs/olm.rst index 78c9731..1331a00 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -11,13 +11,13 @@ The Olm Algorithm Initial setup ~~~~~~~~~~~~~ -The setup takes four Curve25519 inputs: Identity keys for Alice and Bob, +The setup takes four Curve25519_ inputs: Identity keys for Alice and Bob, :math:`I_A` and :math:`I_B`, and emphemeral 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 and ``"OLM_ROOT"`` -as the info. +`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 using SHA-256_ as the hash function +(HKDF-SHA-256_) with default salt and ``"OLM_ROOT"`` as the info. .. math:: \begin{align} @@ -34,8 +34,9 @@ Curve25519 inputs: the previous ratchet key, :math:`T_{i-1}`, and the current 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 and ``"OLM_RATCHET"`` as the info. +chain key, :math:`C_{i,0}`, are derived from the shared secret using +HKDF-SHA-256_ using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the +info. .. math:: \begin{align} @@ -51,8 +52,8 @@ Advancing the chain key ~~~~~~~~~~~~~~~~~~~~~~~ Advancing a root key takes the previous chain key, :math:`C_{i,j-i}`. The next -chain key, :math:`C_{i,j}`, is the HMAC of ``"\x02"`` using the previous chain -key as the key. +chain key, :math:`C_{i,j}`, is the HMAC-SHA-256_ of ``"\x02"`` using the +previous chain key as the key. .. math:: \begin{align} @@ -63,9 +64,9 @@ Creating a message key ~~~~~~~~~~~~~~~~~~~~~~ Creating a message key takes the current chain key, :math:`C_{i,j}`. The -message key, :math:`M_{i,j}`, is the HMAC of ``"\x01"`` using the current -chain key as the key. The message keys where :math:`i` is even are used by -Alice to encrypt messages. The message keys where :math:`i` is odd are used +message key, :math:`M_{i,j}`, is the HMAC-SHA-256_ of ``"\x01"`` using the +current chain key as the key. The message keys where :math:`i` is even are used +by Alice to encrypt messages. The message keys where :math:`i` is odd are used by Bob to encrypt messages. .. math:: @@ -225,18 +226,27 @@ Olm Authenticated Encryption Version 1 ~~~~~~~~~ -Version 1 of Olm uses AES-256 in CBC mode with PCKS#7 padding for encryption +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. +First the plain-text 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) \\ + &= HKDF\left(M_{i,j},\,\text{"OLM\_KEYS"}\right) \\ \end{align} + +.. _`Curve25519`: http://cr.yp.to/ecdh.html +.. _`Triple Diffie-Hellman`: https://whispersystems.org/blog/simplifying-otr-deniability/ +.. _`HKDF-SHA-256`: https://tools.ietf.org/html/rfc5869 +.. _`HMAC-SHA-256`: https://tools.ietf.org/html/rfc2104 +.. _`SHA-256`: https://tools.ietf.org/html/rfc6234 +.. _`AES-256`: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf +.. _`CBC`: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf +.. _`PCKS#7`: https://tools.ietf.org/html/rfc2315 |