data/api/client-server/keys.yaml - main - Undeadguy/matrix-spec

data/api/client-server/keys.yaml
482 строки21 KB
Andy Balaam
Specify the order in which one-time keys are returned (MSC4225) (#2029)
12 дек 2024, 18:53
12 дек 2024, 18:5335c3ddb
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
# 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 Client Config API
  version: 1.0.0
paths:
  /keys/upload:
    post:
      summary: Upload end-to-end encryption keys.
      description: Publishes end-to-end encryption keys for the device.
      operationId: uploadKeys
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                device_keys:
                  description: |-
                    Identity keys for the device. May be absent if no new
                    identity keys are required.
                  allOf:
                    - $ref: definitions/device_keys.yaml
                one_time_keys:
                  allOf:
                    - $ref: "definitions/one_time_keys.yaml"
                  type: object
                  description: |-
                    One-time public keys for "pre-key" messages.  The names of
                    the properties should be in the format
                    `<algorithm>:<key_id>`. The format of the key is determined
                    by the [key algorithm](/client-server-api/#key-algorithms).

                    May be absent if no new one-time keys are required.
                  example:
                    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
                fallback_keys:
                  x-addedInMatrixVersion: "1.2"
                  allOf:
                    - $ref: "definitions/one_time_keys.yaml"
                  type: object
                  description: |-
                    The public key which should be used if the device's one-time keys
                    are exhausted. The fallback key is not deleted once used, but should
                    be replaced when additional one-time keys are being uploaded. The
                    server will notify the client of the fallback key being used through
                    `/sync`.

                    There can only be at most one key per algorithm uploaded, and the server
                    will only persist one key per algorithm.

                    When uploading a signed key, an additional `fallback: true` key should
                    be included to denote that the key is a fallback key.

                    May be absent if a new fallback key is not required.
                  example:
                    signed_curve25519:AAAAGj:
                      key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
                      fallback: true
                      signatures:
                        "@alice:example.com":
                          ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
        description: The keys to be published
        required: true
      responses:
        "200":
          description: The provided keys were successfully uploaded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  one_time_key_counts:
                    type: object
                    additionalProperties:
                      type: integer
                    description: |-
                      For each key algorithm, the number of unclaimed one-time keys
                      of that type currently held on the server for this device.
                      If an algorithm is not listed, the count for that algorithm
                      is to be assumed zero.
                    example:
                      signed_curve25519: 20
                required:
                  - one_time_key_counts
      tags:
        - End-to-end encryption
  /keys/query:
    post:
      summary: Download device identity keys.
      description: Returns the current devices and identity keys for the given users.
      operationId: queryKeys
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                timeout:
                  type: integer
                  description: |-
                    The time (in milliseconds) to wait when downloading keys from
                    remote servers. 10 seconds is the recommended default.
                  example: 10000
                device_keys:
                  type: object
                  description: |-
                    The keys to be downloaded. A map from user ID, to a list of
                    device IDs, or to an empty list to indicate all devices for the
                    corresponding user.
                  patternProperties:
                    "^@":
                      x-pattern-format: mx-user-id
                      type: array
                      items:
                        type: string
                        description: device ID
                  example:
                    "@alice:example.com": []
              required:
                - device_keys
        description: Query defining the keys to be downloaded
        required: true
      responses:
        "200":
          description: The device information
          content:
            application/json:
              schema:
                type: object
                properties:
                  failures:
                    type: object
                    description: |-
                      If any remote homeservers could not be reached, they are
                      recorded here. The names of the properties are the names of
                      the unreachable servers.

                      If the homeserver could be reached, but the user or device
                      was unknown, no failure is recorded. Instead, the corresponding
                      user or device is missing from the `device_keys` result.
                    additionalProperties:
                      type: object
                    example: {}
                  device_keys:
                    type: object
                    description: |-
                      Information on the queried devices. A map from user ID, to a
                      map from device ID to device information.  For each device,
                      the information returned will be the same as uploaded via
                      `/keys/upload`, with the addition of an `unsigned`
                      property.
                    patternProperties:
                      "^@":
                        x-pattern-format: mx-user-id
                        type: object
                        additionalProperties:
                          title: DeviceInformation
                          allOf:
                            - $ref: definitions/device_keys.yaml
                          properties:
                            unsigned:
                              title: UnsignedDeviceInfo
                              type: object
                              description: |-
                                Additional data added to the device key information
                                by intermediate servers, and not covered by the
                                signatures.
                              properties:
                                device_display_name:
                                  type: string
                                  description: The display name which the user set on the device.
                    example:
                      "@alice:example.com":
                        JLAFKJWSCS:
                          user_id: "@alice:example.com"
                          device_id: JLAFKJWSCS
                          algorithms:
                            - m.olm.v1.curve25519-aes-sha2
                            - m.megolm.v1.aes-sha2
                          keys:
                            curve25519:JLAFKJWSCS: 3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI
                            ed25519:JLAFKJWSCS: lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI
                          signatures:
                            "@alice:example.com":
                              ed25519:JLAFKJWSCS: dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA
                          unsigned:
                            device_display_name: Alice's mobile phone
                  master_keys:
                    x-addedInMatrixVersion: "1.1"
                    type: object
                    description: |-
                      Information on the master cross-signing keys of the queried users.
                      A map from user ID, to master key information.  For each key, the
                      information returned will be the same as uploaded via
                      `/keys/device_signing/upload`, along with the signatures
                      uploaded via `/keys/signatures/upload` that the requesting user
                      is allowed to see.
                    patternProperties:
                      "^@":
                        x-pattern-format: mx-user-id
                        allOf:
                          - $ref: definitions/cross_signing_key.yaml
                    example:
                      "@alice:example.com":
                        user_id: "@alice:example.com"
                        usage:
                          - master
                        keys:
                          ed25519:base64+master+public+key: base64+master+public+key
                  self_signing_keys:
                    x-addedInMatrixVersion: "1.1"
                    type: object
                    description: |-
                      Information on the self-signing keys of the queried users. A map
                      from user ID, to self-signing key information.  For each key, the
                      information returned will be the same as uploaded via
                      `/keys/device_signing/upload`.
                    patternProperties:
                      "^@":
                        x-pattern-format: mx-user-id
                        allOf:
                          - $ref: definitions/cross_signing_key.yaml
                    example:
                      "@alice:example.com":
                        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_keys:
                    type: object
                    description: |-
                      Information on the user-signing key of the user making the
                      request, if they queried their own device information. A map
                      from user ID, to user-signing key information.  The
                      information returned will be the same as uploaded via
                      `/keys/device_signing/upload`.
                    patternProperties:
                      "^@":
                        x-pattern-format: mx-user-id
                        allOf:
                          - $ref: definitions/cross_signing_key.yaml
                    example:
                      "@alice:example.com":
                        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
      tags:
        - End-to-end encryption
  /keys/claim:
    post:
      summary: Claim one-time encryption keys.
      description: |-
        Claims one-time keys for use in pre-key messages.

        The request contains the user ID, device ID and algorithm name of the
        keys that are required. If a key matching these requirements can be
        found, the response contains it. The returned key is a one-time key
        if one is available, and otherwise a fallback key.

        One-time keys are given out in the order that they were uploaded via
        [/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All
        keys uploaded within a given call to `/keys/upload` are considered
        equivalent in this regard; no ordering is specified within them.)

        Servers must ensure that each one-time key is returned at most once,
        so when a key has been returned, no other request will ever return
        the same key.
      operationId: claimKeys
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                timeout:
                  type: integer
                  description: |-
                    The time (in milliseconds) to wait when downloading keys from
                    remote servers. 10 seconds is the recommended default.
                  example: 10000
                one_time_keys:
                  type: object
                  description: |-
                    The keys to be claimed. A map from user ID, to a map from
                    device ID to algorithm name.
                  patternProperties:
                    "^@":
                      x-pattern-format: mx-user-id
                      type: object
                      additionalProperties:
                        type: string
                        description: algorithm
                        example: signed_curve25519
                  example:
                    "@alice:example.com":
                      JLAFKJWSCS: signed_curve25519
              required:
                - one_time_keys
        description: Query defining the keys to be claimed
        required: true
      responses:
        "200":
          description: The claimed keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  failures:
                    type: object
                    description: |-
                      If any remote homeservers could not be reached, they are
                      recorded here. The names of the properties are the names of
                      the unreachable servers.

                      If the homeserver could be reached, but the user or device
                      was unknown, no failure is recorded. Instead, the corresponding
                      user or device is missing from the `one_time_keys` result.
                    additionalProperties:
                      type: object
                    example: {}
                  one_time_keys:
                    type: object
                    description: |-
                      One-time keys for the queried devices. A map from user ID, to a
                      map from devices to a map from `<algorithm>:<key_id>` to the key object.

                      See the [key algorithms](/client-server-api/#key-algorithms) section for information
                      on the Key Object format.

                      If necessary, the claimed key might be a fallback key. Fallback
                      keys are re-used by the server until replaced by the device.
                    patternProperties:
                      "^@":
                        x-pattern-format: mx-user-id
                        type: object
                        additionalProperties:
                          $ref: "definitions/one_time_keys.yaml"
                    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:
        - End-to-end encryption
  /keys/changes:
    get:
      summary: Query users with recent device key updates.
      description: |-
        Gets a list of users who have updated their device identity keys since a
        previous sync token.

        The server should include in the results any users who:

        * currently share a room with the calling user (ie, both users have
          membership state `join`); *and*
        * added new device identity keys or removed an existing device with
          identity keys, between `from` and `to`.
      operationId: getKeysChanges
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: from
          description: |-
            The desired start point of the list. Should be the `next_batch` field
            from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not
            uploaded new device identity keys since this point, nor deleted
            existing devices with identity keys since then, will be excluded
            from the results.
          required: true
          example: s72594_4483_1934
          schema:
            type: string
        - in: query
          name: to
          description: |-
            The desired end point of the list. Should be the `next_batch`
            field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent
            such call. This may be used by the server as a hint to check its
            caches are up to date.
          required: true
          example: s75689_5632_2435
          schema:
            type: string
      responses:
        "200":
          description: The list of users who updated their devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  changed:
                    type: array
                    items:
                      type: string
                    description: |-
                      The Matrix User IDs of all users who updated their device
                      identity keys.
                    example:
                      - "@alice:example.com"
                      - "@bob:example.org"
                  left:
                    type: array
                    items:
                      type: string
                    description: |-
                      The Matrix User IDs of all users who may have left all
                      the end-to-end encrypted rooms they previously shared
                      with the user.
                    example:
                      - "@clara:example.com"
                      - "@doug:example.org"
      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