diff --git a/assets/scss/custom.scss b/assets/scss/custom.scss index 35b4e3dc..8a5c0e58 100644 --- a/assets/scss/custom.scss +++ b/assets/scss/custom.scss @@ -323,7 +323,6 @@ footer { table { table-layout: fixed; width: 100%; - margin: 4rem 0; caption { caption-side: top; diff --git a/changelogs/client_server/newsfragments/1166.clarification b/changelogs/client_server/newsfragments/1166.clarification new file mode 100644 index 00000000..9db3e7c3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1166.clarification @@ -0,0 +1 @@ +Clarify the format of some structures in the End-to-end encryption module. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 8875e57a..10f21e86 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1255,25 +1255,12 @@ When a backup is created with the `algorithm` set to `m.megolm_backup.v1.curve25519-aes-sha2`, the `auth_data` should have the following format: -`AuthData` - -| 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 | +{{% definition path="api/client-server/definitions/key_backup_auth_data" %}} 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: - -| 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). | +1. Encode the session key to be backed up as a JSON object using the + `SessionData` format defined below. 2. Generate an ephemeral curve25519 key, and perform an ECDH with the ephemeral key and the backup's public key to generate a shared @@ -1295,6 +1282,8 @@ The `session_data` field in the backups is constructed as follows: the resulting MAC are base64-encoded, and become the `mac` property of the `session_data`. +{{% definition path="api/client-server/definitions/key_backup_session_data" %}} + {{% http-api spec="client-server" api="key_backup" %}} ##### Key exports @@ -1344,42 +1333,7 @@ user-supplied passphrase, and is created as follows: The exported sessions are formatted as a JSON array of `SessionData` objects described as follows: -`SessionData` - -| 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 -`room_id` and `session_id` fields. - -Example: - -``` -[ - { - "algorithm": "m.megolm.v1.aes-sha2", - "forwarding_curve25519_key_chain": [ - "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" - ], - "room_id": "!Cuyf34gef24t:localhost", - "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", - "sender_claimed_keys": { - "ed25519": "", - }, - "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", - "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..." - }, - ... -] -``` +{{% definition path="api/client-server/definitions/megolm_export_session_data" %}} #### Messaging Algorithms diff --git a/data/api/client-server/definitions/key_backup_auth_data.yaml b/data/api/client-server/definitions/key_backup_auth_data.yaml new file mode 100644 index 00000000..e057e433 --- /dev/null +++ b/data/api/client-server/definitions/key_backup_auth_data.yaml @@ -0,0 +1,36 @@ +# Copyright 2022 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. + + +type: object +title: AuthData +description: |- + The format of the `auth_data` when a key backup is created with the + `algorithm` set to `m.megolm_backup.v1.curve25519-aes-sha2`. +properties: + public_key: + type: string + description: |- + The curve25519 public key used to encrypt the backups, encoded in unpadded base64. + example: "abcdefg" + signatures: + type: object + description: |- + Signatures of the `auth_data`, as Signed JSON + example: { + "something": { + "ed25519:something": "hijklmnop" + } + } +required: ['public_key'] diff --git a/data/api/client-server/definitions/key_backup_session_data.yaml b/data/api/client-server/definitions/key_backup_session_data.yaml new file mode 100644 index 00000000..18963cbe --- /dev/null +++ b/data/api/client-server/definitions/key_backup_session_data.yaml @@ -0,0 +1,62 @@ +# Copyright 2022 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. + + +type: object +title: SessionData +description: |- + The format of a backed-up session key, prior to encryption, when using the + `m.megolm_backup.v1.curve25519-aes-sha2` algorithm. +properties: + algorithm: + type: string + description: |- + The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`. + forwarding_curve25519_key_chain: + type: array + items: + type: string + description: |- + Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](#mforwarded_room_key) events. + sender_key: + type: string + description: |- + Unpadded base64-encoded device Curve25519 key. + sender_claimed_keys: + type: object + additionalProperties: + type: string + description: |- + A map from algorithm name (`ed25519`) to the Ed25519 signing key of the sending device. + session_key: + type: string + description: |- + Unpadded base64-encoded session key in [session-export format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-export-format). +example: { + "algorithm": "m.megolm.v1.aes-sha2", + "forwarding_curve25519_key_chain": [ + "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" + ], + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", + "sender_claimed_keys": { + "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y", + }, + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..." +} +required: + - algorithm + - forwarding_curve25519_key_chain + - sender_key + - sender_claimed_keys + - session_key diff --git a/data/api/client-server/definitions/megolm_export_session_data.yaml b/data/api/client-server/definitions/megolm_export_session_data.yaml new file mode 100644 index 00000000..8c1e5010 --- /dev/null +++ b/data/api/client-server/definitions/megolm_export_session_data.yaml @@ -0,0 +1,38 @@ +# Copyright 2022 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. + + +allOf: + - $ref: key_backup_session_data.yaml + - type: object + description: |- + The format used to encode a Megolm session key for export. + + 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 + `room_id` and `session_id` fields. + properties: + room_id: + type: string + description: |- + The room where the session is used. + example: "!Cuyf34gef24t:localhost" + session_id: + type: string + description: |- + The Megolm session ID. + example: "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" + required: + - room_id + - session_id diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html index 2828db48..fdb307f7 100644 --- a/layouts/shortcodes/definition.html +++ b/layouts/shortcodes/definition.html @@ -18,6 +18,10 @@ {{/* The definition is referenced by the .path parameter */}} {{ $definition := index .Site.Data $pieces }} +{{ if not $definition }} + {{ errorf "site data %s not found" $path }} +{{ end }} + {{/* The base path, which we use to resolve $ref, omits the last component */}} {{ $pieces = first (sub (len $pieces) 1) $pieces}} {{ $path = delimit $pieces "/" }}