From e97c10ecc6e23e238e922e0b6c1dd307e9d72913 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Fri, 27 May 2022 19:07:48 +0200 Subject: [PATCH 1/2] keys.yml: fix one_time_keys object contents The alternatives previously listed under two additionalProperties levels are actually one _more_ level deeper; we still can't define them in a formal way before moving to OpenAPI 3 but at least let's be honest and say there's always a dict where there's always a dict. Also, since the same data structure is used in three places now, at least give it a name, and document the actual definition (once) separately (not using it now because it's OpenAPI 3). --- .../definitions/one_time_keys.yaml | 24 ++++++++ data/api/client-server/keys.yaml | 61 +++++-------------- 2 files changed, 40 insertions(+), 45 deletions(-) create mode 100644 data/api/client-server/definitions/one_time_keys.yaml diff --git a/data/api/client-server/definitions/one_time_keys.yaml b/data/api/client-server/definitions/one_time_keys.yaml new file mode 100644 index 000000000..ceb692914 --- /dev/null +++ b/data/api/client-server/definitions/one_time_keys.yaml @@ -0,0 +1,24 @@ +--- +title: OneTimeKeys +type: object +description: |- + One-time public keys. The names of the properties should be in the format + `:`. The format of the key is determined + by the [key algorithm](/client-server-api/#key-algorithms). +additionalProperties: + oneOf: + - type: string + - type: object + properties: + key: + type: string + description: The key, encoded using unpadded base64. + signatures: + type: object + description: |- + Signature for the device. Mapped from user ID to signature object, + containing mapping from _key signing identifier_ to the signature + (see also: https://spec.matrix.org/v1.2/appendices/#signing-json) + additionalProperties: + type: object + required: ['key', 'signatures'] diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index 116a661d2..25f22acdc 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -53,7 +53,12 @@ paths: allOf: - $ref: definitions/device_keys.yaml one_time_keys: + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here, so we have to hope + # that people will look at the swagger source or can figure it out + # from the other endpoints/example. type: object + title: OneTimeKeys description: |- One-time public keys for "pre-key" messages. The names of the properties should be in the format @@ -61,26 +66,6 @@ paths: by the [key algorithm](/client-server-api/#key-algorithms). May be absent if no new one-time keys are required. - additionalProperties: - type: - - string - - object - # XXX: We can't define an actual object here, so we have to hope - # that people will look at the swagger source or can figure it out - # from the other endpoints/example. - # - type: object - # title: KeyObject - # properties: - # key: - # type: string - # description: The key, encoded using unpadded base64. - # signatures: - # type: object - # description: |- - # Signature for the device. Mapped from user ID to signature object. - # additionalProperties: - # type: string - # required: ['key', 'signatures'] example: { "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", "signed_curve25519:AAAAHg": { @@ -101,8 +86,11 @@ paths: } } fallback_keys: - type: object x-addedInMatrixVersion: "1.2" + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here - see above. + type: object + title: OneTimeKeys description: |- The public key which should be used if the device's one-time keys are exhausted. The fallback key is not deleted once used, but should @@ -117,11 +105,6 @@ paths: be included to denote that the key is a fallback key. May be absent if a new fallback key is not required. - additionalProperties: - type: - - string - - object - # XXX: We can't define an actual object here - see one_time_keys. example: { "curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", "signed_curve25519:AAAAGj": { @@ -420,25 +403,13 @@ paths: additionalProperties: type: object additionalProperties: - type: - - string - - object - # XXX: We can't define an actual object here, so we have to hope - # that people will look at the swagger source or can figure it out - # from the other endpoints/example. - # - type: object - # title: KeyObject - # properties: - # key: - # type: string - # description: The key, encoded using unpadded base64. - # signatures: - # type: object - # description: |- - # Signature for the device. Mapped from user ID to signature object. - # additionalProperties: - # type: string - # required: ['key', 'signatures'] + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here, so we have to hope + # that people will read the link provided in the description + # and figure it out from the other endpoints/example. + # See also one_time_key parameter for /keys/upload above. + type: object + title: OneTimeKeys example: { "@alice:example.com": { "JLAFKJWSCS": { From 8972935ae7cfa8faad571c3f720f9d2850c658b3 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 14 Jun 2022 18:57:58 +0200 Subject: [PATCH 2/2] Changelog --- changelogs/client_server/newsfragments/1127.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1127.clarification diff --git a/changelogs/client_server/newsfragments/1127.clarification b/changelogs/client_server/newsfragments/1127.clarification new file mode 100644 index 000000000..3ccb23339 --- /dev/null +++ b/changelogs/client_server/newsfragments/1127.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification.