aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorHubert Chathi <hubert@uhoreg.ca>2019-08-22 04:30:45 +0000
committerHubert Chathi <hubert@uhoreg.ca>2019-08-22 04:30:45 +0000
commit57b6839c2574c9bcfd0ba2e1bef4996e07fc8045 (patch)
tree019dbaa5c69350e0ca18d32de737183df3294ae8 /docs
parente267825bb73517f3dd7c99880ff2fab96264552a (diff)
parent32f3a82bf9b9132c0eec70c5abaaac78cf53f6c6 (diff)
Merge branch 'rav/megolm_doc_format' into 'master'
Update megolm.md See merge request matrix-org/olm!6
Diffstat (limited to 'docs')
-rw-r--r--docs/megolm.md33
1 files changed, 17 insertions, 16 deletions
diff --git a/docs/megolm.md b/docs/megolm.md
index ec98001..eaae7e0 100644
--- a/docs/megolm.md
+++ b/docs/megolm.md
@@ -69,8 +69,8 @@ R_{i,3} &=
where $`H_0`$, $`H_1`$, $`H_2`$, and $`H_3`$ are different hash
functions. In summary: every $`2^8`$ iterations, $`R_{i,3}`$ is
-reseeded from $`R_{i,2}`$. Every $`2^16`$ iterations, $`R_{i,2}`$
-and $`R_{i,3}`$ are reseeded from $`R_{i,1}`$. Every $`2^24`$
+reseeded from $`R_{i,2}`$. Every $`2^{16}`$ iterations, $`R_{i,2}`$
+and $`R_{i,3}`$ are reseeded from $`R_{i,1}`$. Every $`2^{24}`$
iterations, $`R_{i,1}`$, $`R_{i,2}`$ and $`R_{i,3}`$ are reseeded
from $`R_{i,0}`$.
@@ -119,26 +119,27 @@ copy of the counter, ratchet, and public key.
### Message encryption
-This version of Megolm uses AES-256_ in CBC_ mode with [PKCS#7][] padding and
-HMAC-SHA-256_ (truncated to 64 bits). The 256 bit AES key, 256 bit HMAC key,
+This version of Megolm uses [AES-256][] in [CBC][] mode with [PKCS#7][] padding and
+[HMAC-SHA-256][] (truncated to 64 bits). The 256 bit AES key, 256 bit HMAC key,
and 128 bit AES IV are derived from the megolm ratchet $`R_i`$:
```math
\begin{aligned}
-AES\_KEY_{i}\;\parallel\;HMAC\_KEY_{i}\;\parallel\;AES\_IV_{i}
- &= HKDF\left(0,\,R_{i},\text{"MEGOLM\_KEYS"},\,80\right) \\
+ \mathit{AES\_KEY}_{i}\;\parallel\;\mathit{HMAC\_KEY}_{i}\;\parallel\;\mathit{AES\_IV}_{i}
+ &= \operatorname{HKDF}\left(0,\,R_{i},\text{"MEGOLM\_KEYS"},\,80\right) \\
\end{aligned}
```
where $`\parallel`$ represents string splitting, and
-$`HKDF\left(salt,\,IKM,\,info,\,L\right)`$ refers to the [HMAC-based key
+$`\operatorname{HKDF}\left(\mathit{salt},\,\mathit{IKM},\,\mathit{info},\,L\right)`$
+refers to the [HMAC-based key
derivation function][] using using [SHA-256][] as the hash function
-([HKDF-SHA-256][]) with a salt value of $`salt`$, input key material of
-$`IKM`$, context string $`info`$, and output keying material length of
+([HKDF-SHA-256][]) with a salt value of $`\mathit{salt}`$, input key material of
+$`\mathit{IKM}`$, context string $`\mathit{info}`$, and output keying material length of
$`L`$ bytes.
-The plain-text is encrypted with AES-256, using the key $`AES\_KEY_{i}`$
-and the IV $`AES\_IV_{i}`$ to give the cipher-text, $`X_{i}`$.
+The plain-text is encrypted with AES-256, using the key $`\mathit{AES\_KEY}_{i}`$
+and the IV $`\mathit{AES\_IV}_{i}`$ to give the cipher-text, $`X_{i}`$.
The ratchet index $`i`$, and the cipher-text $`X_{i}`$, are then packed
into a message as described in [Message format](#message-format). Then the entire message
@@ -160,14 +161,14 @@ described in [The Megolm ratchet algorithm](#the-megolm-ratchet-algorithm), usin
```math
\begin{aligned}
- H_0(A) &\equiv HMAC(A,\text{"\x00"}) \\
- H_1(A) &\equiv HMAC(A,\text{"\x01"}) \\
- H_2(A) &\equiv HMAC(A,\text{"\x02"}) \\
- H_3(A) &\equiv HMAC(A,\text{"\x03"}) \\
+ H_0(A) &\equiv \operatorname{HMAC}(A,\text{"\x00"}) \\
+ H_1(A) &\equiv \operatorname{HMAC}(A,\text{"\x01"}) \\
+ H_2(A) &\equiv \operatorname{HMAC}(A,\text{"\x02"}) \\
+ H_3(A) &\equiv \operatorname{HMAC}(A,\text{"\x03"}) \\
\end{aligned}
```
-where $`HMAC(A, T)`$ is the HMAC-SHA-256 of ``T``, using ``A`` as the
+where $`\operatorname{HMAC}(A, T)`$ is the HMAC-SHA-256 of ``T``, using ``A`` as the
key.
For outbound sessions, the updated ratchet and counter are stored in the