Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2025-12-20 16:38:37 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge pull request #2083 from matrix-org/travis/1.0/key-object

Browse source 
Clarify the key object definition for the key management API
This commit is contained in:
Travis Ralston 2019-06-11 09:50:34 -06:00 committed by GitHub
parent 19f017f9bd 8b7887dfc2
commit 8ac555f870
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 103 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

100
api/client-server/keys.yaml
View file

@ -56,25 +56,48 @@ paths:
One-time public keys for "pre-key" messages. The names of One-time public keys for "pre-key" messages. The names of
the properties should be in the format the properties should be in the format
``<algorithm>:<key_id>``. The format of the key is determined ``<algorithm>:<key_id>``. The format of the key is determined
by the key algorithm. by the `key algorithm <#key-algorithms>`_.
May be absent if no new one-time keys are required. May be absent if no new one-time keys are required.
additionalProperties: additionalProperties:
type: type:
- string - string
- object - object
example: # XXX: We can't define an actual object here, so we have to hope
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8" # that people will look at the swagger source or can figure it out
signed_curve25519:AAAAHg: # from the other endpoints/example.
key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs" # - type: object
signatures: # title: KeyObject
"@alice:example.com": # properties:
ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" # key:
signed_curve25519:AAAAHQ: # type: string
key: "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw" # description: The key, encoded using unpadded base64.
signatures: # signatures:
"@alice:example.com": # type: object
ed25519:JLAFKJWSCS: "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA" # 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": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
},
"signed_curve25519:AAAAHQ": {
"key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
}
}
}
}
responses: responses:
200: 200:
description: description:
@ -205,12 +228,12 @@ paths:
"@alice:example.com": { "@alice:example.com": {
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
} }
}, },
"unsigned": { "unsigned": {
"device_display_name": "Alice's mobile phone" "device_display_name": "Alice's mobile phone"
} }
} }
tags: tags:
- End-to-end encryption - End-to-end encryption
"/keys/claim": "/keys/claim":
@ -246,8 +269,9 @@ paths:
type: string type: string
description: algorithm description: algorithm
example: "signed_curve25519" example: "signed_curve25519"
example: example: {
"@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
}
required: required:
- one_time_keys - one_time_keys
responses: responses:
@ -263,7 +287,7 @@ paths:
If any remote homeservers could not be reached, they are If any remote homeservers could not be reached, they are
recorded here. The names of the properties are the names of recorded here. The names of the properties are the names of
the unreachable servers. the unreachable servers.
If the homeserver could be reached, but the user or device If the homeserver could be reached, but the user or device
was unknown, no failure is recorded. Instead, the corresponding was unknown, no failure is recorded. Instead, the corresponding
user or device is missing from the ``one_time_keys`` result. user or device is missing from the ``one_time_keys`` result.
@ -275,20 +299,46 @@ paths:
description: |- description: |-
One-time keys for the queried devices. A map from user ID, to a One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from ``<algorithm>:<key_id>`` to the key object. map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
See the `key algorithms <#key-algorithms>`_ section for information
on the Key Object format.
additionalProperties: additionalProperties:
type: object type: object
additionalProperties: additionalProperties:
type: type:
- string - string
- object - object
example: # XXX: We can't define an actual object here, so we have to hope
"@alice:example.com": # that people will look at the swagger source or can figure it out
JLAFKJWSCS: # from the other endpoints/example.
signed_curve25519:AAAAHg: # - type: object
key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs" # title: KeyObject
signatures: # properties:
"@alice:example.com": # key:
ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" # 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: {
"@alice:example.com": {
"JLAFKJWSCS": {
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
}
}
required: ['one_time_keys']
tags: tags:
- End-to-end encryption - End-to-end encryption
"/keys/changes": "/keys/changes":

40
api/server-server/user_keys.yaml
View file

@ -72,30 +72,42 @@ paths:
description: |- description: |-
One-time keys for the queried devices. A map from user ID, to a One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from ``<algorithm>:<key_id>`` to the key object. map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
See the Client-Server Key Algorithms section for more information on
the Key Object format.
additionalProperties: additionalProperties:
type: object type: object
additionalProperties: additionalProperties:
type: type:
- string - string
- object - type: object
required: ['one_time_keys'] title: KeyObject
examples: properties:
application/json: { key:
"one_time_keys": { type: string
"@alice:example.com": { description: The key, encoded using unpadded base64.
"JLAFKJWSCS": { signatures:
"signed_curve25518:AAAAHg": { type: object
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", description: |-
"signatures": { Signature for the device. Mapped from user ID to signature object.
"@alice:example.com": { additionalProperties:
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" type: string
required: ['key', 'signatures']
example: {
"@alice:example.com": {
"JLAFKJWSCS": {
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
} }
} }
} }
} }
} }
} required: ['one_time_keys']
}
"/user/keys/query": "/user/keys/query":
post: post:
summary: Download device identity keys. summary: Download device identity keys.

1
changelogs/client_server/newsfragments/2083.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the key object definition for the key management API.

1
changelogs/server_server/newsfragments/2083.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the key object definition for the key management API.