Commit 22e2c893 authored by Martin Ward's avatar Martin Ward
Browse files

Edit key-deliv_ExtraMarkup.yaml

parent f1bb651e
Loading
Loading
Loading
Loading
+89 −59
Changes for key-deliv_ExtraMarkup.yaml: 89 added lines, 59 removed lines.
Original line number Diff line number Diff line
@@ -3,6 +3,17 @@
openapi: '3.0.3'
info:
  title: Draft ETSI GS QKD 014 - Protocol and data format of REST-based key delivery for QKD
  
  contact:
    name: ETSI ISG QKD
    email: isgsupport@etsi.org
  version: Proposed changes to 1.3.1
  license:
    name: BSD 3-Clause
    url: https://opensource.org/licenses/BSD-3-Clause
  x-logo:
    url: 'https://www.etsi.org/templates/etsi/img/logo.svg'
    altText: ETSI logo
  description: |
    
    # Overview
@@ -67,16 +78,6 @@ info:
    match the SAE ID for which the API call refers to, the KME will 
    reject the API call.
    
  contact:
    name: ETSI ISG QKD
    email: isgsupport@etsi.org
  version: Draft 1.3.1
  license:
    name: BSD 3-Clause
    url: https://opensource.org/licenses/BSD-3-Clause
  x-logo:
    url: 'https://www.etsi.org/templates/etsi/img/logo.svg'
    altText: ETSI logo
servers:
- url: http://{kme_hostname}
  description: Local KME server
@@ -349,18 +350,21 @@ components:
  schemas:
    array_link_status:
      type: array
      description: Array of <code>link_status</code> link statuses
      description: Array of link statuses `link_status`<!-- ~ref_link_status -->.
      maxItems: 1024
      items:
        $ref: '#/components/schemas/link_status'

    delivered_key_count:
      type: integer
      description: Total number of keys delivered by KME to the calling initiator SAE
      description: Delivered key count `delivered_key_count`<!-- ~ref_delivered_key_count --> 
        indicates the total number of keys delivered by KME to the calling initiator SAE
      example: 10

    delivered_key_bits:
      type: integer
      description: Total number of bits delivered by KME to the calling initiator SAE
      description: Delivered key bits `delivered_key_bits`<!-- ~ref_delivered_key_bits --> 
        indicates the total number of bits delivered by KME to the calling initiator SAE
      example: 2560

    extension:
@@ -368,10 +372,10 @@ components:
      additionalProperties:
        type: object
        additionalProperties: true
      description: 'Reserved for future use. Dictionary of objects.'
      description: Extension `extension`<!-- ~ref_extension --> Reserved for future use. Dictionary of objects.
      example:
        abc_extension1: 'Some string'
        abc_extension2: 
        32473_extension1: 'Some string'
        32473_extension2: 
          property1: 10111
          property2: 'Some text'
          property3:
@@ -384,11 +388,12 @@ components:
        type: object
        additionalProperties: true
      description: >-
        Dictionary of objects representing extension parameters that KME shall 
        Mandatory extensions `extension_mandatory`<!-- ~ref_extension_mandatory --> 
        is a dictionary of objects representing extension parameters that KME shall 
        handle or return an error. Objects may be of any type.
      example:
        abc_route_type: 'direct'
        abc_method:
        32473_route_type: 'direct'
        32473_method:
          hybrid_keys: true
          primary: 'qkd'
          secondary: 'pqc'
@@ -399,18 +404,20 @@ components:
        type: object
        additionalProperties: true
      description: >-
        Dictionary of objects representing extension parameters that KME may 
        Optional extensions `extension_optional`<!-- ~ref_extension_optional --> is a 
        dictionary of objects representing extension parameters that the KME may 
        ignore. Objects may be of any type.
      example:
        abc_module_type:
        32473_module_type:
          vendor: 'Company ABC'
          protocol: 'BB84'
          min_version: 2.5
        abc_qos_session: 'e73d9abe'
        32473_qos_session: 'e73d9abe'

    fractional_byte_support:
      type: boolean
      description: >-
        Fractional byte support `fractional_byte_support`<!-- ~ref_fractional_byte_support -->.
        Non-integer-byte-size keys are supported for relevant keys when true. 
        When absent or false non-integer-byte-size keys are not supported.
      example: true
@@ -418,17 +425,20 @@ components:
    initiator_kme_id:
      type: string
      example: kme1
      description: KME ID of the KME
      description: Initiator KME ID `initiator_kme_id`<!-- ~ref_initiator_kme_id --> 
        is the ID of the initiating KME.

    initiator_sae_id:
      type: string
      description: ID of the SAE that initiated the request to share the key(s) relevant to the request.
      description: Initiator SAE ID `initiator_sae_id`<!-- ~ref_initiator_sae_id --> 
        is the ID the SAE that initiated the request to share the key(s) relevant to the request.
      example: encryptor1

    keys:
      type: array
      description: >-
        Array of keys with IDs and optionally extensions.
        Keys `keys`<!-- ~ref_keys --> is an array of `key`<!-- ~ref_key --> 
        (key values with key IDs) and optionally extensions.
      items:
        type: object
        required:
