Commit 014b4ca4 authored by Martin Ward's avatar Martin Ward
Browse files

Changes for draft V1.3.1

parent 52e1690b
Loading
Loading
Loading
Loading
+2 −2
Changes for key-deliv.yaml: 2 added lines, 2 removed lines.
Original line number Diff line number Diff line
# Copyright 2024 ETSI
# Copyright 2025 ETSI
# Licensed under the BSD-3 Clause (https://forge.etsi.org/legal-matters)
openapi: '3.0.3'
info:
@@ -70,7 +70,7 @@ info:
  contact:
    name: ETSI ISG QKD
    email: isgsupport@etsi.org
  version: Proposed changes to 1.2.2
  version: Proposed changes to 1.3.1
  license:
    name: BSD 3-Clause
    url: https://opensource.org/licenses/BSD-3-Clause
+41 −41
Changes for key-deliv_ExtraMarkup.yaml: 41 added lines, 41 removed lines.
Original line number Diff line number Diff line
# Copyright 2024 ETSI
# Copyright 2025 ETSI
# Licensed under the BSD-3 Clause (https://forge.etsi.org/legal-matters)
openapi: '3.0.3'
info:
@@ -70,7 +70,7 @@ info:
  contact:
    name: ETSI ISG QKD
    email: isgsupport@etsi.org
  version: Proposed changes to 1.2.2
  version: Proposed changes to 1.3.1
  license:
    name: BSD 3-Clause
    url: https://opensource.org/licenses/BSD-3-Clause
@@ -138,26 +138,26 @@ paths:
      tags:
      - keys
      description: |
        The KME returns a `key_container`<!-- #ref_key_container --> object 
        The KME returns a `key_container`<!-- ~ref_key_container --> object 
        to the calling initiator SAE based on a request for a specified 
        number of keys.
        
        `key_container`<!-- #ref_key_container --> contains one or more keys. 
        `key_container`<!-- ~ref_key_container --> contains one or more keys. 
        The calling initiator SAE supplies a 
        `key_request`<!-- #ref_key_request --> object in the request body 
        `key_request`<!-- ~ref_key_request --> object in the request body 
        to specify the size and number of keys it desires and in 
        `target_sae_ids`<!-- #post_kdapi_v2_keys_target_sae_ids --> the 
        `target_sae_ids`<!-- ~post_kdapi_v2_keys_target_sae_ids --> the 
        target SAE IDs the keys may be retrieved from. KMEs in the network 
        shall ensure that keys are not shared with SAE that are not included 
        in `target_sae_ids`<!-- #post_kdapi_v2_keys_target_sae_ids -->. 
        in `target_sae_ids`<!-- ~post_kdapi_v2_keys_target_sae_ids -->. 
        
        The initiator SAE can use the 
        `extension_mandatory`<!-- #post_kdapi_v2_keys_extension_mandatory -->
        `extension_mandatory`<!-- ~post_kdapi_v2_keys_extension_mandatory -->
        and indicate additional requirements for keys delivered and KMEs shall 
        not return keys that do not satisfy these requirements.
        
        The initiator SAE can use the 
        `extension_optional`<!-- #post_kdapi_v2_keys_extension_optional -->
        `extension_optional`<!-- ~post_kdapi_v2_keys_extension_optional -->
        to indicate other preferences within requiring the KME to reject the
        request if these preferences cannot be satisfied.

@@ -189,29 +189,29 @@ paths:
      tags:
      - keys
      description: |
        The KME returns a `key_container`<!-- #ref_key_container --> object 
        The KME returns a `key_container`<!-- ~ref_key_container --> object 
        to the calling target SAE based on a set of requested 
        `key_ids`<!-- #post_kdapi_v2_keys_with_id_key_ids -->.
        `key_ids`<!-- ~post_kdapi_v2_keys_with_id_key_ids -->.

        The `key_container`<!-- #ref_key_container --> contains keys that shall 
        The `key_container`<!-- ~ref_key_container --> contains keys that shall 
        match keys delivered to the initiator SAE in one or more calls it 
        previously made to the `/kdapi/v2/keys`<!-- #op_post_kdapi_v2_keys --> 
        previously made to the `/kdapi/v2/keys`<!-- ~op_post_kdapi_v2_keys --> 
        endpoint of its KME.
        
        The KME shall reject the request with a 
        `401`<!-- #op_po_kdapi_v2_keys_with_id_c_401 --> HTTP status code 
        `401`<!-- ~op_po_kdapi_v2_keys_with_id_c_401 --> HTTP status code 
        if the SAE ID of the requestor was not a SAE ID supplied in the 
        `target_sae_ids`<!-- #post_kdapi_v2_keys_target_sae_ids -->
        parameter of the call to the `/kdapi/v2/keys`<!-- #op_post_kdapi_v2_keys --> 
        `target_sae_ids`<!-- ~post_kdapi_v2_keys_target_sae_ids -->
        parameter of the call to the `/kdapi/v2/keys`<!-- ~op_post_kdapi_v2_keys --> 
        when the corresponding key was returned to the corresponding initiator SAE.
        This response shall be issued if any key indicated in 
        `key_ids`<!-- #post_kdapi_v2_keys_with_id_key_ids --> does not satisfy 
        `key_ids`<!-- ~post_kdapi_v2_keys_with_id_key_ids --> does not satisfy 
        this condition.

        Separate from this API the target SAE needs access to 
        `key_ids`<!-- #post_kdapi_v2_keys_with_id_key_ids --> that were previously 
        `key_ids`<!-- ~post_kdapi_v2_keys_with_id_key_ids --> that were previously 
        returned to an initiator SAE in response to a call to 
        the `/kdapi/v2/keys`<!-- #op_post_kdapi_v2_keys --> endpoint of its KME.
        the `/kdapi/v2/keys`<!-- ~op_post_kdapi_v2_keys --> endpoint of its KME.

        NOTE: v1 of this API supported an initiator SAE performing a `GET` 
        operation to retrieve a single key by supplying a single key ID and no 
@@ -238,10 +238,10 @@ paths:
      tags:
      - status
      description: |
        The KME returns a `kme_status`<!-- #ref_key_container --> object to 
        The KME returns a `kme_status`<!-- ~ref_key_container --> object to 
        indicate the general status of the KME. For detailed status 
        information about a particular link between two SAEs please see the 
        `/kdapi/v2/status/link`<!-- #op_post_kdapi_v2_status_link --> 
        `/kdapi/v2/status/link`<!-- ~op_post_kdapi_v2_status_link --> 
        endpoint.
      responses:
        '200':
@@ -265,23 +265,23 @@ paths:
          Returns status for one or more links between given initiator and 
          target SAEs.

          If both `initiator_sae_id`<!-- #post_kdapi_v2_status_link_initiator_sae_id --> 
          and `target_sae_id`<!-- #post_kdapi_v2_status_link_target_sae_id --> 
          If both `initiator_sae_id`<!-- ~post_kdapi_v2_status_link_initiator_sae_id --> 
          and `target_sae_id`<!-- ~post_kdapi_v2_status_link_target_sae_id --> 
          are specified in the request body, a single status container is returned containing 
          information on keys available to be requested by the initiator SAE 
          for the specified target SAE.

          If only `initiator_sae_id`<!-- #post_kdapi_v2_status_link_initiator_sae_id --> 
          If only `initiator_sae_id`<!-- ~post_kdapi_v2_status_link_initiator_sae_id --> 
          is specified in the request body, a status container will be returned for each 
          active link where the calling SAE is the specified initiator SAE.

          If only `target_sae_id`<!-- #post_kdapi_v2_status_link_target_sae_id --> 
          If only `target_sae_id`<!-- ~post_kdapi_v2_status_link_target_sae_id --> 
          is specified in the request body, a status container will be returned for each 
          active link where the target SAE is the specified target SAE.

          If neither `initiator_sae_id`<!-- #post_kdapi_v2_status_link_initiator_sae_id --> 
          nor `target_sae_id`<!-- #post_kdapi_v2_status_link_target_sae_id --> is specified, 
          a `400`<!-- #op_po_kdapi_v2_status_link_c_400 --> HTTP status code is returned.
          If neither `initiator_sae_id`<!-- ~post_kdapi_v2_status_link_initiator_sae_id --> 
          nor `target_sae_id`<!-- ~post_kdapi_v2_status_link_target_sae_id --> is specified, 
          a `400`<!-- ~op_po_kdapi_v2_status_link_c_400 --> HTTP status code is returned.
      requestBody:
        description: Link status request.
        content:
@@ -513,12 +513,12 @@ components:
      minimum: 1
      description: >-
        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 --> 
        SAEs to request it can return a `key_size`<!-- ~refp_link_status_key_size --> 
        in bits within the `link_status`<!-- ~ref_link_status --> 
        data format. Note that support for non-integer-byte-sizes is optional 
        (such support is available when 
        `fractional_byte_support`<!-- #refp_link_status_fractional_byte_support --> 
        is set in the `link_status`<!-- #ref_link_status --> objct with a value of `true`).
        `fractional_byte_support`<!-- ~refp_link_status_fractional_byte_support --> 
        is set in the `link_status`<!-- ~ref_link_status --> objct with a value of `true`).
      example: 256

    kme_id:
@@ -657,10 +657,10 @@ components:
      description: >-
        Size of key(s) requested in bits. If the requested size 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 
        `max_key_size`<!-- #refp_link_status_max_key_size --> in order to make 
        `/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 
        `max_key_size`<!-- ~refp_link_status_max_key_size --> in order to make 
        valid requests.
      example: 256

@@ -686,11 +686,11 @@ components:
        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 
        `max_sae_id_count`<!-- #refp_link_status_max_sae_id_count -->
        in the `link_status`<!-- #ref_link_status --> data format.
        `max_sae_id_count`<!-- ~refp_link_status_max_sae_id_count -->
        in the `link_status`<!-- ~ref_link_status --> data format.
        
        Support for more than one 
        `target_sae_ids`<!-- #refp_key_request_target_sae_ids --> (multicast) 
        `target_sae_ids`<!-- ~refp_key_request_target_sae_ids --> (multicast) 
        is optional and not widely implemented at the time of writing.
      items:
        $ref: '#/components/schemas/target_sae_id'
@@ -703,9 +703,9 @@ components:
      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 
        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.
        `/kdapi/v2/keys`<!-- ~op_post_kdapi_v2_keys --> method.
      example: 90
      
    uptime: