Loading interop-kms.yaml +47 −33 Original line number Diff line number Diff line # Copyright 2025 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 Loading @@ -10,7 +12,7 @@ info: contact: name: ETSI ISG QKD email: isgsupport@etsi.org version: Proposed changes to 0.4.1 version: Draft 0.5.1 license: name: BSD 3-Clause url: https://forge.etsi.org/legal-matters Loading Loading @@ -50,7 +52,7 @@ paths: supports. responses: '200': description: Supported versions description: Successful response content: application/json: schema: Loading @@ -67,13 +69,14 @@ paths: tags: - ext-keys description: | Pass an extended key request container comprising key material and Pass an `ext_key_container` 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. Upon a valid request, the KME should aim to resond without undue delay with Upon a valid request, the KME should aim to respond without undue delay with a `202` ('Accepted'), then it will issue a separate call (or multiple calls) to the specified `ack_callback_url` Loading @@ -83,7 +86,8 @@ paths: if the container format is invalid or includes initiator/target SAE IDs for which a valid route is not known to the KME. requestBody: description: Extended key request container. description: | `ext_key_container` extended key request container. required: true content: application/json: Loading @@ -108,15 +112,17 @@ paths: tags: - ext-keys description: | Pass an extended key request container comprising key IDs to another Pass an `ext_key_container` 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 delivered to SAEs). The `ext_key_container` extended key request container contains keys matching those already passed to the KME. Upon a valid request, a KME shall discard keys relating to the provided key IDs and post a call to the specified `ack_callback_url` describing the completed operation. After this, The KMEs shall not use the ipacted the completed operation. After this, The KMEs shall not use the impacted key, and it shall reject any requests to retrieve them using ETSI GS QKD 014, ETSI GS QKD 004, or otherwise. Loading @@ -127,10 +133,11 @@ paths: If this operation is requested with an empty `key_ids` array all keys shared between the prspecified SAEs shall be voided. To reduce the risk of accidental key loss, unles the to confirm this action an `all_confirmation` boolean field needs to be passed with a value of `true`, otherwise a Code 400 error is returned). all keys shared between the pre-specified SAEs shall be voided. To reduce the risk of accidental key loss, the KME shall reject any void request that does specify key ID(s) but without including the `all_confirmation` URL parameter with a value of true, and return a `400` code. parameters: - $ref: '#/components/parameters/all_confirmation' requestBody: Loading Loading @@ -160,16 +167,17 @@ paths: - ext-keys description: | Pass one or more key acknowledgement container comprising key IDs associated with a previous call to the ext_keys method by an external associated with a previous call to the `ext_keys` method by an external KMS. The status of all keys in the container is indicated by the status field. The `ack_status` field may be `relayed` `voided` `failed` or `key not The `ack_status` field may be `relayed`, `voided`, `failed`, or `key not present`. - `relayed` indicates the KME has successfully relayed the specified keys to the requested target (where the initiator_sae_id and target_sae_id are specified in the acknowledgement container). If the keys to the requested target (where the `initiator_sae_id` and `target_sae_id` are specified in the acknowledgement container). If the initiator requested multiple targets, the acknowledgements for each target are separate acknowledgement containers (since the status for each target may be different). Loading @@ -178,7 +186,8 @@ paths: so they will not be delivered to applications. - `failed` indicates that the requested operation on the specified keys could not be completed. For example, an ext_keys request may not could not be completed. For example, an `ext_keys` request may not complete if there is insufficient key material for relaying. Also, a void request will fail if the specified keys have already been delivered to a requesting SAE. Loading @@ -189,7 +198,8 @@ paths: In addition to the `status` field, additional information (e.g. explaining a failure) can be included in the optional `message` field. It is possible that a single ext_keys request included multiple keys, It is possible that a single `ext_keys` request included multiple keys, where some are successfully delivered and other fail. This can be indicated by a KME sending multiple acknowledgement requests, with the container payload used to specify the status of different arrays of Loading @@ -201,9 +211,9 @@ paths: handled accordingly (e.g. to keep the provided metadata with each key so it can be relayed to the initiator SAE). A Code 200 Success will returned by a KME receiving a valid acknowledgement, otherwise an Error Code will be returned including details of the error. a KME receiving a valid acknowledgement shall return a `200` code, otherwise an Error Code shall be returned including details of the error. requestBody: description: Acknowledgements containers required: true Loading Loading @@ -330,7 +340,8 @@ components: message: timeout details: - timeout: >- No response received from KME to ext_keys request in No response received from KME to `ext_keys` request in sufficient time. 503-extkey: Loading Loading @@ -376,14 +387,16 @@ components: $ref: '#/components/schemas/extension' ack_containers: description: Array of acknowledgement containers description: Array of `ack_container` acknowledgement containers type: array items: $ref: '#/components/schemas/ack_container' ack_message: title: message description: Optional further details to expand upon the `ack_status`. description: | Optional further details to expand upon the `ack_status`. type: string ack_status: Loading Loading @@ -443,10 +456,10 @@ components: additionalProperties: true description: >- Dictionary of objects representing extension parameters 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). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. or return an error (e.g. as originated in the Get Key request that triggered key relaying to use the `ext_keys` call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. example: abc_route_type: 'direct' abc_method: Loading @@ -462,8 +475,9 @@ components: description: >- Dictionary of objects representing extension parameters that KME may ignore (e.g. as originated in the Get Key request that triggered key relaying to use the ext_keys call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. `ext_keys` call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. example: abc_module_type: vendor: 'Company ABC' Loading Loading @@ -544,10 +558,10 @@ components: type: array description: >- Array of IDs of target SAEs relevant to the request. (In a call to ext_keys to request keys to be shared these are the keys the initiator `ext_keys` to request keys to be shared these are the keys the initiator SAE wishes to share keys with.) A single target or multiple targets can be specified (where each target gets an identical key). The maximum number of IDs is defined as `max_sae_id_count` in Status data format. be specified (where each target gets an identical key). items: $ref: '#/components/schemas/target_sae_id' Loading interop-kms_ExtraMarkup.yaml +54 −41 Original line number Diff line number Diff line openapi: 3.0.3 # Copyright 2025 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: | Loading @@ -10,7 +11,7 @@ info: contact: name: ETSI ISG QKD email: isgsupport@etsi.org version: Proposed changes to 0.4.1 version: Draft 0.5.1 license: name: BSD 3-Clause url: https://forge.etsi.org/legal-matters Loading Loading @@ -50,7 +51,7 @@ paths: supports. responses: '200': description: Supported versions description: Successful response content: application/json: schema: Loading @@ -67,23 +68,25 @@ paths: tags: - ext-keys description: | Pass an extended key request container comprising key material and Pass an `ext_key_container`<!-- ~ref_ext_key_container --> 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. Upon a valid request, the KME should aim to resond without undue delay with a `202`<!-- #op_po_kmapi_v1_ext_keys_c_202 --> ('Accepted'), Upon a valid request, the KME should aim to respond without undue delay with a `202`<!-- ~op_po_kmapi_v1_ext_keys_c_202 --> ('Accepted'), then it will issue a separate call (or multiple calls) to the specified `ack_callback_url`<!-- #op_post_kmapi_v1_ext_keys_ack --> `ack_callback_url`<!-- ~p_kmapi_v1_ext_keys_ack_cb_url --> endpoint once the keys are actually delivered (or fail to be delivered). A `400`<!-- #op_po_kmapi_v1_ext_keys_c_400 --> error will be returned A `400`<!-- ~op_po_kmapi_v1_ext_keys_c_400 --> error will be returned if the container format is invalid or includes initiator/target SAE IDs for which a valid route is not known to the KME. requestBody: description: Extended key request container. description: | `ext_key_container`<!-- ~ref_ext_key_container --> extended key request container. required: true content: application/json: Loading @@ -108,29 +111,32 @@ paths: tags: - ext-keys description: | Pass an extended key request container comprising key IDs to another Pass an `ext_key_container`<!-- ~ref_ext_key_container --> 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 delivered to SAEs). The `ext_key_container`<!-- ~ref_ext_key_container --> extended key request container contains keys matching those already passed to the KME. Upon a valid request, a KME shall discard keys relating to the provided key IDs and post a call to the specified `ack_callback_url`<!-- #op_post_kmapi_v1_ext_keys_ack --> describing the completed operation. After this, The KMEs shall not use the ipacted `ack_callback_url`<!-- ~p_kmapi_v1_ext_keys_ack_cb_url --> describing the completed operation. After this, The KMEs shall not use the impacted key, and it shall reject any requests to retrieve them using ETSI GS QKD 014, ETSI GS QKD 004, or otherwise. A `400`<!-- #op_po_kmapi_v1_ext_keys_c_400 --> code should be returned A `400`<!-- ~op_po_kmapi_v1_ext_keys_c_400 --> code should be returned if the request is known without further investigation to be invalid. Otherwise, failures to void keys can be reported subsequently via `ack_callback_url`<!-- #op_post_kmapi_v1_ext_keys_ack --> `ack_callback_url`<!-- ~p_kmapi_v1_ext_keys_ack_cb_url --> If this operation is requested with an empty `key_ids`<!-- #post_kmapi_v1_ext_keys_void_key_ids --> array all keys shared between the prspecified SAEs shall be voided. To reduce the risk of accidental key loss, unles the to confirm this action an `all_confirmation` boolean field needs to be passed with a value of `true`, otherwise a Code 400 error is returned). `key_ids`<!-- ~p_kmapi_v1_ext_keys_void_key_ids --> array all keys shared between the pre-specified SAEs shall be voided. To reduce the risk of accidental key loss, the KME shall reject any void request that does specify key ID(s) but without including the `all_confirmation` URL parameter with a value of true, and return a `400`<!-- ~op_po_kmapi_v1_ext_keys_c_400 --> code. parameters: - $ref: '#/components/parameters/all_confirmation' requestBody: Loading Loading @@ -160,16 +166,17 @@ paths: - ext-keys description: | Pass one or more key acknowledgement container comprising key IDs associated with a previous call to the ext_keys method by an external associated with a previous call to the `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> method by an external KMS. The status of all keys in the container is indicated by the status field. The `ack_status` field may be `relayed` `voided` `failed` or `key not The `ack_status` field may be `relayed`, `voided`, `failed`, or `key not present`. - `relayed` indicates the KME has successfully relayed the specified keys to the requested target (where the initiator_sae_id and target_sae_id are specified in the acknowledgement container). If the keys to the requested target (where the `initiator_sae_id` and `target_sae_id` are specified in the acknowledgement container). If the initiator requested multiple targets, the acknowledgements for each target are separate acknowledgement containers (since the status for each target may be different). Loading @@ -178,7 +185,8 @@ paths: so they will not be delivered to applications. - `failed` indicates that the requested operation on the specified keys could not be completed. For example, an ext_keys request may not could not be completed. For example, an `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request may not complete if there is insufficient key material for relaying. Also, a void request will fail if the specified keys have already been delivered to a requesting SAE. Loading @@ -189,7 +197,8 @@ paths: In addition to the `status` field, additional information (e.g. explaining a failure) can be included in the optional `message` field. It is possible that a single ext_keys request included multiple keys, It is possible that a single `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request included multiple keys, where some are successfully delivered and other fail. This can be indicated by a KME sending multiple acknowledgement requests, with the container payload used to specify the status of different arrays of Loading @@ -201,9 +210,9 @@ paths: handled accordingly (e.g. to keep the provided metadata with each key so it can be relayed to the initiator SAE). A Code 200 Success will returned by a KME receiving a valid acknowledgement, otherwise an Error Code will be returned including details of the error. a KME receiving a valid acknowledgement shall return a `200`<!-- ~op_po_kmapi_v1_ack_c_200 --> code, otherwise an Error Code shall be returned including details of the error. requestBody: description: Acknowledgements containers required: true Loading Loading @@ -330,7 +339,8 @@ components: message: timeout details: - timeout: >- No response received from KME to ext_keys request in No response received from KME to `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request in sufficient time. 503-extkey: Loading Loading @@ -376,14 +386,16 @@ components: $ref: '#/components/schemas/extension' ack_containers: description: Array of acknowledgement containers description: Array of `ack_container` acknowledgement containers type: array items: $ref: '#/components/schemas/ack_container' ack_message: title: message description: Optional further details to expand upon the `ack_status`. description: | Optional further details to expand upon the `ack_status`<!-- ~ref_ack_status -->. type: string ack_status: Loading Loading @@ -443,10 +455,10 @@ components: additionalProperties: true description: >- Dictionary of objects representing extension parameters 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). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. or return an error (e.g. as originated in the Get Key request that triggered key relaying to use the `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. example: abc_route_type: 'direct' abc_method: Loading @@ -462,8 +474,9 @@ components: description: >- Dictionary of objects representing extension parameters that KME may ignore (e.g. as originated in the Get Key request that triggered key relaying to use the ext_keys call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. example: abc_module_type: vendor: 'Company ABC' Loading Loading @@ -544,10 +557,10 @@ components: type: array description: >- Array of IDs of target SAEs relevant to the request. (In a call to ext_keys to request keys to be shared these are the keys the initiator `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> to request keys to be shared these are the keys the initiator SAE wishes to share keys with.) A single target or multiple targets can be specified (where each target gets an identical key). The maximum number of IDs is defined as `max_sae_id_count` in Status data format. be specified (where each target gets an identical key). items: $ref: '#/components/schemas/target_sae_id' Loading Loading
interop-kms.yaml +47 −33 Original line number Diff line number Diff line # Copyright 2025 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 Loading @@ -10,7 +12,7 @@ info: contact: name: ETSI ISG QKD email: isgsupport@etsi.org version: Proposed changes to 0.4.1 version: Draft 0.5.1 license: name: BSD 3-Clause url: https://forge.etsi.org/legal-matters Loading Loading @@ -50,7 +52,7 @@ paths: supports. responses: '200': description: Supported versions description: Successful response content: application/json: schema: Loading @@ -67,13 +69,14 @@ paths: tags: - ext-keys description: | Pass an extended key request container comprising key material and Pass an `ext_key_container` 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. Upon a valid request, the KME should aim to resond without undue delay with Upon a valid request, the KME should aim to respond without undue delay with a `202` ('Accepted'), then it will issue a separate call (or multiple calls) to the specified `ack_callback_url` Loading @@ -83,7 +86,8 @@ paths: if the container format is invalid or includes initiator/target SAE IDs for which a valid route is not known to the KME. requestBody: description: Extended key request container. description: | `ext_key_container` extended key request container. required: true content: application/json: Loading @@ -108,15 +112,17 @@ paths: tags: - ext-keys description: | Pass an extended key request container comprising key IDs to another Pass an `ext_key_container` 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 delivered to SAEs). The `ext_key_container` extended key request container contains keys matching those already passed to the KME. Upon a valid request, a KME shall discard keys relating to the provided key IDs and post a call to the specified `ack_callback_url` describing the completed operation. After this, The KMEs shall not use the ipacted the completed operation. After this, The KMEs shall not use the impacted key, and it shall reject any requests to retrieve them using ETSI GS QKD 014, ETSI GS QKD 004, or otherwise. Loading @@ -127,10 +133,11 @@ paths: If this operation is requested with an empty `key_ids` array all keys shared between the prspecified SAEs shall be voided. To reduce the risk of accidental key loss, unles the to confirm this action an `all_confirmation` boolean field needs to be passed with a value of `true`, otherwise a Code 400 error is returned). all keys shared between the pre-specified SAEs shall be voided. To reduce the risk of accidental key loss, the KME shall reject any void request that does specify key ID(s) but without including the `all_confirmation` URL parameter with a value of true, and return a `400` code. parameters: - $ref: '#/components/parameters/all_confirmation' requestBody: Loading Loading @@ -160,16 +167,17 @@ paths: - ext-keys description: | Pass one or more key acknowledgement container comprising key IDs associated with a previous call to the ext_keys method by an external associated with a previous call to the `ext_keys` method by an external KMS. The status of all keys in the container is indicated by the status field. The `ack_status` field may be `relayed` `voided` `failed` or `key not The `ack_status` field may be `relayed`, `voided`, `failed`, or `key not present`. - `relayed` indicates the KME has successfully relayed the specified keys to the requested target (where the initiator_sae_id and target_sae_id are specified in the acknowledgement container). If the keys to the requested target (where the `initiator_sae_id` and `target_sae_id` are specified in the acknowledgement container). If the initiator requested multiple targets, the acknowledgements for each target are separate acknowledgement containers (since the status for each target may be different). Loading @@ -178,7 +186,8 @@ paths: so they will not be delivered to applications. - `failed` indicates that the requested operation on the specified keys could not be completed. For example, an ext_keys request may not could not be completed. For example, an `ext_keys` request may not complete if there is insufficient key material for relaying. Also, a void request will fail if the specified keys have already been delivered to a requesting SAE. Loading @@ -189,7 +198,8 @@ paths: In addition to the `status` field, additional information (e.g. explaining a failure) can be included in the optional `message` field. It is possible that a single ext_keys request included multiple keys, It is possible that a single `ext_keys` request included multiple keys, where some are successfully delivered and other fail. This can be indicated by a KME sending multiple acknowledgement requests, with the container payload used to specify the status of different arrays of Loading @@ -201,9 +211,9 @@ paths: handled accordingly (e.g. to keep the provided metadata with each key so it can be relayed to the initiator SAE). A Code 200 Success will returned by a KME receiving a valid acknowledgement, otherwise an Error Code will be returned including details of the error. a KME receiving a valid acknowledgement shall return a `200` code, otherwise an Error Code shall be returned including details of the error. requestBody: description: Acknowledgements containers required: true Loading Loading @@ -330,7 +340,8 @@ components: message: timeout details: - timeout: >- No response received from KME to ext_keys request in No response received from KME to `ext_keys` request in sufficient time. 503-extkey: Loading Loading @@ -376,14 +387,16 @@ components: $ref: '#/components/schemas/extension' ack_containers: description: Array of acknowledgement containers description: Array of `ack_container` acknowledgement containers type: array items: $ref: '#/components/schemas/ack_container' ack_message: title: message description: Optional further details to expand upon the `ack_status`. description: | Optional further details to expand upon the `ack_status`. type: string ack_status: Loading Loading @@ -443,10 +456,10 @@ components: additionalProperties: true description: >- Dictionary of objects representing extension parameters 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). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. or return an error (e.g. as originated in the Get Key request that triggered key relaying to use the `ext_keys` call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. example: abc_route_type: 'direct' abc_method: Loading @@ -462,8 +475,9 @@ components: description: >- Dictionary of objects representing extension parameters that KME may ignore (e.g. as originated in the Get Key request that triggered key relaying to use the ext_keys call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. `ext_keys` call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. example: abc_module_type: vendor: 'Company ABC' Loading Loading @@ -544,10 +558,10 @@ components: type: array description: >- Array of IDs of target SAEs relevant to the request. (In a call to ext_keys to request keys to be shared these are the keys the initiator `ext_keys` to request keys to be shared these are the keys the initiator SAE wishes to share keys with.) A single target or multiple targets can be specified (where each target gets an identical key). The maximum number of IDs is defined as `max_sae_id_count` in Status data format. be specified (where each target gets an identical key). items: $ref: '#/components/schemas/target_sae_id' Loading
interop-kms_ExtraMarkup.yaml +54 −41 Original line number Diff line number Diff line openapi: 3.0.3 # Copyright 2025 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: | Loading @@ -10,7 +11,7 @@ info: contact: name: ETSI ISG QKD email: isgsupport@etsi.org version: Proposed changes to 0.4.1 version: Draft 0.5.1 license: name: BSD 3-Clause url: https://forge.etsi.org/legal-matters Loading Loading @@ -50,7 +51,7 @@ paths: supports. responses: '200': description: Supported versions description: Successful response content: application/json: schema: Loading @@ -67,23 +68,25 @@ paths: tags: - ext-keys description: | Pass an extended key request container comprising key material and Pass an `ext_key_container`<!-- ~ref_ext_key_container --> 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. Upon a valid request, the KME should aim to resond without undue delay with a `202`<!-- #op_po_kmapi_v1_ext_keys_c_202 --> ('Accepted'), Upon a valid request, the KME should aim to respond without undue delay with a `202`<!-- ~op_po_kmapi_v1_ext_keys_c_202 --> ('Accepted'), then it will issue a separate call (or multiple calls) to the specified `ack_callback_url`<!-- #op_post_kmapi_v1_ext_keys_ack --> `ack_callback_url`<!-- ~p_kmapi_v1_ext_keys_ack_cb_url --> endpoint once the keys are actually delivered (or fail to be delivered). A `400`<!-- #op_po_kmapi_v1_ext_keys_c_400 --> error will be returned A `400`<!-- ~op_po_kmapi_v1_ext_keys_c_400 --> error will be returned if the container format is invalid or includes initiator/target SAE IDs for which a valid route is not known to the KME. requestBody: description: Extended key request container. description: | `ext_key_container`<!-- ~ref_ext_key_container --> extended key request container. required: true content: application/json: Loading @@ -108,29 +111,32 @@ paths: tags: - ext-keys description: | Pass an extended key request container comprising key IDs to another Pass an `ext_key_container`<!-- ~ref_ext_key_container --> 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 delivered to SAEs). The `ext_key_container`<!-- ~ref_ext_key_container --> extended key request container contains keys matching those already passed to the KME. Upon a valid request, a KME shall discard keys relating to the provided key IDs and post a call to the specified `ack_callback_url`<!-- #op_post_kmapi_v1_ext_keys_ack --> describing the completed operation. After this, The KMEs shall not use the ipacted `ack_callback_url`<!-- ~p_kmapi_v1_ext_keys_ack_cb_url --> describing the completed operation. After this, The KMEs shall not use the impacted key, and it shall reject any requests to retrieve them using ETSI GS QKD 014, ETSI GS QKD 004, or otherwise. A `400`<!-- #op_po_kmapi_v1_ext_keys_c_400 --> code should be returned A `400`<!-- ~op_po_kmapi_v1_ext_keys_c_400 --> code should be returned if the request is known without further investigation to be invalid. Otherwise, failures to void keys can be reported subsequently via `ack_callback_url`<!-- #op_post_kmapi_v1_ext_keys_ack --> `ack_callback_url`<!-- ~p_kmapi_v1_ext_keys_ack_cb_url --> If this operation is requested with an empty `key_ids`<!-- #post_kmapi_v1_ext_keys_void_key_ids --> array all keys shared between the prspecified SAEs shall be voided. To reduce the risk of accidental key loss, unles the to confirm this action an `all_confirmation` boolean field needs to be passed with a value of `true`, otherwise a Code 400 error is returned). `key_ids`<!-- ~p_kmapi_v1_ext_keys_void_key_ids --> array all keys shared between the pre-specified SAEs shall be voided. To reduce the risk of accidental key loss, the KME shall reject any void request that does specify key ID(s) but without including the `all_confirmation` URL parameter with a value of true, and return a `400`<!-- ~op_po_kmapi_v1_ext_keys_c_400 --> code. parameters: - $ref: '#/components/parameters/all_confirmation' requestBody: Loading Loading @@ -160,16 +166,17 @@ paths: - ext-keys description: | Pass one or more key acknowledgement container comprising key IDs associated with a previous call to the ext_keys method by an external associated with a previous call to the `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> method by an external KMS. The status of all keys in the container is indicated by the status field. The `ack_status` field may be `relayed` `voided` `failed` or `key not The `ack_status` field may be `relayed`, `voided`, `failed`, or `key not present`. - `relayed` indicates the KME has successfully relayed the specified keys to the requested target (where the initiator_sae_id and target_sae_id are specified in the acknowledgement container). If the keys to the requested target (where the `initiator_sae_id` and `target_sae_id` are specified in the acknowledgement container). If the initiator requested multiple targets, the acknowledgements for each target are separate acknowledgement containers (since the status for each target may be different). Loading @@ -178,7 +185,8 @@ paths: so they will not be delivered to applications. - `failed` indicates that the requested operation on the specified keys could not be completed. For example, an ext_keys request may not could not be completed. For example, an `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request may not complete if there is insufficient key material for relaying. Also, a void request will fail if the specified keys have already been delivered to a requesting SAE. Loading @@ -189,7 +197,8 @@ paths: In addition to the `status` field, additional information (e.g. explaining a failure) can be included in the optional `message` field. It is possible that a single ext_keys request included multiple keys, It is possible that a single `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request included multiple keys, where some are successfully delivered and other fail. This can be indicated by a KME sending multiple acknowledgement requests, with the container payload used to specify the status of different arrays of Loading @@ -201,9 +210,9 @@ paths: handled accordingly (e.g. to keep the provided metadata with each key so it can be relayed to the initiator SAE). A Code 200 Success will returned by a KME receiving a valid acknowledgement, otherwise an Error Code will be returned including details of the error. a KME receiving a valid acknowledgement shall return a `200`<!-- ~op_po_kmapi_v1_ack_c_200 --> code, otherwise an Error Code shall be returned including details of the error. requestBody: description: Acknowledgements containers required: true Loading Loading @@ -330,7 +339,8 @@ components: message: timeout details: - timeout: >- No response received from KME to ext_keys request in No response received from KME to `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request in sufficient time. 503-extkey: Loading Loading @@ -376,14 +386,16 @@ components: $ref: '#/components/schemas/extension' ack_containers: description: Array of acknowledgement containers description: Array of `ack_container` acknowledgement containers type: array items: $ref: '#/components/schemas/ack_container' ack_message: title: message description: Optional further details to expand upon the `ack_status`. description: | Optional further details to expand upon the `ack_status`<!-- ~ref_ack_status -->. type: string ack_status: Loading Loading @@ -443,10 +455,10 @@ components: additionalProperties: true description: >- Dictionary of objects representing extension parameters 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). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. or return an error (e.g. as originated in the Get Key request that triggered key relaying to use the `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. example: abc_route_type: 'direct' abc_method: Loading @@ -462,8 +474,9 @@ components: description: >- Dictionary of objects representing extension parameters that KME may ignore (e.g. as originated in the Get Key request that triggered key relaying to use the ext_keys call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> call). Objects may be of any type and custom extensions should be named starting with a vendor prefix followed by an underscore. example: abc_module_type: vendor: 'Company ABC' Loading Loading @@ -544,10 +557,10 @@ components: type: array description: >- Array of IDs of target SAEs relevant to the request. (In a call to ext_keys to request keys to be shared these are the keys the initiator `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> to request keys to be shared these are the keys the initiator SAE wishes to share keys with.) A single target or multiple targets can be specified (where each target gets an identical key). The maximum number of IDs is defined as `max_sae_id_count` in Status data format. be specified (where each target gets an identical key). items: $ref: '#/components/schemas/target_sae_id' Loading
