Changes for V0.2.1

**IMPORTANT: These [OpenAPI](https://www.openapis.org/) specifications are under development and subject to change.**

Note: The default branch in this repository has been renamed `main` as per QKD(23)033d002.

## Visualise

View API in [Swagger Editor](https://forge.etsi.org/swagger/editor-versions/v3.8.0/?url=https://forge.etsi.org/rep/qkd/gs020-interop-kms/raw/master/interop-kms.yaml).

# Copyright 2022 ETSI

# Copyright 2023 ETSI

# Licensed under the BSD-3 Clause (https://forge.etsi.org/legal-matters)

openapi: '3.0.3'

info:

  title: Draft ETSI GS QKD 020 - Interoperable Key Management System API

  description: OpenAPI description of the Interoperable Key Management System API being developed by ETSI ISG QKD under work item DGS/QKD-020_InteropKMS. The interface is intended for use within a trusted node and enables the transfer of keys between key management systems. 

  description: |

    OpenAPI description of the Interoperable Key Management System API being developed by ETSI ISG QKD under work item DGS/QKD-020_InteropKMS.

    The interface is intended for use within a trusted node and enables the transfer of keys between key management systems.

  contact:

    name: ETSI ISG QKD

    email: 'isgsupport@etsi.org'

  version: '0.1.1'

  version: '0.2.1'

  license:

    name: BSD 3-Clause

    url: https://forge.etsi.org/legal-matters

servers:

- url: https://{KME_hostname}/

  description: Local KMS server

- url: https://{kme_hostname}

  description: Local KME server

  variables:

    KME_hostname:

    kme_hostname:

      default: '127.0.0.1:443'

externalDocs:

  description: 'Work Item description.'

  description: 'Work Item description'

  url: 'https://portal.etsi.org/webapp/WorkProgram/Report_WorkItem.asp?WKI_ID=63115'

tags:

- name: 'Extended Specification'

paths:

  /kdapi/v2/ext_keys:

  /kmapi/versions:

    get:

      summary: 'Get supported API versions'

      operationId: get-versions

      description: |

        Return list of supported ETSI GS QKD 020 API versions.

        When an SAE makes a request to a KME, it should use the most recent version of the API that the KME and SAE support.

        The SAE can use this end-point to determine which API versions the KME supports.

      responses:

        '200':

          description: Supported versions

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/version_container'

        '401':

          $ref: '#/components/responses/401-extkey'

        '503':

          $ref: '#/components/responses/503-extkey'

  /kmapi/v1/ext_keys/{initiator_sae_id}/{target_sae_id}:

    post:

      summary: 'Transfer keys to external KMS for delivery'

      tags:

      - 'Extended Specification'

      description: 'Pass an Extended Key Container comprising key material and associated data to another KME, for the key(s) to be delivered (by relay where necessary) to the target SAE(s) specified. The Extended Key Container contains keys matching those to be delivered to the initiator SAE.'

      summary: 'Transfer keys to external KMS'

      operationId: post-ext_keys

      description: |

        Pass an extended key request container comprising key material and associated data to another KME, for the key(s) to be delivered (by relay where necessary) to the target SAE(s) specified. The extended key request container contains keys matching those to be delivered to the initiator SAE.

        If this method is called without specifying an `ack_callback_url`, it will execute in 'blocking mode', whereby the KME will only respond once the keys have been relayed to the KME corresponding to the `target_sae_id`. If this method is called with an `ack_callback_url` specified, then it will execute in 'non-blocking mode', whereby the KME will respond quickly with an HTTP code 202 ('Accepted'), then it will issue a separate call (or multiple calls) to the `ack_callback_url` endpoint once the keys are actually delivered (or fail to be delivered).

        When 'non-blocking mode' is requested, the server shall respond with Code 202 if it accepts the request.

        When operating in 'blocking mode', there will be a delay while the remote KMS relays the key(s), then a Code 200 response will be returned. This response includes a status field which may have either the value `success` or `partial_success`. `success` indicates that all keys were delivered to the destination KME. An array of acknowledgement containers may be optionally returned that includes extension fields (which could be, e.g. metadata for each key to indicate its routing information from the remote KMS). If such containers are returned, the extensions should be handled by the requesting KMS (e.g. to keep the provided metadata with each key so it can be relayed to the initiator SAE). If one or more key failed to be relayed successfully the KME shall respond with a value of `partial_success` in the status field and the KME shall return an array of acknowledgement containers that includes the status of each key.

      parameters:

        - $ref: '#/components/parameters/initiator_sae_id'

        - $ref: '#/components/parameters/target_sae_id'

      requestBody:

        description: 'Extended Key Container'

        description: 'Extended key request container.'

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/ext_key_container'

      responses:

        200:

          $ref: '#/components/responses/200-extkey'

        400:

        '200':

          $ref: '#/components/responses/200-request-response'

        '202':

          $ref: '#/components/responses/202-extkey'

        '400':

          $ref: '#/components/responses/400-extkey'

        '401':

          $ref: '#/components/responses/401-extkey'

        '408':

          $ref: '#/components/responses/408-extkey'

        '503':

          $ref: '#/components/responses/503-extkey'

  /kmapi/v1/ext_keys/void/{initiator_sae_id}/{target_sae_id}:

    post:

      summary: 'Signal keys as void to external KMS (i.e. discard keys)'

      operationId: post-ext_keys-void

      description: |

        Pass an extended key request container comprising key IDs to another KME, for the key(s) to be marked as void (i.e. discarded and not delivered to SAEs). The Extended Key Container contains keys matching those already passed to the KME.

        As for `ext_keys`, this method blocks when the `ack_callback_url` field is omitted and operates in non-blocking mode when the `ack_callback_url` field is supplied. If this is called without supplying a `key_ids` array, then all keys shared between the provided SAEs will be voided (to prevent accidental key loss, to confirm this action an `all_confirmation` boolean field must also be passed as true, otherwise a Code 400 error is returned).

      parameters:

        - $ref: '#/components/parameters/initiator_sae_id'

        - $ref: '#/components/parameters/target_sae_id'

        - $ref: '#/components/parameters/all_confirmation'

      requestBody:

        description: 'Void request container'

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/void_container'

      responses:

        '200':

          $ref: '#/components/responses/200-request-response'

        '202':

          $ref: '#/components/responses/202-extkey'

        '400':

          $ref: '#/components/responses/400-extkey-void'

        '401':

          $ref: '#/components/responses/401-extkey'

        '408':

          $ref: '#/components/responses/408-extkey'

        '503':

          $ref: '#/components/responses/503-extkey'

  /kmapi/v1/ext_keys/ack:

    post:

      summary: 'Acknowledge completion of a previous ext_key request'

      operationId: post-ext_keys-ack

      description: 'Pass one or more key acknowledgement containers comprising key IDs associated with a previous (non-blocking) call to the ext_keys method to deliver keys by an external KMS. The status of all keys in the container is indicated by the status field.'

      requestBody:

        description: 'Acknowledgements containers'

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/ack_containers'

      responses:

        '200':

          $ref: '#/components/responses/200-ack-response'

        '400':

          $ref: '#/components/responses/400-extkey-ack'

        '401':

          $ref: '#/components/responses/401-extkey'

        '503':

          $ref: '#/components/responses/503-extkey'

components:

  responses:

    200-extkey:

    200-request-response:

      description: Request processed response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/request_response'

    200-ack-response:

      description: Successful response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/message_data'

    202-extkey:

      description: Request accepted response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/message_data'

    400-extkey:

      description: Bad request format response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/message_data'

          example:

          examples:

            missing_parameters:

              value:

                message: 'missing parameters'

                details:

                  - 'missing_parameters': 'required parameters are missing from the API call'

            unknown_sae_id:

              value:

                message: 'key routing error'

                details:

            - 'One of the target_sae_ids was not recognized': 'KME associated with a target SAE ID is not known.'

                  - 'target_sae_id_not_recognized': 'KME associated with a target SAE ID is not known.'

            no_known_route:

              value:

                message: 'key routing error'

                details:

                  - 'no_known_route': 'KME does not know a route to deliver to target SAE ID.'

            no_passback_allowed:

              value:

                message: 'key routing error'

                details:

                  - 'invalid_routing': 'Routing this key to target SAE ID requires directly passing it back to the calling KME, which is invalid.'

            insufficient_key_material:

              value:

                message: 'insufficient key material'

                details:

                  - 'insufficient_key_material': 'Insufficient key material available to deliver key.'

    400-extkey-void:

      description: Bad request format response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/message_data'

          examples:

            failed:

              value:

                message: 'void request not understood'

                details:

                  - 'key_voiding_error': 'KME cannot parse the submitted void request.'

            key_not_present:

              value:

                message: 'key not present'

                details:

                  - 'key_not_present': 'The requested key ID(s) are not available to be voided.'

            no_key_ids_or_confirmation:

              value:

                message: 'no_key_ids_or_confirmation'

                details:

                  - 'no_key_ids_or_confirmation': 'When no key_ids are passed, all keys shared between the SAEs will be voided. If this is the intended action, the `all_confirmation` field must also be set to true. Otherwise, please specify key_ids to be voided.'

    400-extkey-ack:

      description: Bad request format response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/message_data'

          examples:

            not_understood:

              value:

                message: 'ack not understood'

                details:

                  - 'ack_not_understood': 'KME cannot parse the submitted acknowledgement.'

    401-extkey:

      description: Unauthorized response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/message_data'

          example:

            message: 'unauthorized'

            details:

            - 'unauthorized': 'User-supplied certificate is invalid.'

    408-extkey:

      description: Timeout response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/message_data'

          example:

            message: 'timeout'

            details:

            - 'timeout': 'No response received from KME to ext_keys request in sufficient time.'

    503-extkey:

      description: Error of server side response

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/message_data'

          example:

            message: 'server side general error'

            details:

            - 'server_side_general_error': 'The server encountered a general failure and cannot respond.'

  schemas:

    initiator_sae_id:

      type: string

      description: ID of the SAE that initiated the request to share the key(s) relevant to the request.

      example: encryptor1

    target_sae_id:

      type: string

      description: ID of target SAE that the initiator SAE wishes to share keys with (single target only; for sharing to multiple targets, specify additional_target_sae_ids in body).

      example: encryptor2

    additional_target_sae_ids:

      type: array

      description: Array of IDs of target SAEs. It is used for specifying two or more target SAEs to share identical keys. The maximum number of IDs is defined as max_sae_id_count in Status data format.

      items:

        $ref: '#/components/schemas/target_sae_id'

    key_id:

      description: 'ID of the key: UUID format.'

      type: string

      format: uuid

      example: '550e8400-e29b-41d4-a716-446655440000'

    value:

      description: 'Key data encoded by base64.'

      type: string

      example: 'wHHVxRwDJs3/bXd38GHP3oe4svTuRpZS0yCC7x4Ly+s='

    extension:

      type: object

      description: 'Reserved for future use.'

    extension_mandatory:

      type: array

      description: 'Array of extension parameters specified as name/value pairs that KME shall handle or return an error (e.g. as originated in the Get Key request that triggerded key relaying to use the ext_keys call). Parameter values may be of any type, including objects.'

      items:

        type: object

      example:

        - 'abc_route_type': 'direct'

        - 'abc_transfer_method': 'qkd'

    extension_optional:

      type: array

      description: 'Array of extension parameters specified as name/value pairs that KME may ignore (e.g. as originated in the Get Key request that triggered key relaying to use the ext_keys call). Parameter values may be of any type, including objects.'

      items:

        type: object

      example:

        - 'abc_max_age': 30000

    ack_callback_url:

      description: 'URL to which acknowledgement should be sent after relaying to the KME(s) associated with target SAE(s) (for ‘non-blocking’ operation) completes or fails.'

      type: string

      example: https://kme1/kmapi/v1/ext_keys/ack

    ack_status:

      description: Status of acknowledged keys

      type: string

      enum: [relayed, voided, failed, key not present]

      example: relayed

    keys:

      type: array

      description: 'Array of keys.'

      items:

        type: object

        required:

        - key_id

        - value

        properties:

          key_id:

            $ref: '#/components/schemas/key_id'

          value:

            $ref: '#/components/schemas/value'

          extension:

            $ref: '#/components/schemas/extension'

    ext_key_container:

      title: 'Extended Key Container data format'

      title: 'Extended key request container'

      type: object

      required:

      - keys

      - initiator_sae_id

      - target_sae_id

      properties:

        keys:

          description: 'Array of keys'

          $ref: '#/components/schemas/keys'

        additional_target_sae_ids:

          $ref: '#/components/schemas/additional_target_sae_ids'

        ack_callback_url:

          $ref: '#/components/schemas/ack_callback_url'

        extension_mandatory:

          $ref: '#/components/schemas/extension_mandatory'

        extension_optional:

          $ref: '#/components/schemas/extension_optional'

    key_id_container:

      type: array

      description: 'Array of key IDs.'

      items:

        type: object

        required:

        - key_id

            - key_value

        properties:

          key_id:

                description: 'ID of the key: UUID format'

                type: string

                format: uuid

                example: '550e8400-e29b-41d4-a716-446655440000'

              key_id_extension:

                description: 'Object for future use'

            $ref: '#/components/schemas/key_id'

          extension:

            $ref: '#/components/schemas/extension'

    key_ids:

      type: array

      description: 'Array of key IDs.'

      items:

        $ref: '#/components/schemas/key_id'

    void_container:

      title: 'Void request container'

      type: object

              key_value:

                description: 'Key data encoded in base64'

                type: string

              key_extension:

                description: 'Object for future use'

      properties:

        key_ids:

          $ref: '#/components/schemas/key_ids'

        additional_target_sae_ids:

          $ref: '#/components/schemas/additional_target_sae_ids'

        ack_callback_url:

          $ref: '#/components/schemas/ack_callback_url'

        extension:

          $ref: '#/components/schemas/extension'

    ack_container:

      title: 'Acknowledgements container'

      type: object

          example:

            - key_id: 'bc490419-7d60-487f-adc1-4ddcc177c139'

              key_value: 'wHHVxRwDJs3/bXd38GHP3oe4svTuRpZS0yCC7x4Ly+s='

            - key_id: '0a782fb5-3434-48fe-aa4d-14f41d46cf92'

              key_value: 'OeGMPxh1+2RpJpNCYixWHFLYRubpOKCw94FcCI7VdJA='

            - key_id: '64a7e9a2-269c-4b2c-832c-5351f3ac5adb'

              key_value: '479G1Osfljpmfa5vn24tdzE5zqv5CafkGxYrLCk8384='

            - key_id: '550e8400-e29b-41d4-a716-446655440000'

              key_value: 'csEMV9KkmjgOPF90uc54+hykhg6iI5GTPHlP9PjgLVU='

      required:

      - key_ids

      - ack_status

      - initiator_sae_id

      - target_sae_id

      properties:

        key_ids:

          $ref: '#/components/schemas/key_id_container'

        ack_status:

          $ref: '#/components/schemas/ack_status'

        initiator_sae_id:

          description: 'ID of the SAE that initiated the request to share the key(s) contained in the request'

          type: string

          example: 'App_Init'

        target_sae_ids:

          description: 'Array of IDs of target SAE(s) that the initiator SAE wishes to share keys with'

          $ref: '#/components/schemas/initiator_sae_id'

        target_sae_id:

          $ref: '#/components/schemas/target_sae_id'

        extension:

          $ref: '#/components/schemas/extension'

    ack_containers:

      description: 'Array of acknowledgement containers'

      type: array

      items:

        $ref: '#/components/schemas/ack_container'

    version:

      type: string

      description: 'Supported API version.'

      example:

            - 'App_Target_1'

            - 'App_Target_2'

        key_container_extension:

          description: 'Object for future use'

          type: object

          example:

            {"abc_additional_id": "be3aa2"}

        key_request_extension_mandatory:

          description: 'Array of extension parameters that the KME shall handle or return an error'

        - 'v1'

        - 'v2'

    versions:

      type: array

      description: 'Array of supported API versions.'

      items:

            description: 'Object for future use'

        $ref: '#/components/schemas/version'

    version_container:

      title: 'Version container'

      type: object

          example:

            - {"abc_max_protocol_epsilon": 1e-7}

            - {"abc_relay_encryption_otp": true}

        key_request_extension_optional:

          description: 'Array of extension parameters that the KME may ignore'

          type: array

          items:

            description: 'Object for future use'

            type: object

          example:

            - {"abc_max_age": 30000}

            - {"abc_prefer_protocol": "BB84"}

      required:

      - versions

      properties:

        versions:

            $ref: '#/components/schemas/versions'

        extension:

          $ref: '#/components/schemas/extension'

    message_data:

      title: 'Message Data format'

      title: 'Message data format'

      type: object

      required:

      - message

        message:

          description: 'Response message'

          type: string

          example:

            message: 'success'

          example: 'success'

        details:

          description: 'Array of objects containing details'

          type: array

          items:

            description: 'Object containing detail'

            type: object

            example:

              - {"response_time": 32}

              - {"availability": "good"}

    request_response:

      title: 'Request response'

      type: object

      required:

      - status

      properties:

        status:

          description: Status of request

          type: string

          enum: [success, partial_success]

          example: success

        ack_containers:

            $ref: '#/components/schemas/ack_containers'

  parameters:

    initiator_sae_id:

      name: initiator_sae_id

      in: path

      required: true

      schema:

        $ref: '#/components/schemas/initiator_sae_id'

    target_sae_id:

      name: target_sae_id

      in: path

      required: true

      schema:

        $ref: '#/components/schemas/target_sae_id'

    all_confirmation:

      name: all_confirmation

      in: query

      required: false

      description: Confirmation flag used to confirm deletion of all keys when no key IDs are specified.

      schema:

        type: boolean

      examples:

        true:

          value: true

          summary: "Confirmation"

  securitySchemes:

    mutualTLS:

      type: http

      scheme: mutual

      description: Mutual TLS authentication using certificates, TLSv1.3 (or later). NOTE - OpenAPI 3.1.0 introduces better support for describing mTLS.

security:

  - mutualTLS: []

 No newline at end of file