matrix-spec/data/api/client-server/cross_signing.yaml

# 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.
              additionalProperties:
                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`.
                    additionalProperties:
                      type: object
                      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