Clarify the key object definition for the key management API

Fixes https://github.com/matrix-org/matrix-doc/issues/1907


One too far
This commit is contained in:
Travis Ralston 2019-06-05 21:10:38 -06:00
parent 9ac89cc915
commit a19eb59f13
4 changed files with 96 additions and 42 deletions

View file

@ -59,22 +59,41 @@ paths:
by the key algorithm. by the key algorithm.
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 - type: object
example: title: KeyObject
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8" properties:
signed_curve25519:AAAAHg: key:
key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs" type: string
signatures: description: The key, encoded using unpadded base64.
"@alice:example.com": signatures:
ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" type: object
signed_curve25519:AAAAHQ: description: |-
key: "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw" Signature for the device. Mapped from user ID to signature object.
signatures: additionalProperties:
"@alice:example.com": type: string
ed25519:JLAFKJWSCS: "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA" 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:
@ -246,8 +265,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:
@ -281,14 +301,37 @@ paths:
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":

View file

@ -77,25 +77,34 @@ paths:
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.

View file

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

View file

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