Add interop-kms.yaml

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. 

  contact:

    name: ETSI ISG QKD

    email: 'isgsupport@etsi.org'

  version: '0.0.1'

servers:

- url: https://{KME_hostname}/

  description: Local KMS server

  variables:

    KME_hostname:

      default: '127.0.0.1:443'

externalDocs:

  description: 'Work Item description.'

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

tags:

- name: 'Extended Specification'

paths:

  /api/v1/keys/ext_keys:

    post:

      summary: 'Relay key'

      tags:

      - 'Extended Specification'

      description: 'Returns Key container data from the KME to the initiator SAE. Key container data contains one or more keys. The initiator SAE may supply Key request data to specify requirements on Key container data. The target SAE specified by the target_SAE_ID parameter may subsequently request matching keys from a remote KME using key_id identifiers from the returned Key container.'

      requestBody:

        description: 'Extended key container.'

        required: true

        content:

          application/json:

            schema:

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

      responses:

        200:

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

        400:

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

components:

  responses:

    200-extkey:

      description: Successful 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:

            message: 'key routing error'

            details:

            - 'target_SAE_ID not recognized': 'KME associated with this target SAE ID is not known.'

  schemas:

    ext_key_container:

      title: 'Extended Key Container data format'

      type: object

      required:

      - keys

      - initiator_sae_id

      - target_sae_id

      properties:

        Keys:

          description: 'Array of keys. The number of keys is specified by the "number" parameter in "Get key". If not specified, the default number of keys is 1.'

          type: array

          items:

            type: object

            required:

            - key_id

            - key

            properties:

              key_id:

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

                type: string

                format: uuid

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

              key_id_extension:

                description: '(Option) for future use'

                type: object

              key:

                description: 'Key data encoded by base64 [7]. The key size is specified by the "size" parameter in "Get key". If not specified, the "key_size" value in Status data model is used as the default size.'

                type: string

              key_extension:

                description: '(Option) for future use.'

                type: object

          example:

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

              key: 'wHHVxRwDJs3/bXd38GHP3oe4svTuRpZS0yCC7x4Ly+s='

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

              key: 'OeGMPxh1+2RpJpNCYixWHFLYRubpOKCw94FcCI7VdJA='

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

              key: '479G1Osfljpmfa5vn24tdzE5zqv5CafkGxYrLCk8384='

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

              key: 'csEMV9KkmjgOPF90uc54+hykhg6iI5GTPHlP9PjgLVU='

        initiator_sae_id:

          description: 'ID of initiator SAE who instigated the request to share the keys that are carried in this container. (Editorial note: It is proposed to introduce a similar parameter to GS QKD 014 this parameter is optional when the  container is returned in response to ENC/DEC_KEYS API, but non-optional when container used for EXT_KEYS API relaying keys between SAEs)'

          type: string

        target_sae_id:

          description: 'ID of target SAE that the initiator SAE wishes to share keys with (i.e., the SAE the keys are being relayed to).'

          type: string

        key_container_extension:

          description: '(Option) for future use.'

          type: object

    message_data:

      title: 'Message Data format'

      type: object

      required:

      - message

      properties:

        message:

          description: 'Response message'

          type: string

        details:

          type: array

          items:

            type: object

      example:

        message: 'success'