@@ -444,7 +454,8 @@ components:

    key_container:
      type: object
      description: Key container
      description: Key container `key_container`<!-- ~ref_key_container --> is an array of 
        `keys`<!-- ~ref_keys --> and optionally a srt of global extensions. 
      required:
      - keys
      properties:
@@ -454,7 +465,7 @@ components:
          $ref: '#/components/schemas/extension'

    key_id:
      description: 'ID of the key: UUID format.'
      description: Key ID `key_id`<!-- ~ref_key_id --> is the ID of the key in UUID format.
      type: string
      format: uuid
      example: '550e8400-e29b-41d4-a716-446655440000'
@@ -462,7 +473,8 @@ components:
    key_ids:
      type: array
      format: int16
      description: Array of key IDs.
      description: Key IDs `key_ids`<!-- ~ref_key_ids --> is an array of key IDs 
        `key_id`<!-- ~ref_key_id -->.
      items:
        $ref: '#/components/schemas/key_id'
      minItems: 1
@@ -471,7 +483,8 @@ components:

    key_id_container:
      type: object
      description: Key IDs container.
      description: Key IDs container `key_id_container`<!-- ~ref_key_id_container --> holds 
        a `key_ids`<!-- ~ref_key_ids --> array along with th associted initiator and target SAE IDs.
      required:
        - initiator_sae_id
        - target_sae_id
@@ -488,7 +501,7 @@ components:

    key_request:
      type: object
      description: Key request container.
      description: Key request container `key_request`<!-- ~ref_key_request -->.
      required:
        - initiator_sae_id
        - target_sae_ids
@@ -511,7 +524,9 @@ components:
      type: integer
      format: int32
      minimum: 1
      description: >-
      description: |
        Key size `key_size`<!-- ~ref_key_size -->.

        Where a KME wishes to indicate a preferred or recommended size of key for 
        SAEs to request it can return a `key_size`<!-- ~refp_link_status_key_size --> 
        in bits within the `link_status`<!-- ~ref_link_status --> 
@@ -524,11 +539,12 @@ components:
    kme_id:
      type: string
      example: kme1
      description: KME ID of the KME
      description: KME ID `kme_id`<!-- ~ref_kme_id -->.

    kme_status:
      type: object
      description: Status information about the KME.
      description: KME status `kme_status`<!-- ~ref_kme_status --> conntains 
        status information about a KME.
      required:
        - kme_id
        - uptime
@@ -542,7 +558,8 @@ components:

    link_status:
      type: object
      description: Status information about a link.
      description: Link status `link_status`<!-- ~ref_link_status --> 
        contains status information about a link.
      required:
        - initiator_kme_id
        - target_kme_id
@@ -591,7 +608,7 @@ components:

    link_status_request:
      type: object
      description: Link status request.
      description: Link status request `link_status_request`<!-- ~ref_link_status_request -->.
      required:
        - initiator_sae_id
        - target_sae_id
@@ -605,29 +622,32 @@ components:

    max_key_count:
      type: integer
      description: Maximum number of stored_key_count
      description: Maximum key count `max_key_count`<!-- ~ref_max_key_count --> 
        is the maximum number of `stored_key_count`<!-- ~ref_stored_key_count -->.
      example: 100000

    max_key_per_request:
      type: integer
      description: Maximum number of keys per request
      description: Maximum number of keys per request `max_key_per_request`<!-- ~ref_max_key_per_request -->.
      example: 128

    max_key_size:
      type: integer
      description: Maximum size of key the KME can deliver to the SAE (in bits) 
        `max_key_size`<!-- ~ref_max_key_size -->.
      example: 1024

    max_sae_id_count:
      type: integer
      description: >-
        Maximum number of additional target_sae_ids the KME allows. 
        `0` when the KME does not support key multicast.
        Maximum number of additional target_sae_ids 
        `max_sae_id_count`<!-- ~ref_max_sae_id_count -->
        that the KME supports. `0` when the KME does not support key multicast.
      example: 0

    message_data:
      type: object
      description: Message data format.
      description: Message data format `message_data`<!-- ~ref_message_data -->.
      required:
      - message
      properties:
@@ -644,10 +664,11 @@ components:
    min_key_size:
      type: integer
      description: Minimum size of key the KME can deliver to the SAE (in bits)
        `min_key_size`<!-- ~ref_min_key_size -->.
      example: 64

    number:
      description: 'Number of keys requested (default value is 1).'
      description: Number `number`<!-- ~ref_number --> of keys requested.
      type: integer
      default: 1
      example: 20
