async-matrix 3.0.1 → 4.0.1

data/lib/async/matrix/e2ee/schema/content/olm-megolm/olm.md

@@ -0,0 +1,334 @@
+---
+title: "Olm: A Cryptographic Ratchet"
+weight: 10
+type: docs
+---
+
+An implementation of the double cryptographic ratchet described by
+https://signal.org/docs/specifications/doubleratchet/.
+
+## Notation
+
+This document uses \(\parallel\) to represent string concatenation. When
+\(\parallel\) appears on the right hand side of an \(=\) it means that
+the inputs are concatenated. When \(\parallel\) appears on the left hand
+side of an \(=\) it means that the output is split.
+
+When this document uses \(\operatorname{ECDH}\left(K_A,K_B\right)\) it means
+that each party computes a Diffie-Hellman agreement using their private key 
+and the remote party's public key.
+So party \(A\) computes \(\operatorname{ECDH}\left(K_B^{\mathit{public}},K_A^{\mathit{private}}\right)\)
+and party \(B\) computes \(\operatorname{ECDH}\left(K_A^{\mathit{public}},K_B^{\mathit{private}}\right)\).
+
+Where this document uses \(\operatorname{HKDF}\left(\mathit{salt},\mathit{IKM},\mathit{info},L\right)\) it
+refers to the [HMAC-based key derivation function][] 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 Olm Algorithm
+
+### Initial setup
+
+The setup takes four [Curve25519][] inputs: Identity keys for Alice and Bob,
+\(I_A\) and \(I_B\), and one-time keys for Alice and Bob,
+\(E_A\) and \(E_B\). A shared secret, \(S\), is generated using
+[Triple Diffie-Hellman][]. The initial 256 bit root key, \(R_0\), and 256
+bit chain key, \(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.
+
+\[
+\begin{aligned}
+    S&=\operatorname{ECDH}\left(I_A,E_B\right)\;\parallel\;
+       \operatorname{ECDH}\left(E_A,I_B\right)\;\parallel\;
+       \operatorname{ECDH}\left(E_A,E_B\right)\\
+    R_0\;\parallel\;C_{0,0}&=
+        \operatorname{HKDF}\left(0,S,\text{``OLM\_ROOT"},64\right)
+\end{aligned}
+\]
+
+### Advancing the root key
+
+Advancing a root key takes the previous root key, \(R_{i-1}\), and two
+Curve25519 inputs: the previous ratchet key, \(T_{i-1}\), and the current
+ratchet key \(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, \(R_i\), and
+chain key, \(C_{i,0}\), are derived from the shared secret using
+[HKDF-SHA-256][] using \(R_{i-1}\) as the salt and ``"OLM_RATCHET"`` as the
+info.
+
+\[
+\begin{aligned}
+    R_i\;\parallel\;C_{i,0}&=
+        \operatorname{HKDF}\left(
+            R_{i-1},
+            \operatorname{ECDH}\left(T_{i-1},T_i\right),
+            \text{``OLM\_RATCHET"},
+            64
+        \right)
+\end{aligned}
+\]
+
+### Advancing the chain key
+
+Advancing a chain key takes the previous chain key, \(C_{i,j-1}\). The next
+chain key, \(C_{i,j}\), is the [HMAC-SHA-256][] of ``"\x02"`` using the
+previous chain key as the key.
+
+\[
+\begin{aligned}
+    C_{i,j}&=\operatorname{HMAC}\left(C_{i,j-1},\text{``\char`\\x02"}\right)
+\end{aligned}
+\]
+
+### Creating a message key
+
+Creating a message key takes the current chain key, \(C_{i,j}\). The
+message key, \(M_{i,j}\), is the [HMAC-SHA-256][] of ``"\x01"`` using the
+current chain key as the key. The message keys where \(i\) is even are used
+by Alice to encrypt messages. The message keys where \(i\) is odd are used
+by Bob to encrypt messages.
+
+\[
+\begin{aligned}
+    M_{i,j}&=\operatorname{HMAC}\left(C_{i,j},\text{``\char`\\x01"}\right)
+\end{aligned}
+\]
+
+## The Olm Protocol
+
+### Creating an outbound session
+
+Bob publishes the public parts of his identity key, \(I_B\), and some
+single-use one-time keys \(E_B\).
+
+Alice downloads Bob's identity key, \(I_B\), and a one-time key,
+\(E_B\). She generates a new single-use key, \(E_A\), and computes a
+root key, \(R_0\), and a chain key \(C_{0,0}\). She also generates a
+new ratchet key \(T_0\).
+
+### Sending the first pre-key messages
+
+Alice computes a message key, \(M_{0,j}\), and a new chain key,
+\(C_{0,j+1}\), using the current chain key. She replaces the current chain
+key with the new one.
+
+Alice encrypts her plain-text with the message key, \(M_{0,j}\), using an
+authenticated encryption scheme (see below) to get a cipher-text,
+\(X_{0,j}\).
+
+She then sends the following to Bob:
+ * The public part of her identity key, \(I_A\)
+ * The public part of her single-use key, \(E_A\)
+ * The public part of Bob's single-use key, \(E_B\)
+ * The current chain index, \(j\)
+ * The public part of her ratchet key, \(T_0\)
+ * The cipher-text, \(X_{0,j}\)
+
+Alice will continue to send pre-key messages until she receives a message from
+Bob.
+
+### Creating an inbound session from a pre-key message
+
+Bob receives a pre-key message as above.
+
+Bob looks up the private part of his single-use key, \(E_B\). He can now
+compute the root key, \(R_0\), and the chain key, \(C_{0,0}\), from
+\(I_A\), \(E_A\), \(I_B\), and \(E_B\).
+
+Bob then advances the chain key \(j\) times, to compute the chain key used
+by the message, \(C_{0,j}\). He now creates the
+message key, \(M_{0,j}\), and attempts to decrypt the cipher-text,
+\(X_{0,j}\). If the cipher-text's authentication is correct then Bob can
+discard the private part of his single-use one-time key, \(E_B\).
+
+Bob stores Alice's initial ratchet key, \(T_0\), until he wants to
+send a message.
+
+### Sending normal messages
+
+Once a message has been received from the other side, a session is considered
+established, and a more compact form is used.
+
+To send a message, the user checks if they have a sender chain key,
+\(C_{i,j}\). Alice uses chain keys where \(i\) is even. Bob uses chain
+keys where \(i\) is odd. If the chain key doesn't exist then a new ratchet
+key \(T_i\) is generated and a new root key \(R_i\) and chain key
+\(C_{i,0}\) are computed using \(R_{i-1}\), \(T_{i-1}\) and
+\(T_i\).
+
+A message key,
+\(M_{i,j}\) is computed from the current chain key, \(C_{i,j}\), and
+the chain key is replaced with the next chain key, \(C_{i,j+1}\). The
+plain-text is encrypted with \(M_{i,j}\), using an authenticated encryption
+scheme (see below) to get a cipher-text, \(X_{i,j}\).
+
+The user then sends the following to the recipient:
+ * The current chain index, \(j\)
+ * The public part of the current ratchet key, \(T_i\)
+ * The cipher-text, \(X_{i,j}\)
+
+### Receiving messages
+
+The user receives a message as above with the sender's current chain index, \(j\),
+the sender's ratchet key, \(T_i\), and the cipher-text, \(X_{i,j}\).
+
+The user checks if they have a receiver chain with the correct
+\(i\) by comparing the ratchet key, \(T_i\). If the chain doesn't exist
+then they compute a new root key, \(R_i\), and a new receiver chain, with
+chain key \(C_{i,0}\), using \(R_{i-1}\), \(T_{i-1}\) and
+\(T_i\).
+
+If the \(j\) of the message is less than
+the current chain index on the receiver then the message may only be decrypted
+if the receiver has stored a copy of the message key \(M_{i,j}\). Otherwise
+the receiver computes the chain key, \(C_{i,j}\). The receiver computes the
+message key, \(M_{i,j}\), from the chain key and attempts to decrypt the
+cipher-text, \(X_{i,j}\).
+
+If the decryption succeeds the receiver updates the chain key for \(T_i\)
+with \(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
+
+Olm uses two types of messages. The underlying transport protocol must provide
+a means for recipients to distinguish between them.
+
+### Normal Messages
+
+Olm messages start with a one byte version followed by a variable length
+payload followed by a fixed length message authentication code.
+
+```nohighlight
+ +--------------+------------------------------------+-----------+
+ | Version Byte | Payload Bytes                      | MAC Bytes |
+ +--------------+------------------------------------+-----------+
+```
+
+The version byte is ``"\x03"``.
+
+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**
+:-----:|:-----:|:-----:|:-----:
+Ratchet-Key|0x0A|String|The public part of the ratchet key of the message, \(T_i\).
+Chain-Index|0x10|Integer|The chain index of the message, \(j\).
+Cipher-Text|0x22|String|The cipher-text of the message, \(X_{i,j}\).
+
+The length of the MAC is determined by the authenticated encryption algorithm
+being used. (Olm version 1 uses [HMAC-SHA-256][], truncated to 8 bytes). The
+MAC protects all of the bytes preceding the MAC.
+
+### Pre-Key Messages
+
+Olm pre-key messages start with a one byte version followed by a variable
+length payload.
+
+```nohighlight
+ +--------------+------------------------------------+
+ | Version Byte | Payload Bytes                      |
+ +--------------+------------------------------------+
+```
+
+The version byte is ``"\x03"``.
+
+The payload uses the same key-value format as for normal messages.
+
+**Name**|**Tag**|**Type**|**Meaning**
+:-----:|:-----:|:-----:|:-----:
+One-Time-Key|0x0A|String|The public part of Bob's single-use key, \(E_B\).
+Base-Key|0x12|String|The public part of Alice's single-use key, \(E_A\).
+Identity-Key|0x1A|String|The public part of Alice's identity key, \(I_A\).
+Message|0x22|String|An embedded Olm message with its own version and MAC.
+
+## Olm Authenticated Encryption
+
+### Version 1
+
+Version 1 of Olm uses [AES-256][] in [CBC][] mode with [PKCS#7][] padding for
+encryption and [HMAC-SHA-256][] (truncated to 64 bits) 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"``.
+
+\[
+\begin{aligned}
+    \mathit{AES\_KEY}_{i,j}\;\parallel\;\mathit{HMAC\_KEY}_{i,j}\;\parallel\;\mathit{AES\_IV}_{i,j}
+    &= \operatorname{HKDF}\left(0,M_{i,j},\text{``OLM\_KEYS"},80\right)
+\end{aligned}
+\]
+
+The plain-text is encrypted with AES-256, using the key \(\mathit{AES\_KEY}_{i,j}\)
+and the IV \(\mathit{AES\_IV}_{i,j}\) to give the cipher-text, \(X_{i,j}\).
+
+Then the entire message (including the Version Byte and all Payload Bytes) are
+passed through [HMAC-SHA-256][]. The first 8 bytes of the MAC are appended to the message.
+
+## Message authentication concerns
+
+To avoid unknown key-share attacks, the application must include identifying
+data for the sending and receiving user in the plain-text of (at least) the
+pre-key messages. Such data could be a user ID, a telephone number;
+alternatively it could be the public part of a keypair which the relevant user
+has proven ownership of.
+
+### Example attacks
+
+1. Alice publishes her public [Curve25519][] identity key, \(I_A\). Eve
+   publishes the same identity key, claiming it as her own. Bob downloads
+   Eve's keys, and associates \(I_A\) with Eve. Alice sends a message to
+   Bob; Eve intercepts it before forwarding it to Bob. Bob believes the
+   message came from Eve rather than Alice.
+
+   This is prevented if Alice includes her user ID in the plain-text of the
+   pre-key message, so that Bob can see that the message was sent by Alice
+   originally.
+
+2. Bob publishes his public [Curve25519][] identity key, \(I_B\). Eve
+   publishes the same identity key, claiming it as her own. Alice downloads
+   Eve's keys, and associates \(I_B\) with Eve. Alice sends a message to
+   Eve; Eve cannot decrypt it, but forwards it to Bob. Bob believes the
+   Alice sent the message to him, whereas Alice intended it to go to Eve.
+
+   This is prevented by Alice including the user ID of the intended recipient
+   (Eve) in the plain-text of the pre-key message. Bob can now tell that the
+   message was meant for Eve rather than him.
+
+## IPR
+
+The Olm specification (this document) is hereby placed in the public domain.
+
+## Feedback
+
+Can be sent to olm at matrix.org.
+
+## Acknowledgements
+
+The ratchet that Olm implements was designed by Trevor Perrin and Moxie
+Marlinspike - details at https://signal.org/docs/specifications/doubleratchet/. Olm is
+an entirely new implementation written by the Matrix.org team.
+
+[Curve25519]: http://cr.yp.to/ecdh.html
+[Triple Diffie-Hellman]: https://signal.org/blog/simplifying-otr-deniability/
+[HMAC-based key derivation function]: https://tools.ietf.org/html/rfc5869
+[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
+[PKCS#7]: https://tools.ietf.org/html/rfc2315

data/lib/async/matrix/e2ee/schema/data/api/client-server/cross_signing.yaml

@@ -0,0 +1,296 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Cross Signing API
+  version: 1.0.0
+paths:
+  /keys/device_signing/upload:
+    post:
+      x-addedInMatrixVersion: "1.1"
+      x-changedInMatrixVersion:
+        "1.11": UIA is not always required for this endpoint.
+        "1.17": |-
+          This endpoint no longer requires User-Interactive Authentication when used by an
+          application service.
+      summary: Upload cross-signing keys.
+      description: |-
+        Publishes cross-signing keys for the user.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
+        except when used by an application service.
+
+        User-Interactive Authentication MUST be performed for regular clients, except in these cases:
+        - there is no existing master signing key uploaded to the homeserver, OR
+        - there is an existing master signing key and it exactly matches the
+          master signing key provided in the request body. If there are any additional
+          keys provided in the request (self-signing key, user-signing key) they MUST also
+          match the existing keys stored on the server. In other words, the request contains
+          no new keys.
+
+        This allows clients to freely upload one set of keys, but not modify/overwrite keys if
+        they already exist. Allowing clients to upload the same set of keys more than once
+        makes this endpoint idempotent in the case where the response is lost over the network,
+        which would otherwise cause a UIA challenge upon retry.
+
+        {{% boxes/note %}}
+        When this endpoint requires User-Interactive Authentication,
+        it uses the [`m.oauth`](/client-server-api/#oauth-authentication)
+        authentication type if the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/note %}}
+      operationId: uploadCrossSigningKeys
+      security:
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                master_key:
+                  description: Optional. The user\'s master signing key.
+                  allOf:
+                    - $ref: definitions/cross_signing_key.yaml
+                self_signing_key:
+                  description: |-
+                    Optional. The user\'s self-signing key. Must be signed by
+                    the accompanying master signing key, or by the user\'s most recently
+                    uploaded master signing key if no master signing key is included in the
+                    request.
+                  allOf:
+                    - $ref: definitions/cross_signing_key.yaml
+                user_signing_key:
+                  description: |-
+                    Optional. The user\'s user-signing key. Must be signed by
+                    the accompanying master signing key, or by the user\'s most recently
+                    uploaded master signing key if no master signing key is included in the
+                    request.
+                  allOf:
+                    - $ref: definitions/cross_signing_key.yaml
+                auth:
+                  description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+              example: {
+                "auth": {
+                  "type": "example.type.foo",
+                  "session": "xxxxx",
+                  "example_credential": "verypoorsharedsecret"
+                },
+                "master_key": {
+                  "user_id": "@alice:example.com",
+                  "usage": [
+                    "master"
+                  ],
+                  "keys": {
+                    "ed25519:base64+master+public+key": "base64+master+public+key"
+                  }
+                },
+                "self_signing_key": {
+                  "user_id": "@alice:example.com",
+                  "usage": [
+                    "self_signing"
+                  ],
+                  "keys": {
+                    "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
+                  },
+                  "signatures": {
+                    "@alice:example.com": {
+                      "ed25519:base64+master+public+key": "signature+of+self+signing+key"
+                    }
+                  }
+                },
+                "user_signing_key": {
+                  "user_id": "@alice:example.com",
+                  "usage": [
+                    "user_signing"
+                  ],
+                  "keys": {
+                    "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key"
+                  },
+                  "signatures": {
+                    "@alice:example.com": {
+                      "ed25519:base64+master+public+key": "signature+of+user+signing+key"
+                    }
+                  }
+                }
+              }
+        description: The keys to be published.
+        required: true
+      responses:
+        "200":
+          description: The provided keys were successfully uploaded.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {}
+        "400":
+          description: |-
+            The input was invalid in some way. This can include one of the
+            following error codes:
+
+            * `M_INVALID_SIGNATURE`: For example, the self-signing or
+              user-signing key had an incorrect signature.
+            * `M_MISSING_PARAM`: No master signing key is available.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {
+                  "errcode": "M_INVALID_SIGNATURE",
+                  "error": "Invalid signature"
+                }
+        "403":
+          description: |-
+            The public key of one of the keys is the same as one of the user\'s
+            device IDs, or the request is not authorised for any other reason.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {
+                  "errcode": "M_FORBIDDEN",
+                  "error": "Key ID in use"
+                }
+      tags:
+        - End-to-end encryption
+  /keys/signatures/upload:
+    post:
+      x-addedInMatrixVersion: "1.1"
+      summary: Upload cross-signing signatures.
+      description: |-
+        Publishes cross-signing signatures for the user.
+
+        The signed JSON object must match the key previously uploaded or
+        retrieved for the given key ID, with the exception of the `signatures`
+        property, which contains the new signature(s) to add.
+      operationId: uploadCrossSigningSignatures
+      security:
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: |-
+                A map of user ID to a map of key ID to signed JSON object.
+              patternProperties:
+                "^@":
+                  x-pattern-format: mx-user-id
+                  type: object
+                  additionalProperties:
+                    type: object
+              example: {
+                "@alice:example.com": {
+                  "HIJKLMN": {
+                    "user_id": "@alice:example.com",
+                    "device_id": "HIJKLMN",
+                    "algorithms": [
+                      "m.olm.v1.curve25519-aes-sha2",
+                      "m.megolm.v1.aes-sha2"
+                    ],
+                    "keys": {
+                      "curve25519:HIJKLMN": "base64+curve25519+key",
+                      "ed25519:HIJKLMN": "base64+ed25519+key"
+                    },
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN"
+                      }
+                    }
+                  },
+                  "base64+master+public+key": {
+                    "user_id": "@alice:example.com",
+                    "usage": [
+                      "master"
+                    ],
+                    "keys": {
+                      "ed25519:base64+master+public+key": "base64+master+public+key"
+                    },
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:HIJKLMN": "base64+signature+of+master+key"
+                      }
+                    }
+                  }
+                },
+                "@bob:example.com": {
+                  "bobs+base64+master+public+key": {
+                    "user_id": "@bob:example.com",
+                    "keys": {
+                      "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
+                    },
+                    "usage": [
+                      "master"
+                    ],
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
+                      }
+                    }
+                  }
+                }
+              }
+        description: |-
+          A map from user ID to key ID to signed JSON objects containing the
+          signatures to be published.
+        required: true
+      responses:
+        "200":
+          description: The provided signatures were processed.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  failures:
+                    type: object
+                    description: |-
+                      A map from user ID to key ID to an error for any signatures
+                      that failed.  If a signature was invalid, the `errcode` will
+                      be set to `M_INVALID_SIGNATURE`.
+                    patternProperties:
+                      "^@":
+                        type: object
+                        x-pattern-format: mx-user-id
+                        additionalProperties:
+                          type: object
+                          title: Error
+                    example:
+                      "@alice:example.com":
+                        HIJKLMN:
+                          errcode: M_INVALID_SIGNATURE
+                          error: Invalid signature
+      tags:
+        - End-to-end encryption
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer