wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Use GFM table syntax instead of raw HTML

Browse source
This commit is contained in:
Will 2021-01-21 17:08:08 -08:00
parent afa62628e8
commit 52745160f3
No known key found for this signature in database
GPG key ID: 385872BB265E8BF8
6 changed files with 144 additions and 730 deletions
Download patch file Download diff file Expand all files Collapse all files

114
content/application-service-api.md
View file

@ -86,57 +86,18 @@ by POSIX extended regular expressions and look like:
Application services may define the following namespaces (with none
being explicitly required):
<table>
<colgroup>
<col style="width: 24%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="header">
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>users</td>
<td>Events which are sent from certain users.</td>
</tr>
<tr class="even">
<td>aliases</td>
<td>Events which are sent in rooms with certain room aliases.</td>
</tr>
<tr class="odd">
<td>rooms</td>
<td>Events which are sent in rooms with certain room IDs.</td>
</tr>
</tbody>
</table>
| Name | Description |
|----------|------------------------------------------------------------|
| users | Events which are sent from certain users. |
| aliases | Events which are sent in rooms with certain room aliases. |
| rooms | Events which are sent in rooms with certain room IDs. |
Each individual namespace MUST declare the following fields:
<table>
<colgroup>
<col style="width: 12%" />
<col style="width: 87%" />
</colgroup>
<thead>
<tr class="header">
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>exclusive</td>
<td><strong>Required</strong> A true or false value stating whether this application service has exclusive access to events within this namespace.</td>
</tr>
<tr class="even">
<td>regex</td>
<td><strong>Required</strong> A regular expression defining which values this namespace includes.</td>
</tr>
</tbody>
</table>
| Name | Description |
|------------|------------------------------------------------------------------------------------------------------------------------------------|
| exclusive | **Required** A true or false value stating whether this application service has exclusive access to events within this namespace. |
| regex | **Required** A regular expression defining which values this namespace includes. |
Exclusive user and alias namespaces should begin with an underscore
after the sigil to avoid collisions with other users on the homeserver.
@ -149,52 +110,17 @@ The registration is represented by a series of key-value pairs, which
this specification will present as YAML. See below for the possible
options along with their explanation:
<table>
<colgroup>
<col style="width: 11%" />
<col style="width: 88%" />
</colgroup>
<thead>
<tr class="header">
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>id</td>
<td><strong>Required.</strong> A unique, user-defined ID of the application service which will never change.</td>
</tr>
<tr class="even">
<td>url</td>
<td><strong>Required.</strong> The URL for the application service. May include a path after the domain name. Optionally set to <code>null</code> if no traffic is required.</td>
</tr>
<tr class="odd">
<td>as_token</td>
<td><strong>Required.</strong> A unique token for application services to use to authenticate requests to Homeservers.</td>
</tr>
<tr class="even">
<td>hs_token</td>
<td><strong>Required.</strong> A unique token for Homeservers to use to authenticate requests to application services.</td>
</tr>
<tr class="odd">
<td>sender_localpart</td>
<td><strong>Required.</strong> The localpart of the user associated with the application service.</td>
</tr>
<tr class="even">
<td>namespaces</td>
<td><strong>Required.</strong> A list of <code>users</code>, <code>aliases</code> and <code>rooms</code> namespaces that the application service controls.</td>
</tr>
<tr class="odd">
<td>rate_limited</td>
<td>Whether requests from masqueraded users are rate-limited. The sender is excluded.</td>
</tr>
<tr class="even">
<td>protocols</td>
<td>The external protocols which the application service provides (e.g. IRC).</td>
</tr>
</tbody>
</table>
| Name | Description |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| id | **Required** A unique, user-defined ID of the application service which will never change. |
| url | **Required** The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required. |
| as_token | **Required** A unique token for application services to use to authenticate requests to Homeservers. |
| hs_token | **Required** A unique token for Homeservers to use to authenticate requests to application services. |
| sender_localpart | **Required** The localpart of the user associated with the application service. |
| namespaces | **Required** A list of `users`, `aliases` and `rooms` namespaces that the application service controls. |
| rate_limited | Whether requests from masqueraded users are rate-limited. The sender is excluded. |
| protocols | The external protocols which the application service provides (e.g. IRC). |
An example registration file for an IRC-bridging application service is
below:

31
content/client-server-api/_index.md
View file

@ -1473,32 +1473,11 @@ the server-server API.
In addition to the fields of a Room Event, State Events have the
following fields.
<table>
<colgroup>
<col style="width: 16%" />
<col style="width: 16%" />
<col style="width: 67%" />
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>state_key</td>
<td>string</td>
<td><strong>Required.</strong> A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. State keys starting with an <code>@</code> are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.</td>
</tr>
<tr class="even">
<td>prev_content</td>
<td>EventContent</td>
<td>Optional. The previous <code>content</code> for this event. If there is no previous content, this key will be missing.</td>
</tr>
</tbody>
</table>
| Key | Type | Description |
|--------------|--------------|--------------------------------------------------------------------------------------------------------------|
| state_key | string | **Required.** A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. State keys starting with an `@` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user. |
| prev_content | EventContent | Optional. The previous `content` for this event. If there is no previous content, this key will be missing. |
### Size limits

327
content/client-server-api/modules/end_to_end_encryption.md
View file

@ -74,28 +74,10 @@ with the following properties:
`KeyObject`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>key</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> The unpadded Base64-encoded 32-byte Curve25519 public key.</p></td>
</tr>
<tr class="even">
<td><p>signatures</p></td>
<td><p>Signatures</p></td>
<td><p><strong>Required.</strong> Signatures of the key object.</p>
<p>The signature is calculated using the process described at <a href="/appendices/#signing-json">Signing JSON</a>.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| key | string | **Required.** The unpadded Base64-encoded 32-byte Curve25519 public key. |
| signatures | Signatures | **Required.** Signatures of the key object. The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). |
Example:
@ -275,81 +257,23 @@ properties.
`EncryptedFile`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>url</td>
<td>string</td>
<td><strong>Required.</strong> The URL to the file.</td>
</tr>
<tr class="even">
<td>key</td>
<td>JWK</td>
<td><strong>Required.</strong> A <a href="https://tools.ietf.org/html/rfc7517#appendix-A.3">JSON Web Key</a> object.</td>
</tr>
<tr class="odd">
<td><p>iv</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.</p></td>
</tr>
<tr class="even">
<td><p>hashes</p></td>
<td><p>{string: string}</p></td>
<td><p><strong>Required.</strong> A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key <code>sha256</code>.</p></td>
</tr>
<tr class="odd">
<td><p>v</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> Version of the encrypted attachments protocol. Must be <code>v2</code>.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|-----------|------------------|------------------------------------------------------------------------------------------------|
| url | string | **Required.** The URL to the file. |
| key | JWK | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object. |
| iv | string | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. |
| hashes | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. |
| v | string | **Required.** Version of the encrypted attachments protocol. Must be `v2`. |
`JWK`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>kty</td>
<td>string</td>
<td><strong>Required.</strong> Key type. Must be <code>oct</code>.</td>
</tr>
<tr class="even">
<td><p>key_ops</p></td>
<td><p>[string]</p></td>
<td><p><strong>Required.</strong> Key operations. Must at least contain <code>encrypt</code> and <code>decrypt</code>.</p></td>
</tr>
<tr class="odd">
<td>alg</td>
<td>string</td>
<td><strong>Required.</strong> Algorithm. Must be <code>A256CTR</code>.</td>
</tr>
<tr class="even">
<td>k</td>
<td>string</td>
<td><strong>Required.</strong> The key, encoded as urlsafe unpadded base64.</td>
</tr>
<tr class="odd">
<td><p>ext</p></td>
<td><p>boolean</p></td>
<td><p><strong>Required.</strong> Extractable. Must be <code>true</code>. This is a <a href="https://w3c.github.io/webcrypto/#iana-section-jwk">W3C extension</a>.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
| --------- |----------|--------------------------------------------------------------------------------------------------------------------------|
| kty | string | **Required.** Key type. Must be `oct`. |
| key_ops | [string] | **Required.** Key operations. Must at least contain `encrypt` and `decrypt`. |
| alg | string | **Required.** Algorithm. Must be `A256CTR`. |
| k | string | **Required.** The key, encoded as urlsafe unpadded base64. |
| ext | boolean | **Required.** Extractable. Must be `true`. This is a [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk). |
Example:
@ -1027,69 +951,23 @@ the following format:
`AuthData`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>public_key</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> The curve25519 public key used to encrypt the backups, encoded in unpadded base64.</p></td>
</tr>
<tr class="even">
<td><p>signatures</p></td>
<td><p>Signatures</p></td>
<td><p>Optional. Signatures of the <code>auth_data</code>, as Signed JSON</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
| -----------| -----------|--------------------------------------------------------------------------------------------------|
| public_key | string | **Required.** The curve25519 public key used to encrypt the backups, encoded in unpadded base64. |
| signatures | Signatures | Optional. Signatures of the ``auth_data``, as Signed JSON |
The `session_data` field in the backups is constructed as follows:
1. Encode the session key to be backed up as a JSON object with the
properties:
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>algorithm</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> The end-to-end message encryption algorithm that the key is for. Must be <code>m.megolm.v1.aes-sha2</code>.</p></td>
</tr>
<tr class="even">
<td><p>forwarding_curve25519_key_chain</p></td>
<td><p>[string]</p></td>
<td><p><strong>Required.</strong> Chain of Curve25519 keys through which this session was forwarded, via <a href="#mforwarded_room_key">m.forwarded_room_key</a> events.</p></td>
</tr>
<tr class="odd">
<td><p>sender_key</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> Unpadded base64-encoded device curve25519 key.</p></td>
</tr>
<tr class="even">
<td><p>sender_claimed_keys</p></td>
<td><p>{string: string}</p></td>
<td><p><strong>Required.</strong> A map from algorithm name (<code>ed25519</code>) to the identity key for the sending device.</p></td>
</tr>
<tr class="odd">
<td><p>session_key</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> Unpadded base64-encoded session key in <a href="https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-sharing-format">session-sharing format</a>.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
| --------------------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| algorithm | string | **Required.** The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`. |
| forwarding_curve25519_key_chain | [string] | **Required.** Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](#mforwarded_room_key) events. |
| sender_key | string | **Required.** Unpadded base64-encoded device curve25519 key. |
| sender_claimed_keys | {string: string} | **Required.** A map from algorithm name (`ed25519`) to the identity key for the sending device. |
| session_key | string | **Required.** Unpadded base64-encoded session key in [session-sharing format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-sharing-format). |
2. Generate an ephemeral curve25519 key, and perform an ECDH with the
ephemeral key and the backup's public key to generate a shared
@ -1138,40 +1016,14 @@ user-supplied passphrase, and is created as follows:
4. Concatenate the following data:
<table>
<thead>
<tr class="header">
<th>Size (bytes)</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>1</td>
<td>Export format version, which must be <code>0x01</code>.</td>
</tr>
<tr class="even">
<td>16</td>
<td>The salt S.</td>
</tr>
<tr class="odd">
<td>16</td>
<td>The initialization vector IV.</td>
</tr>
<tr class="even">
<td>4</td>
<td>The number of rounds N, as a big-endian unsigned 32-bit integer.</td>
</tr>
<tr class="odd">
<td>variable</td>
<td>The encrypted JSON object.</td>
</tr>
<tr class="even">
<td><p>32</p></td>
<td><p>The HMAC-SHA-256 of all the above string concatenated together, using K' as the key.</p></td>
</tr>
</tbody>
</table>
| Size (bytes)| Description |
| ------------|-----------------------------------------------------------------------------------------|
| 1 | Export format version, which must be `0x01`. |
| 16 | The salt S. |
| 16 | The initialization vector IV. |
| 4 | The number of rounds N, as a big-endian unsigned 32-bit integer. |
| variable | The encrypted JSON object. |
| 32 | The HMAC-SHA-256 of all the above string concatenated together, using K' as the key. |
5. Base64-encode the string above. Newlines may be added to avoid
overly long lines.
@ -1188,52 +1040,15 @@ objects described as follows:
`SessionData`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>algorithm</p></td>
<td><p>string</p></td>
<td><p>Required. The encryption algorithm that the session uses. Must be <code>m.megolm.v1.aes-sha2</code>.</p></td>
</tr>
<tr class="even">
<td><p>forwarding_curve25519_key_chain</p></td>
<td><p>[string]</p></td>
<td><p>Required. Chain of Curve25519 keys through which this session was forwarded, via <a href="#mforwarded_room_key">m.forwarded_room_key</a> events.</p></td>
</tr>
<tr class="odd">
<td><p>room_id</p></td>
<td><p>string</p></td>
<td><p>Required. The room where the session is used.</p></td>
</tr>
<tr class="even">
<td><p>sender_key</p></td>
<td><p>string</p></td>
<td><p>Required. The Curve25519 key of the device which initiated the session originally.</p></td>
</tr>
<tr class="odd">
<td><p>sender_claimed_keys</p></td>
<td><p>{string: string}</p></td>
<td><p>Required. The Ed25519 key of the device which initiated the session originally.</p></td>
</tr>
<tr class="even">
<td>session_id</td>
<td>string</td>
<td>Required. The ID of the session.</td>
</tr>
<tr class="odd">
<td>session_key</td>
<td>string</td>
<td>Required. The key for the session.</td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|-----------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| algorithm | string | Required. The encryption algorithm that the session uses. Must be `m.megolm.v1.aes-sha2`. |
| forwarding_curve25519_key_chain | [string] | Required. Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](#mforwarded_room_key) events. |
| room_id | string | Required. The room where the session is used. |
| sender_key | string | Required. The Curve25519 key of the device which initiated the session originally. |
| sender_claimed_keys | {string: string} | Required. The Ed25519 key of the device which initiated the session originally. |
| session_id | string | Required. The ID of the session. |
| session_key | string | Required. The key for the session. |
This is similar to the format before encryption used for the session
keys in [Server-side key backups](#server-side-key-backups) but adds the
@ -1509,51 +1324,17 @@ It also adds a `one_time_keys_count` property. Note the spelling
difference with the `one_time_key_counts` property in the
`/keys/upload`\_ response.
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>device_lists</p></td>
<td><p>DeviceLists</p></td>
<td><p>Optional. Information on e2e device updates. Note: only present on an incremental sync.</p></td>
</tr>
<tr class="even">
<td><p>device_one_time_keys_count</p></td>
<td><p>{string: integer}</p></td>
<td><p>Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|----------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
| device_lists | DeviceLists | Optional. Information on e2e device updates. Note: only present on an incremental sync. |
| device_one_time_keys_count | {string: integer} | Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. |
`DeviceLists`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>changed</p></td>
<td><p>[string]</p></td>
<td><p>List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response.</p></td>
</tr>
<tr class="even">
<td><p>left</p></td>
<td><p>[string]</p></td>
<td><p>List of users with whom we do not share any encrypted rooms anymore since the previous sync response.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| changed | [string] | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
| left | [string] | List of users with whom we do not share any encrypted rooms anymore since the previous sync response. |
{{% boxes/note %}}
For optimal performance, Alice should be added to `changed` in Bob's

223
content/client-server-api/modules/secrets.md
View file

@ -40,32 +40,11 @@ passphrases](#deriving-keys-from-passphrases).
`KeyDescription`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>name</td>
<td>string</td>
<td><strong>Required.</strong> The name of the key.</td>
</tr>
<tr class="even">
<td><p>algorithm</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> The encryption algorithm to be used for this key. Currently, only <code>m.secret_storage.v1.aes-hmac-sha2</code> is supported.</p></td>
</tr>
<tr class="odd">
<td><p>passphrase</p></td>
<td><p>string</p></td>
<td><p>See <a href="#deriving-keys-from-passphrases">deriving keys from passphrases</a> section for a description of this property.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description
|------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|
| name | string | **Required.** The name of the key. |
| algorithm | string | **Required.** The encryption algorithm to be used for this key. Currently, only `m.secret_storage.v1.aes-hmac-sha2` is supported. |
| passphrase | string | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property. |
Other properties depend on the encryption algorithm, and are described
below.
@ -91,22 +70,9 @@ of the data.
`Secret`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>encrypted</p></td>
<td><p>{string: object}</p></td>
<td><p><strong>Required.</strong> Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of <code>AesHmacSha2EncryptedData</code> in the <a href="#msecret_storagev1aes-hmac-sha2">m.secret_storage.v1.aes-hmac-sha2</a> section.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|-----------|------------------|-------------|
| encrypted | {string: object} | **Required.** Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of `AesHmacSha2EncryptedData` in the [m.secret_storage.v1.aes-hmac-sha2](#msecret_storagev1aes-hmac-sha2) section. |
Example:
@ -175,32 +141,11 @@ HMAC-SHA-256. The secret is encrypted as follows:
`AesHmacSha2EncryptedData`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>iv</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> The 16-byte initialization vector, encoded as base64.</p></td>
</tr>
<tr class="even">
<td><p>ciphertext</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> The AES-CTR-encrypted data, encoded as base64.</p></td>
</tr>
<tr class="odd">
<td>mac</td>
<td>string</td>
<td><strong>Required.</strong> The MAC, encoded as base64.</td>
</tr>
</tbody>
</table>
| Parameter | Type | Description
|------------|---------|------------------------------------------------------------------------|
| iv | string | **Required.** The 16-byte initialization vector, encoded as base64. |
| ciphertext | string | **Required.** The AES-CTR-encrypted data, encoded as base64. |
| mac | string | **Required.** The MAC, encoded as base64. |
For the purposes of allowing clients to check whether a user has
correctly entered the key, clients should:
@ -213,42 +158,13 @@ correctly entered the key, clients should:
`AesHmacSha2KeyDescription`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>name</td>
<td>string</td>
<td><strong>Required.</strong> The name of the key.</td>
</tr>
<tr class="even">
<td><p>algorithm</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> The encryption algorithm to be used for this key. Currently, only <code>m.secret_storage.v1.aes-hmac-sha2</code> is supported.</p></td>
</tr>
<tr class="odd">
<td><p>passphrase</p></td>
<td><p>object</p></td>
<td><p>See <a href="#deriving-keys-from-passphrases">deriving keys from passphrases</a> section for a description of this property.</p></td>
</tr>
<tr class="even">
<td>iv</td>
<td>string</td>
<td>The 16-byte initialization vector, encoded as base64.</td>
</tr>
<tr class="odd">
<td><p>mac</p></td>
<td><p>string</p></td>
<td><p>The MAC of the result of encrypting 32 bytes of 0, encoded as base64.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|-------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|
| name | string | **Required.** The name of the key. |
| algorithm | string | **Required.** The encryption algorithm to be used for this key. Currently, only `m.secret_storage.v1.aes-hmac-sha2` is supported. |
| passphrase | object | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property. |
| iv | string | The 16-byte initialization vector, encoded as base64. |
| mac | string | The MAC of the result of encrypting 32 bytes of 0, encoded as base64. |
For example, the `m.secret_storage.key.key_id` for a key using this
algorithm could look like:
@ -311,37 +227,12 @@ defined by the `algorithm` specified.
For the `m.pbkdf2` algorithm, the `passphrase` property has the
following properties:
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>algorithm</td>
<td>string</td>
<td><strong>Required.</strong> Must be <code>m.pbkdf2</code></td>
</tr>
<tr class="even">
<td>salt</td>
<td>string</td>
<td><strong>Required.</strong> The salt used in PBKDF2.</td>
</tr>
<tr class="odd">
<td>iterations</td>
<td>integer</td>
<td><strong>Required.</strong> The number of iterations to use in PBKDF2.</td>
</tr>
<tr class="even">
<td><p>bits</p></td>
<td><p>integer</p></td>
<td><p>Optional. The number of bits to generate for the key. Defaults to 256.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|------------|---------|------------------------------------------------------------------------|
| algorithm | string | **Required.** Must be `m.pbkdf2` |
| salt | string | **Required.** The salt used in PBKDF2. |
| iterations | integer | **Required.** The number of iterations to use in PBKDF2. |
| bits | integer | Optional. The number of bits to generate for the key. Defaults to 256. |
The key is generated using PBKDF2 with SHA-512 as the hash, using the
salt given in the `salt` parameter, and the number of iterations given
@ -385,37 +276,12 @@ confirm sharing the secret.
Sent by a client to request a secret from another device or to cancel a
previous request. It is sent as an unencrypted to-device event.
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>name</p></td>
<td><p>string</p></td>
<td><p>Required if <code>action</code> is <code>request</code>. The name of the secret that is being requested.</p></td>
</tr>
<tr class="even">
<td>action</td>
<td>enum</td>
<td><strong>Required.</strong> One of ["request", "request_cancellation"].</td>
</tr>
<tr class="odd">
<td>requesting_device_id</td>
<td>string</td>
<td><strong>Required.</strong> The ID of the device requesting the secret.</td>
</tr>
<tr class="even">
<td><p>request_id</p></td>
<td><p>string</p></td>
<td><p><strong>Required.</strong> A random string uniquely identifying (with respect to the requester and the target) the target for a secret. If the secret is requested from multiple devices at the same time, the same ID may be used for every target. The same ID is also used in order to cancel a previous request.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|-----------------------|--------|----------------------------------------------------------------------------------------|
| name | string | Required if ``action`` is ``request``. The name of the secret that is being requested. |
| action | enum | **Required.** One of ["request", "request_cancellation"]. |
| requesting_device_id | string | **Required.** The ID of the device requesting the secret. |
| request_id | string | **Required.** A random string uniquely identifying (with respect to the requester and the target) the target for a secret. If the secret is requested from multiple devices at the same time, the same ID may be used for every target. The same ID is also used in order to cancel a previous request. |
Example:
@ -434,27 +300,10 @@ Sent by a client to share a secret with another device, in response to
an `m.secret.request` event. It must be encrypted as an
`m.room.encrypted` event, then sent as a to-device event.
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>request_id</td>
<td>string</td>
<td><strong>Required.</strong> The ID of the request that this a response to.</td>
</tr>
<tr class="even">
<td>secret</td>
<td>string</td>
<td><strong>Required.</strong> The contents of the secret.</td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|-------------|--------|--------------------------------------------------------------|
| request_id | string | **Required.** The ID of the request that this a response to. |
| secret | string | **Required.** The contents of the secret. |
Example:

69
content/client-server-api/modules/send_to_device.md
View file

@ -58,70 +58,23 @@ should be sent on to the remote servers via
This module adds the following properties to the \_ response:
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>to_device</p></td>
<td><p>ToDevice</p></td>
<td><p>Optional. Information on the send-to-device messages for the client device.</p></td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|-----------|-----------|-----------------------------------------------------------------------------|
| to_device | ToDevice | Optional. Information on the send-to-device messages for the client device. |
`ToDevice`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>events</td>
<td>[Event]</td>
<td>List of send-to-device messages.</td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|-----------|-----------|----------------------------------|
| events | [Event] | List of send-to-device messages. |
`Event`
<table>
<thead>
<tr class="header">
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>content</p></td>
<td><p>EventContent</p></td>
<td><p>The content of this event. The fields in this object will vary depending on the type of event.</p></td>
</tr>
<tr class="even">
<td><p>sender</p></td>
<td><p>string</p></td>
<td><p>The Matrix user ID of the user who sent this event.</p></td>
</tr>
<tr class="odd">
<td>type</td>
<td>string</td>
<td>The type of event.</td>
</tr>
</tbody>
</table>
| Parameter | Type | Description |
|------------|--------------|-------------------------------------------------------------------------------------------------|
| content | EventContent | The content of this event. The fields in this object will vary depending on the type of event. |
| sender | string | The Matrix user ID of the user who sent this event. |
| type | string | The type of event. |
Example response:

110
content/proposals.md
View file

@ -331,72 +331,19 @@ request trackers.
**Note:** All labels are to be placed on the proposal PR.
<table>
<thead>
<tr class="header">
<th>Name</th>
<th>GitHub Label</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Proposal Drafting and Feedback</td>
<td>N/A</td>
<td>A proposal document which is still work-in-progress but is being shared to incorporate feedback. Please prefix your proposal's title with <code>[WIP]</code> to make it easier for reviewers to skim their notifications list.</td>
</tr>
<tr class="even">
<td>Proposal In Review</td>
<td>proposal-in-review</td>
<td>A proposal document which is now ready and waiting for review by the Spec Core Team and community</td>
</tr>
<tr class="odd">
<td>Proposed Final Comment Period</td>
<td>proposed-final-comment-period</td>
<td>Currently awaiting signoff of a 75% majority of team members in order to enter the final comment period</td>
</tr>
<tr class="even">
<td>Final Comment Period</td>
<td>final-comment-period</td>
<td>A proposal document which has reached final comment period either for merge, closure or postponement</td>
</tr>
<tr class="odd">
<td>Final Comment Period Complete</td>
<td>finished-final-comment-period</td>
<td>The final comment period has been completed. Waiting for a demonstration implementation</td>
</tr>
<tr class="even">
<td>Spec PR Missing</td>
<td>spec-pr-missing</td>
<td>The proposal has been agreed, and proven with a demonstration implementation. Waiting for a PR against the Spec</td>
</tr>
<tr class="odd">
<td>Spec PR In Review</td>
<td>spec-pr-in-review</td>
<td>The spec PR has been written, and is currently under review</td>
</tr>
<tr class="even">
<td>Spec PR Merged</td>
<td>merged</td>
<td>A proposal with a sufficient working implementation and whose Spec PR has been merged!</td>
</tr>
<tr class="odd">
<td><p>Postponed</p></td>
<td><p>proposal-postponed</p></td>
<td><p>A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future</p></td>
</tr>
<tr class="even">
<td>Closed</td>
<td>proposal-closed</td>
<td>A proposal which has been reviewed and deemed unsuitable for acceptance</td>
</tr>
<tr class="odd">
<td>Obsolete</td>
<td>obsolete</td>
<td>A proposal which has been made obsolete by another proposal or decision elsewhere.</td>
</tr>
</tbody>
</table>
| Name | GitHub Label | Description |
|---------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------|
| Proposal Drafting and Feedback | N/A | A proposal document which is still work-in-progress but is being shared to incorporate feedback. Please prefix your proposal's title with `[WIP]` to make it easier for reviewers to skim their notifications list. |
| Proposal In Review | proposal-in-review | A proposal document which is now ready and waiting for review by the Spec Core Team and community |
| Proposed Final Comment Period | proposed-final-comment-period | Currently awaiting signoff of a 75% majority of team members in order to enter the final comment period |
| Final Comment Period | final-comment-period | A proposal document which has reached final comment period either for merge, closure or postponement |
| Final Comment Period Complete | finished-final-comment-period | The final comment period has been completed. Waiting for a demonstration implementation |
| Spec PR Missing | spec-pr-missing | The proposal has been agreed, and proven with a demonstration implementation. Waiting for a PR against the Spec |
| Spec PR In Review | spec-pr-in-review | The spec PR has been written, and is currently under review |
| Spec PR Merged | merged | A proposal with a sufficient working implementation and whose Spec PR has been merged! |
| Postponed | proposal-postponed | A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future |
| Closed | proposal-closed | A proposal which has been reviewed and deemed unsuitable for acceptance |
| Obsolete | obsolete | A proposal which has been made obsolete by another proposal or decision elsewhere. |
# Categories
@ -407,32 +354,11 @@ category when possible.
The current categories are:
<table>
<thead>
<tr class="header">
<th>Name</th>
<th>GitHub Label</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Core</td>
<td>kind:core</td>
<td>Important for the protocol's success.</td>
</tr>
<tr class="even">
<td>Feature</td>
<td>kind:feature</td>
<td>Nice to have additions to the spec.</td>
</tr>
<tr class="odd">
<td>Maintenance</td>
<td>kind:maintenance</td>
<td>Fixes or clarifies existing spec.</td>
</tr>
</tbody>
</table>
| Name | GitHub Label | Description |
|-------------|------------------|---------------------------------------|
| Core | kind:core | Important for the protocol's success. |
| Feature | kind:feature | Nice to have additions to the spec. |
| Maintenance | kind:maintenance | Fixes or clarifies existing spec. |
Some examples of core MSCs would be aggregations, cross-signing, and
groups/communities. These are the sorts of things that if not