From a5ebedc131c15f2017532c73102b86eb1ca98170 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 16 Oct 2020 18:36:02 -0400 Subject: [PATCH] apply suggestions from review --- api/client-server/cross_signing.yaml | 19 +++++--- api/client-server/login.yaml | 10 +++-- .../event-schemas/m.signing_key_update.yaml | 44 +++++++++---------- .../modules/end_to_end_encryption.rst | 14 +++--- 4 files changed, 48 insertions(+), 39 deletions(-) diff --git a/api/client-server/cross_signing.yaml b/api/client-server/cross_signing.yaml index 219e4b3e..91407954 100644 --- a/api/client-server/cross_signing.yaml +++ b/api/client-server/cross_signing.yaml @@ -107,19 +107,28 @@ paths: example: {} 400: description: |- - The input was invalid in some way. This can include one of the + The input was invalid in some way. This can include one of the following error codes: - * ``M_INVALID_SIGNATURE``: The self-signing or user-signing key - had an incorrect signature - * ``M_FORBIDDEN``: The public key of one of the keys is the same as - one of the user\'s device IDs. + * ``M_INVALID_SIGNATURE``: For example, the self-signing or + user-signing key had an incorrect signature. + * ``M_MISSING_PARAM``: No master key is available. 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 unauthorized. + schema: + type: object + example: { + "errcode": "M_FORBIDDEN", + "error": "Key ID in use" + } "/keys/signatures/upload": post: summary: Upload cross-signing signatures. diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index f6c92638..6e38705a 100644 --- a/api/client-server/login.yaml +++ b/api/client-server/login.yaml @@ -123,8 +123,10 @@ paths: type: string description: |- ID of the client device. If this does not correspond to a - known client device, a new device will be created. The server - will auto-generate a device_id if this is not specified. + known client device, a new device will be created. The given + device ID must not be the same as a `cross-signing key ID + <#cross-signing>`_. The server will auto-generate a device_id + if this is not specified. initial_device_display_name: type: string description: |- @@ -195,7 +197,9 @@ paths: 403: description: |- The login attempt failed. This can include one of the following error codes: - * ``M_FORBIDDEN``: The provided authentication data was incorrect. + * ``M_FORBIDDEN``: The provided authentication data was incorrect + or the requested device ID is the same as a cross-signing key + ID. * ``M_USER_DEACTIVATED``: The user has been deactivated. examples: application/json: { diff --git a/api/server-server/definitions/event-schemas/m.signing_key_update.yaml b/api/server-server/definitions/event-schemas/m.signing_key_update.yaml index db75f1ed..e372483a 100644 --- a/api/server-server/definitions/event-schemas/m.signing_key_update.yaml +++ b/api/server-server/definitions/event-schemas/m.signing_key_update.yaml @@ -37,32 +37,28 @@ allOf: example: "@alice:example.com" master_key: type: object - allOf: - - $ref: ../../../client-server/definitions/cross_signing_key.yaml - # FIXME: why isn't the doc generator picking up this example? - - example: { - "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" - } - } - } + $ref: ../../../client-server/definitions/cross_signing_key.yaml + example: { + "user_id": "@alice:example.com", + "usage": ["master"], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key", + } + } self_signing_key: type: object - allOf: - - $ref: ../../../client-server/definitions/cross_signing_key.yaml - # FIXME: why isn't the doc generator picking up this example? - - example: { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } + $ref: ../../../client-server/definitions/cross_signing_key.yaml + example: { + "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" } + } + } required: - user_id diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 28e85159..f45ac889 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -848,13 +848,13 @@ that she cannot see: | +------+ | | +----+ | +----------------+ +--------------+ -Verification methods can be used to verify a user's master key by using the -master public key, encoded using unpadded base64, as the device ID, and -treating it as a normal device. For example, if Alice and Bob verify each other -using SAS, Alice's ``m.key.verification.mac`` message to Bob may include -``"ed25519:alices+master+public+key": "alices+master+public+key"`` in the ``mac`` -property. Servers therefore must ensure that device IDs will not collide with -cross-signing public keys. +`Verification methods <#device-verification>`_ can be used to verify a user's +master key by using the master public key, encoded using unpadded base64, as +the device ID, and treating it as a normal device. For example, if Alice and +Bob verify each other using SAS, Alice's ``m.key.verification.mac`` message to +Bob may include ``"ed25519:alices+master+public+key": +"alices+master+public+key"`` in the ``mac`` property. Servers therefore must +ensure that device IDs will not collide with cross-signing public keys. Key and signature security <<<<<<<<<<<<<<<<<<<<<<<<<<