@@ -655,8 +676,8 @@ components:
    size:
      type: integer
      description: >-
        Size of key(s) requested in bits. If the requested size not supported the 
        request will be rejected. A client can call the  
        Size `size`<!-- ~ref_size --> of key(s) requested in bits. If the requested 
        size is not supported the request will be rejected. A client can call the  
        `/kdapi/v2/status/link`<!-- ~op_post_kdapi_v2_status_link --> and consider 
        `fractional_byte_support`<!-- ~refp_link_status_fractional_byte_support -->, 
        `min_key_size`<!-- ~refp_link_status_min_key_size --> and 
@@ -666,23 +687,26 @@ components:

    stored_key_count:
      type: integer
      description: Number of stored keys KME can deliver to the SAE.
      description: Number of stored keys `stored_key_count`<!-- ~ref_stored_key_count --> 
        KME can deliver to the SAE.
      example: 25000

    target_kme_id:
      type: string
      description: KME ID of the target KME.
      description: Target KME ID `target_kme_id`<!-- ~ref_target_kme_id -->.
      example: kme2

    target_sae_id:
      type: string
      description: ID of the target SAE that the initiator SAE wishes to share keys with.
      description: Target SAE ID `target_sae_id`<!-- ~ref_target_sae_id --> 
        of the target SAE that the initiator SAE wishes to share keys with.
      example: encryptor2

    target_sae_ids:
      type: array
      description: >-
        Array of IDs of target SAEs that the initiator SAE wishes to share keys with. 
        Target SAE IDs `target_sae_ids`<!-- ~ref_target_sae_ids --> ia an array 
        of IDs of target SAEs that the initiator SAE wishes to share keys with. 
        A single target or multiple targets can be specified. Specified target SAEs 
        will each be allowed to retrieve an identical key, as returned to the 
        initiator SAE. The maximum number of IDs is specified as 
@@ -702,22 +726,24 @@ components:
      minimum: 1
      format: int32
      description: >-
        How many seconds to expect relevant keys to be available for requests 
        using `/kdapi/v2/keys_with_id`<!-- ~op_post_kdapi_v2_keys_with_id --> from the queried 
        KME after being requested on a remote KME using the 
        Time to fetch `time_to_fetch`<!-- ~ref_time_to_fetch --> indicates how 
        many seconds to expect relevant keys to be available for requests 
        using `/kdapi/v2/keys_with_id`<!-- ~op_post_kdapi_v2_keys_with_id --> 
        from the queried KME after being requested on a remote KME using the 
        `/kdapi/v2/keys`<!-- ~op_post_kdapi_v2_keys --> method.
      example: 90
      
    uptime:
      type: string
      description: Uptime of KME (ISO8601 time duration format)
      description: Uptime of KME `uptime`<!-- ~ref_uptime --> (ISO8601 time duration format).
      example: 'P1Y2M10DT2H30M59S'

    value:
      description: |
        Key data encoded by the base64 data encoding scheme specified in IETF 
        RFC 4648 (October 2006): "The Base16, Base32, and Base64 Data Encodings" 
        [7] using the alphabet in Table 1 of the RFC.
        Value `value`<!-- ~ref_value --> is key data encoded by the base64 data 
        encoding scheme specified in 
        IETF RFC 4648 (October 2006): "The Base16, Base32, and Base64 Data Encodings" 
        using the alphabet in Table 1 of the RFC.

        Implementations shall ensure that padding used in the base64 data 
        encoding scheme is never used as key material. This includes the 
@@ -739,10 +765,11 @@ components:
        with value zero that were added when during encoding in the case 
        of non-integer-byte-size keys.)
        
        Note that support for non-integer-byte-size keys is optional and 
        NOTE: Support for non-integer-byte-size keys is optional and 
        many vendors choose to support only integer byte sizes.

        The key size is always specified by the "size" parameter to "Get key"
        The key size is always specified by the `size`<!-- ~ref_size --> parameter 
        to the "Get key" `/kdapi/v2/keys`<!-- ~op_post_kdapi_v2_keys --> endpoint
        and an application needs to ensure that all SAEs know the requested 
        key size when non-integer-byte-size keys are used.

@@ -751,12 +778,14 @@ components:
           
    version:
      type: string
      description: 'Supported API version.'
      description: Version `version`<!-- ~ref_version --> is a sting indicating 
        a version of this API.
      example: 'v1'

    versions:
      type: array
      description: Array of supported API versions.
      description: Versions `versions`<!-- ~ref_versions --> is an array of supported 
        API versions `version`<!-- ~ref_version -->.
      items:
        $ref: '#/components/schemas/version'
      example: ['v1', 'v2']
@@ -764,7 +793,8 @@ components:
    versions_container: 
      type: object
      description: |
        Container for an array of strings representing the  versions of the 
        Versions container `versions_container`<!-- ~ref_versions_container --> 
        for an array of strings representing the `versions`<!-- ~ref_versions --> of the 
        API supported by the KME with optional extensions.
      required:
      - versions