aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorMark Haines <mark.haines@matrix.org>2015-08-07 18:24:20 +0100
committerMark Haines <mark.haines@matrix.org>2015-08-10 17:12:03 +0100
commit9e79571d07ed1dac4445dff57a7077e265f3d06c (patch)
tree66956e357089be784bf0082e8ab92187334fe402 /docs
parent531a2fb4264b83788d7cadf64acccd7cfab4441f (diff)
Start specifying the message format
Diffstat (limited to 'docs')
-rw-r--r--docs/olm.rst44
1 files changed, 41 insertions, 3 deletions
diff --git a/docs/olm.rst b/docs/olm.rst
index db32cdb..8f1c612 100644
--- a/docs/olm.rst
+++ b/docs/olm.rst
@@ -8,9 +8,6 @@ https://github.com/trevp/axolotl/wiki.
The Olm Algorithm
-----------------
-.. figure:: Axolotl.svg
-
-
Initial setup
~~~~~~~~~~~~~
@@ -153,3 +150,44 @@ with :math:`C_{i,j+1}` and stores the message keys that were skipped in the
process so that they can decode out of order messages. If the receiver created
a new receiver chain then they discard their current sender chain so that
they will create a new chain when they next send a message.
+
+
+The Olm Message Format
+----------------------
+
+Normal Messages
+~~~~~~~~~~~~~~~
+
+Olm messages start with a one byte version followed by a variable length
+payload followed by a fixed length message authentication code.
+
+
+.. code::
+
+ +--------------+------------------------------------+-----------+
+ | Version Byte | Payload Bytes | MAC Bytes |
+ +--------------+------------------------------------+-----------+
+
+The payload consists of key-value pairs where the keys are integers and the
+values are integers and strings. The keys are encoded as a variable length
+integer tag where the 3 lowest bits indicates the type of the value:
+0 for integers, 2 for strings. If the value is an integer then the tag is
+followed by the value encoded as a variable length integer. If the value is
+a string then the tag is followed by the length of the string encoded as
+a variable length integer followed by the string itself.
+
+Olm uses a variable length encoding for integers. Each integer is encoded as a
+sequence of bytes with the high bit set followed by a byte with the high bit
+clear. The seven low bits of each byte store the bits of the integer. The least
+significant bits are stored in the first byte.
+
+=========== ===== ======== ================================================
+ Name Tag Type Meaning
+=========== ===== ======== ================================================
+Chain-Index 0x0A Integer The chain index, :math:`j`, of the message
+Ratchet-Key 0x10 String The ratchet key, :math:`T_{i}`, of the message
+Cipher-Text 0x22 String The cipher-text, :math:`X_{i,j}`, of the message
+=========== ===== ======== ================================================
+
+
+