# Copyright 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 Cross Signing API version: 1.0.0 paths: /keys/device_signing/upload: post: x-addedInMatrixVersion: "1.1" summary: Upload cross-signing keys. description: |- Publishes cross-signing keys for the user. This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). operationId: uploadCrossSigningKeys security: - accessTokenQuery: [] - accessTokenBearer: [] requestBody: content: application/json: schema: type: object properties: master_key: description: Optional. The user\'s master key. allOf: - $ref: definitions/cross_signing_key.yaml self_signing_key: description: |- Optional. The user\'s self-signing key. Must be signed by the accompanying master key, or by the user\'s most recently uploaded master key if no master key is included in the request. allOf: - $ref: definitions/cross_signing_key.yaml user_signing_key: description: |- Optional. The user\'s user-signing key. Must be signed by the accompanying master key, or by the user\'s most recently uploaded master key if no master key is included in the request. allOf: - $ref: definitions/cross_signing_key.yaml auth: description: |- Additional authentication information for the user-interactive authentication API. allOf: - $ref: definitions/auth_data.yaml example: { "auth": { "type": "example.type.foo", "session": "xxxxx", "example_credential": "verypoorsharedsecret" }, "master_key": { "user_id": "@alice:example.com", "usage": [ "master" ], "keys": { "ed25519:base64+master+public+key": "base64+master+public+key" } }, "self_signing_key": { "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" } } }, "user_signing_key": { "user_id": "@alice:example.com", "usage": [ "user_signing" ], "keys": { "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key" }, "signatures": { "@alice:example.com": { "ed25519:base64+master+public+key": "signature+of+user+signing+key" } } } } description: The keys to be published. required: true responses: "200": description: The provided keys were successfully uploaded. content: application/json: schema: type: object example: {} "400": description: |- The input was invalid in some way. This can include one of the following error codes: * `M_INVALID_SIGNATURE`: For example, the self-signing or user-signing key had an incorrect signature. * `M_MISSING_PARAM`: No master key is available. content: application/json: 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 not authorized for any other reason. content: application/json: schema: type: object example: { "errcode": "M_FORBIDDEN", "error": "Key ID in use" } tags: - End-to-end encryption /keys/signatures/upload: post: x-addedInMatrixVersion: "1.1" summary: Upload cross-signing signatures. description: |- Publishes cross-signing signatures for the user. The signed JSON object must match the key previously uploaded or retrieved for the given key ID, with the exception of the `signatures` property, which contains the new signature(s) to add. operationId: uploadCrossSigningSignatures security: - accessTokenQuery: [] - accessTokenBearer: [] requestBody: content: application/json: schema: type: object description: |- A map of user ID to a map of key ID to signed JSON object. patternProperties: "^@": x-pattern-format: mx-user-id type: object additionalProperties: type: object example: { "@alice:example.com": { "HIJKLMN": { "user_id": "@alice:example.com", "device_id": "HIJKLMN", "algorithms": [ "m.olm.v1.curve25519-aes-sha256", "m.megolm.v1.aes-sha" ], "keys": { "curve25519:HIJKLMN": "base64+curve25519+key", "ed25519:HIJKLMN": "base64+ed25519+key" }, "signatures": { "@alice:example.com": { "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" } } }, "base64+master+public+key": { "user_id": "@alice:example.com", "usage": [ "master" ], "keys": { "ed25519:base64+master+public+key": "base64+master+public+key" }, "signatures": { "@alice:example.com": { "ed25519:HIJKLMN": "base64+signature+of+master+key" } } } }, "@bob:example.com": { "bobs+base64+master+public+key": { "user_id": "@bob:example.com", "keys": { "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" }, "usage": [ "master" ], "signatures": { "@alice:example.com": { "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" } } } } } description: |- A map from user ID to key ID to signed JSON objects containing the signatures to be published. required: true responses: "200": description: The provided signatures were processed. content: application/json: schema: type: object properties: failures: type: object description: |- A map from user ID to key ID to an error for any signatures that failed. If a signature was invalid, the `errcode` will be set to `M_INVALID_SIGNATURE`. patternProperties: "^@": type: object x-pattern-format: mx-user-id additionalProperties: type: object title: Error example: "@alice:example.com": HIJKLMN: errcode: M_INVALID_SIGNATURE error: Invalid signature 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