matrix-spec/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.
swagger: '2.0'
info:
  title: "Matrix Client-Server Cross Signing API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/keys/device_signing/upload":
    post:
      summary: Upload cross-signing keys.
      description: |-
        Publishes cross-signing keys for the user.

        This API endpoint uses the `User-Interactive Authentication API`_.        
      operationId: uploadCrossSigningKeys
      security:
        - accessToken: []
      parameters:
        - in: body
          name: keys
          description: |-
                        The keys to be published.
          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 with
                  the accompanied master, 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 with
                  the accompanied master, 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
            example: {
              "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"
                  }
                }
              }
            }
      responses:
        200:
          description: The provided keys were successfully uploaded.
          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``: The self-signing or user-signing key
              had an incorrect signature
            * ``M_FORBIDDEN``: The public key of one of the keys is the same as
              one of the user\'s device IDs.            
          schema:
            type: object
            example: {
              "errcode": "M_INVALID_SIGNATURE",
              "error": "Invalid signature"
            }
  "/keys/signatures/upload":
    post:
      summary: Upload cross-signing signatures.
      description: |-
        Publishes cross-signing signatures for the user.  The request body is a
        map from user ID to key ID to signed JSON object.        
      operationId: uploadCrossSigningSignatures
      security:
        - accessToken: []
      parameters:
        - in: body
          name: signatures
          description: |-
                        The signatures to be published.
          schema:
            type: object
            example: {
              "@alice:example.com": {
                "HIJKLMN": {
                  "user_id": "@alice:example.com",
                  "device_id": "HIJKLMN",
                  "algorithms": [
                    "m.olm.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+self+signing+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"
                    }
                  }
                }
              }
            }
      responses:
        200:
          description: The provided signatures were processed.
          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"
                    }
                  }
                }