You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/client-server/key_backup.yaml

1058 lines
36 KiB
YAML

# Copyright 2019-2020 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.
openapi: 3.1.0
info:
title: Matrix Client-Server Key Backup API
version: 1.0.0
paths:
/room_keys/version:
post:
x-addedInMatrixVersion: "1.1"
summary: Create a new backup.
description: Creates a new backup.
operationId: postRoomKeysVersion
security:
- accessTokenQuery: []
- accessTokenBearer: []
requestBody:
content:
application/json:
schema:
type: object
properties:
algorithm:
description: The algorithm used for storing backups.
type: string
enum:
- m.megolm_backup.v1.curve25519-aes-sha2
example: m.megolm_backup.v1.curve25519-aes-sha2
auth_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
expected format of the data.
type: object
example:
public_key: abcdefg
signatures:
"@alice:example.org":
ed25519:deviceid: signature
required:
- algorithm
- auth_data
description: The backup configuration.
required: true
responses:
"200":
description: The version id of the new backup.
content:
application/json:
schema:
type: object
properties:
version:
type: string
description: The backup version. This is an opaque string.
example: "1"
required:
- version
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
get:
x-addedInMatrixVersion: "1.1"
summary: Get information about the latest backup version.
description: Get information about the latest backup version.
operationId: getRoomKeysVersionCurrent
security:
- accessTokenQuery: []
- accessTokenBearer: []
responses:
"200":
description: The information about the backup.
content:
application/json:
schema:
type: object
properties:
algorithm:
type: string
description: The algorithm used for storing backups.
enum:
- m.megolm_backup.v1.curve25519-aes-sha2
example: m.megolm_backup.v1.curve25519-aes-sha2
auth_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
expected format of the data.
type: object
example:
public_key: abcdefg
signatures:
"@alice:example.org":
ed25519:deviceid: signature
count:
description: The number of keys stored in the backup.
type: integer
example: 42
etag:
description: |-
An opaque string representing stored keys in the backup.
Clients can compare it with the `etag` value they received
in the request of their last key storage request. If not
equal, another client has modified the backup.
type: string
example: anopaquestring
version:
type: string
description: The backup version.
example: "1"
required:
- algorithm
- auth_data
- count
- etag
- version
"404":
description: No backup exists.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "No current backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
"/room_keys/version/{version}":
get:
x-addedInMatrixVersion: "1.1"
summary: Get information about an existing backup.
description: Get information about an existing backup.
operationId: getRoomKeysVersion
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: path
name: version
description: |-
The backup version to get, as returned in the `version` parameter
of the response in
[`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
or this endpoint.
required: true
example: "1"
schema:
type: string
responses:
"200":
description: The information about the requested backup.
content:
application/json:
schema:
type: object
properties:
algorithm:
type: string
description: The algorithm used for storing backups.
enum:
- m.megolm_backup.v1.curve25519-aes-sha2
example: m.megolm_backup.v1.curve25519-aes-sha2
auth_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
expected format of the data.
type: object
example:
public_key: abcdefg
signatures:
"@alice:example.org":
ed25519:deviceid: signature
count:
description: The number of keys stored in the backup.
type: integer
example: 42
etag:
description: |-
An opaque string representing stored keys in the backup.
Clients can compare it with the `etag` value they received
in the request of their last key storage request. If not
equal, another client has modified the backup.
type: string
example: anopaquestring
version:
type: string
description: The backup version.
example: "1"
required:
- algorithm
- auth_data
- count
- etag
- version
"404":
description: The backup specified does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
put:
x-addedInMatrixVersion: "1.1"
summary: Update information about an existing backup.
description: Update information about an existing backup. Only `auth_data` can
be modified.
operationId: putRoomKeysVersion
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: path
name: version
description: |-
The backup version to update, as returned in the `version`
parameter in the response of
[`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion).
required: true
example: "1"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
algorithm:
description: |-
The algorithm used for storing backups. Must be the same as
the algorithm currently used by the backup.
type: string
enum:
- m.megolm_backup.v1.curve25519-aes-sha2
example: m.megolm_backup.v1.curve25519-aes-sha2
auth_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
expected format of the data.
type: object
example:
public_key: abcdefg
signatures:
"@alice:example.org":
ed25519:deviceid: signature
version:
description: |-
The backup version. If present, must be the same as the
version in the path parameter.
type: string
example: "1"
required:
- algorithm
- auth_data
description: The backup configuration
required: true
responses:
"200":
description: The update succeeded.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: |-
A parameter was incorrect. For example, the `algorithm` does not
match the current backup algorithm, or the `version` in the body
does not match the `version` in the path.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Algorithm does not match"
}
"404":
description: The backup specified does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
delete:
x-addedInMatrixVersion: "1.1"
summary: Delete an existing key backup.
description: |-
Delete an existing key backup. Both the information about the backup,
as well as all key data related to the backup will be deleted.
operationId: deleteRoomKeysVersion
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: path
name: version
description: |-
The backup version to delete, as returned in the `version`
parameter in the response of
[`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion).
required: true
example: "1"
schema:
type: string
responses:
"200":
description: |-
The delete succeeded, or the specified backup was previously
deleted.
content:
application/json:
schema:
type: object
properties: {}
"404":
description: |-
The backup specified does not exist. If the backup was previously
deleted, the call should succeed rather than returning an error.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
"/room_keys/keys/{roomId}/{sessionId}":
put:
x-addedInMatrixVersion: "1.1"
summary: Store a key in the backup.
description: Store a key in the backup.
operationId: putRoomKeyBySessionId
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup in which to store the key. Must be the current backup.
required: true
example: "1"
schema:
type: string
- in: path
name: roomId
description: The ID of the room that the key is for.
required: true
example: "!roomid:example.org"
schema:
type: string
- in: path
name: sessionId
description: The ID of the megolm session that the key is for.
required: true
example: sessionid
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: definitions/key_backup_data.yaml
description: The key data.
required: true
responses:
"200":
description: The update succeeded.
content:
application/json:
schema:
type: object
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"403":
description: |-
The version specified does not match the current backup version.
The current version will be included in the `current_version`
field.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
"error": "Wrong backup version.",
"current_version": "42"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
get:
x-addedInMatrixVersion: "1.1"
summary: Retrieve a key from the backup.
description: Retrieve a key from the backup.
operationId: getRoomKeyBySessionId
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup from which to retrieve the key.
required: true
example: "1"
schema:
type: string
- in: path
name: roomId
description: The ID of the room that the requested key is for.
required: true
example: "!roomid:example.org"
schema:
type: string
- in: path
name: sessionId
description: The ID of the megolm session whose key is requested.
required: true
example: sessionid
schema:
type: string
responses:
"200":
description: The key data
content:
application/json:
schema:
$ref: definitions/key_backup_data.yaml
"404":
description: The key or backup was not found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Key not found."
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
delete:
x-addedInMatrixVersion: "1.1"
summary: Delete a key from the backup.
description: Delete a key from the backup.
operationId: deleteRoomKeyBySessionId
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup from which to delete the key
required: true
example: "1"
schema:
type: string
- in: path
name: roomId
description: The ID of the room that the specified key is for.
required: true
example: "!roomid:example.org"
schema:
type: string
- in: path
name: sessionId
description: The ID of the megolm session whose key is to be deleted.
required: true
example: sessionid
schema:
type: string
responses:
"200":
description: The update succeeded
content:
application/json:
schema:
type: object
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"404":
description: The backup was not found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
"/room_keys/keys/{roomId}":
put:
x-addedInMatrixVersion: "1.1"
summary: Store several keys in the backup for a given room.
description: Store several keys in the backup for a given room.
operationId: putRoomKeysByRoomId
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup in which to store the keys. Must be the current backup.
required: true
example: "1"
schema:
type: string
- in: path
name: roomId
description: The ID of the room that the keys are for.
required: true
example: "!roomid:example.org"
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: definitions/room_key_backup.yaml
description: The backup data
required: true
responses:
"200":
description: The update succeeded
content:
application/json:
schema:
type: object
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"403":
description: |-
The version specified does not match the current backup version.
The current version will be included in the `current_version`
field.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
"error": "Wrong backup version.",
"current_version": "42"
}
"404":
description: The backup was not found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
get:
x-addedInMatrixVersion: "1.1"
summary: Retrieve the keys from the backup for a given room.
description: Retrieve the keys from the backup for a given room.
operationId: getRoomKeysByRoomId
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup from which to retrieve the key.
required: true
example: "1"
schema:
type: string
- in: path
name: roomId
description: The ID of the room that the requested key is for.
required: true
example: "!roomid:example.org"
schema:
type: string
responses:
"200":
description: |-
The key data. If no keys are found, then an object with an empty
`sessions` property will be returned (`{"sessions": {}}`).
content:
application/json:
schema:
type: object
$ref: definitions/room_key_backup.yaml
"404":
description: The backup was not found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
delete:
x-addedInMatrixVersion: "1.1"
summary: Delete the keys from the backup for a given room.
description: Delete the keys from the backup for a given room.
operationId: deleteRoomKeysByRoomId
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup from which to delete the key.
required: true
example: "1"
schema:
type: string
- in: path
name: roomId
description: The ID of the room that the specified key is for.
required: true
example: "!roomid:example.org"
schema:
type: string
responses:
"200":
description: The update succeeded
content:
application/json:
schema:
type: object
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"404":
description: The backup was not found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
/room_keys/keys:
put:
x-addedInMatrixVersion: "1.1"
summary: Store several keys in the backup.
description: Store several keys in the backup.
operationId: putRoomKeys
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup in which to store the keys. Must be the current backup.
required: true
example: "1"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
rooms:
type: object
description: A map of room IDs to room key backup data.
additionalProperties:
$ref: definitions/room_key_backup.yaml
example:
"!room:example.org":
sessions:
sessionid1:
first_message_index: 1
forwarded_count: 0
is_verified: true
session_data:
ephemeral: base64+ephemeral+key
ciphertext: base64+ciphertext+of+JSON+data
mac: base64+mac+of+ciphertext
required:
- rooms
description: The backup data.
required: true
responses:
"200":
description: The update succeeded
content:
application/json:
schema:
type: object
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"403":
description: |-
The version specified does not match the current backup version.
The current version will be included in the `current_version`
field.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
"error": "Wrong backup version.",
"current_version": "42"
}
"404":
description: The backup was not found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
get:
x-addedInMatrixVersion: "1.1"
summary: Retrieve the keys from the backup.
description: Retrieve the keys from the backup.
operationId: getRoomKeys
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup from which to retrieve the keys.
required: true
example: "1"
schema:
type: string
responses:
"200":
description: |-
The key data. If no keys are found, then an object with an empty
`rooms` property will be returned (`{"rooms": {}}`).
content:
application/json:
schema:
type: object
properties:
rooms:
type: object
description: A map of room IDs to room key backup data.
additionalProperties:
$ref: definitions/room_key_backup.yaml
example:
"!room:example.org":
sessions:
sessionid1:
first_message_index: 1
forwarded_count: 0
is_verified: true
session_data:
ephemeral: base64+ephemeral+key
ciphertext: base64+ciphertext+of+JSON+data
mac: base64+mac+of+ciphertext
required:
- rooms
"404":
description: The backup was not found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version."
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
delete:
x-addedInMatrixVersion: "1.1"
summary: Delete the keys from the backup.
description: Delete the keys from the backup.
operationId: deleteRoomKeys
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: version
description: The backup from which to delete the key
required: true
example: "1"
schema:
type: string
responses:
"200":
description: The update succeeded
content:
application/json:
schema:
type: object
title: RoomKeysUpdateResponse
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See `GET /room_keys/version/{version}` for more details.
type: string
example: abcdefg
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
"404":
description: The backup was not found.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- End-to-end encryption
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery
accessTokenBearer:
$ref: definitions/security.yaml#/accessTokenBearer