Loading README.md +1 −1 Original line number Diff line number Diff line Loading @@ -13,7 +13,7 @@ Note: The default branch in this repository has been renamed `main` as per QKD(2 ## 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/main/interop-kms_ExtraMarkup.yaml). [Swagger Editor](https://forge.etsi.org/swagger/editor-versions/v3.8.0/?url=https://forge.etsi.org/rep/qkd/gs020-interop-kms/-/raw/wrk_rapporteur_dec/interop-kms_ExtraMarkup.yaml). ## Contact Loading interop-kms_ExtraMarkup.yaml +222 −48 Original line number Diff line number Diff line Loading @@ -3,22 +3,168 @@ 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: Draft 0.6.1 version: Proposed changes to Draft 0.6.1 license: name: BSD 3-Clause url: https://forge.etsi.org/legal-matters x-logo: url: 'https://www.etsi.org/templates/etsi/img/logo.svg' altText: ETSI logo description: | # Overview OpenAPI description of the Interoperable Key Management System API being developed by ETSI ISG QKD under work item DGS/QKD-020_InteropKMS. The present document describes a communication protocol and data format for quantum key distribution (QKD) networks to exchanges keys within a trusted interworking node. It is intended to allow interoperability of equipment from different vendors as well as between different network operators. A REST (REpresentational State Transfer) API is specified as a simple, scalable, widely deployed approach that is familiar to a large developer community. The REST-based API specifies the format of the URIs, the communication protocols (HTTPS), and the JSON (JavaScript Object Notation) data format encoding of posted parameters and responses, including key material. The interface is intended for use within a trusted node and enables the transfer of keys between key management systems. # Connection Specification The common connection specifications for the API are as follows: | Name | Description | |---------------------|--------------------------------------------------| | Communication Protocol | HTTPS | | Character code | UTF-8 | | HTTP Content-type | application/json | SAEs shall connect to KMEs using HTTPS protocols with Transport Layer Security (TLS) version 1.3 (or higher). At the connection establishment, mutual authentication between the SAE and KME shall be performed. The SAE shall verify the validity of the certificate possessed by the KME and confirm the KME ID based on the certificate. If the KME certificate is not valid, the SAE will not proceed to use the API with the KME. Similarly, the KME shall verify the validity of the certificate possessed by the SAE and confirm its SAE ID based on the certificate. Practically, X.509 certificates should be used where the identifying information is specified as a Distinguished Name (DN). Specifically, the SAE's ID should be included as the UID field of the DN or if that is not possible, as the Common Name (CN). If the certificate is invalid, or if the SAE ID in the certificate does not match the SAE ID for which the API call refers to, the KME will reject the API call. # Operation of the API The primary purpose of the key management system in network of QKD systems is to deliver QKD keys to cryptographic applications. Aligned with the terminology in ETSI GS QKD 014 [i.1], cryptographic key-consuming applications at each node are Secure Application Entities (SAEs) and instances of key management software that they connect to are Key Management Entities (KMEs). When an SAE initiates a request to a KME for symmetric keys shared with the "target SAE" it becomes the "initiator SAE". The key management system of the network is responsible for implementing secure key distribution between the KMEs to enable key requests from the initiator and target SAEs to be honoured. APIs have been specified in ETSI GS QKD 014 [i.1] and ETSI GS QKD 004 [i.2] that define methods and data formats for the delivery of keys from a KME to a SAE. However, where different parts of a network use key management systems that are incompatible or managed separately etc. a standardized interface is required for KMEs to pass keys horizontally between different parts of the network. The API described in the present document enables such key transfers such that shared keys can be delivered to SAEs that connect to KMEs in different parts of the network. To ensure interoperability between the KMEs, asynchronous mode shall be the required mode of operation supported by all KMEs for the API methods defined in the present document. In asynchronous API calls, the KME shall respond quickly with an HTTP status code 202 (Request Accepted) and does not wait for the completion of the key request. Upon the completion of the key request, it will issue a separate call(s) to the `ack_callback_url`<!-- ~p_kmapi_v1_ext_keys_ack_cb_url --> to notify the completion result. This mode allows scalability and improves efficiency especially in large scale networks with heavy operations and high traffic. Synchronous mode can be supported as an optional mode in addition to the asynchronous mode for specific implementation(s). Synchronous mode allows KMEs to manage key transfer sessions directly as HTTPS sessions to simplify the implementation of the KMEs. This benefit might outweigh the flexibility and scalability advantages for systems where the volume and frequency of key transfers are relatively low. An example of a network with several parts using systems from different vendors is illustrated in Figure 1. Each node includes QKD module(s) and at least one KME from the vendor of the links that it connects to. Nodes that are a point of presence in more than one part of the network are referred to as "interworking nodes". The use of this API within the network is transparent to the SAEs and does not impose any additional requirements on the API(s) used for key delivery from the KMEs to the SAEs. NOTE: The API described in the present document is aligned with the API specified in ETSI GS QKD 014 [i.1] but a similar API could be developed aligned with ETSI GS QKD 004 [i.2]. Figure 1: Schematic of multi-vendor QKD network # Example of use of the API Figure 2 shows a use-case in which the ext_keys method is used to pass keys using between KMEs in a node of a three-node network comprised of two parts using otherwise incompatible systems from different vendors. The asynchronous key delivery between 2 QKD network vendors is uncoupled from any SAE protocol or workflow. These steps can be triggered when keys are requested by an initiator SAE (reactive pattern), or by an initiator KME node that fills a buffer of keys (proactive pattern). The asynchronous key delivery steps are as follows: - Step 1-2: KME A and KME B (vendor 1) obtain keys from the QKD modules that were established over QKD link #1. - Step 3: In the interworking node, KME B (vendor 1) sends an `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> ext_keys request to KME B (vendor 2), including a set of keys with corresponding key IDs, the initiator_sae_id and the target_sae_id. - Step 4: KME B (vendor 2) responds to the `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request from KME B (Vendor 1) with a success message (HTTP status code 202), meaning request accepted. - Step 5: KME B (vendor 2) obtains keys established over QKD link #2 from the QKD modules and uses them to securely relay the keys and key IDs obtained from KME B (vendor 1) to KME C. - Step 6-7: Once the keys have been successfully delivered to KME C, KME B (Vendor 2) sends an ack request to KME B (Vendor 1), including a set of key IDs and delivered key status, the `initiator_sae_id`<!-- ~ref_initiator_sae_id --> and the `target_sae_id`<!-- ~ref_target_sae_id -->. - Step 8: KME B (vendor 1) notifies the initiator KME A (vendor 1) node that the keys have been delivered or not, to their final destination nodes. - Step 9: KME B (vendor 1) responds to the ack request from KME B (Vendor 2) with a success message (HTTP status code 200). For any reason, if status code indicates an error, KME B (vendor 2) notifies final destination that keys are not available anymore. Separately an SAE pair receives keys as follow: - SAE A (the initiator SAE) sends a keys request to KME A, specifying SAE C as the target_sae_id. - KME A returns keys and associated key IDs to SAE A. - SAE A tells SAE C the key IDs and SAE C sends a keys_with_id request to KME C with the key IDs. - KME C returns the keys and corresponding key IDs to SAE C. In this manner keys are shared between SAEs A and C via the use of ext_keys within the interworking node. servers: - url: https://{kme_hostname} description: Local KME server Loading Loading @@ -83,7 +229,7 @@ paths: mode, as the KMEs shall not respond with an acknowledgement, `ack_callback_url`<!-- ~ref_ack_callback_url --> is omitted in this implementation. Instead, the KME shall respond with a `200`<!-- ~op_po_kmapi_v1_ext_keys_c_200 -->` ('Successful'). `200`<!-- ~op_po_kmapi_v1_ext_keys_c_200 --> ('Successful'). A `400`<!-- ~op_po_kmapi_v1_ext_keys_c_400 --> error shall be returned if the container format is invalid or includes initiator/target SAE IDs Loading Loading @@ -185,8 +331,9 @@ paths: KMS. The status of all keys in the container is indicated by the status field. The `ack_status`<!-- ~ref_ack_status --> field may be `relayed`, `voided`, `failed`, or `key not present`. The `ack_status`<!-- ~ref_ack_status --> field shall not take a value other than one of the following: `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 Loading Loading @@ -401,8 +548,7 @@ components: title: timeout details: - timeout: >- No response received from KME to `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request in No response received from KME to ext_keys request in sufficient time. 503-extkey: Loading Loading @@ -465,21 +611,26 @@ components: extension: $ref: '#/components/schemas/extension' example: - key_ids: - key_id: 550e8400-e29b-41d4-a716-446655440000 - extension: - E32473_extension1: Some string - ack_status: relayed - initiator_sae_id: encryptor1 - target_sae_id: encryptor2 - message: string - extension: - E32473_extension1: Some string - E32473_extension2: key_ids: key_id: 550e8400-e29b-41d4-a716-446655440000 extension: E32473_extension1: Some string applicable to a particular key E32473_extension2: - property1: 10111 - property2: - subprop1: 21 - subprop2: true ack_status: relayed initiator_sae_id: encryptor1 target_sae_id: encryptor2 message: string extension: E32473_extension1: Some string applicable to all keys in the container E32473_extension2: property1: 10111 property2: subprop1: 21 subprop2: true ack_containers: description: Acknowledgements container `ack_containers`<!-- ~ref_ack_containers --> Loading @@ -489,36 +640,43 @@ components: items: $ref: '#/components/schemas/ack_container' example: - - key_ids: - key_id: 550e8400-e29b-41d4-a716-446655440000 - extension: - E32473_extension1: Some string - - ack_status: relayed - - initiator_sae_id: encryptor1 - - target_sae_id: encryptor2 - - message: string - - extension: - E32473_extension1: Some string - E32473_extension2: - key_ids: key_id: 550e8400-e29b-41d4-a716-446655440000 extension: E32473_extension1: Some string applicable to a particular key E32473_extension2: - property1: 10111 - property2: - subprop1: 21 - subprop2: true ack_status: relayed initiator_sae_id: encryptor1 target_sae_id: encryptor2 message: string extension: E32473_extension1: Some string applicable to all keys in the container E32473_extension2: property1: 10111 property2: subprop1: 21 subprop2: true ack_message: description: | Acknowledgement message `ack_message`<!-- ~ref_ack_message --> Optional further details to expand upon the optionally provides further details to expand upon the `ack_status`<!-- ~ref_ack_status -->. type: string maxLength: 4096 ack_status: description: Acknowledgement status `ack_status`<!-- ~ref_ack_status --> describes the status of acknowledged keys. is an enum that describes the status of the acknowledged keys. See `ext_keys/ack`<!-- ~op_post_kmapi_v1_ext_keys_ack --> for details of the usage of `ack_status`<!-- ~ref_ack_status -->. type: string maxLength: 4096 maxLength: 16 enum: - relayed - voided Loading @@ -529,7 +687,7 @@ components: capabilities: type: array description: | Capabilities `capabilities`<!-- ~ref_ack_status --> is an Capabilities `capabilities`<!-- ~ref_capabilities --> is an array of strings each indicating a `capability`<!-- ~ref_capability --> supported by the host. Loading @@ -543,7 +701,7 @@ components: - synchronous_mode capability: description: Capability `capabiity`<!-- ~ref_capability --> is a string that description: Capability `capability`<!-- ~ref_capability --> is a string that indicates a capability supported by the host. type: string maxLength: 128 Loading Loading @@ -576,7 +734,7 @@ components: - key_id: '550e8400-e29b-41d4-a716-446655440000' - value: wHHVxRwDJs3/bXd38GHP3oe4svTuRpZS0yCC7x4Ly+s= - extension: E32473_extension1: Some string E32473_extension1: Some string applicable to a particular key E32473_extension2: property1: 10111 property2: Some text Loading @@ -594,6 +752,7 @@ components: - primary: qkd - secondary: pqc extension_optional: - E32473_extension1: Some string applicable to all keys in the container - E32473_module_type: - vendor: Company ABC - protocol: BB84 Loading @@ -613,6 +772,11 @@ components: ETSI might specify extensions in future and ETSI's IANA Private Enterprise Number `13019` is reserved and shall not be used at this time. Key management entities shall follow the specificaion of any `extension`<!-- ~ref_extension --> it implements. This includes passing on without change any information indicated to be immutable in the specification of the extension. example: - E32473_extension1: 'Some string' - E32473_extension2: Loading @@ -638,6 +802,11 @@ components: ETSI might specify extensions in future and ETSI's IANA Private Enterprise Number `13019` is reserved and shall not be used at this time. Unless a recieving key managment entity recognises and can implement all requirements within the specification of an `extension_mandatory`<!-- ~ref_extension_mandatory --> extension it shall reject the request. example: - E32473_module_type: - vendor: Company ABC Loading @@ -660,6 +829,11 @@ components: ETSI might specify extensions in future and ETSI's IANA Private Enterprise Number `13019` is reserved and shall not be used at this time. If a key managment entity does not recognise an `extension_optional`<!-- ~ref_extension_optional --> extension it shall ensure that the `extension_optional`<!-- ~ref_extension_optional --> extension is passed on without change. example: - E32473_module_type: - vendor: Company ABC Loading @@ -670,7 +844,7 @@ components: initiator_sae_id: type: string description: >- Initiatior SAE ID `initiator_sae_id`<!-- ~ref_initiator_sae_id --> is the ID Initiator SAE ID `initiator_sae_id`<!-- ~ref_initiator_sae_id --> is the ID of the SAE that initiated the request to share the key(s) relevant to the request. example: encryptor1 Loading Loading @@ -757,7 +931,7 @@ components: type: object description: | Problem Details `problem_details`<!-- ~ref_problem_details --> is an object according shall satisfy the requirements in IETF RFC 9457<!-- ~i_rfc_9457 --> according shall satisfy the requirements in IETF RFC 9457<!-- ~n_REF_IETFRFC9457 --> for Problem Details for HTTP APIs. properties: type: Loading Loading @@ -825,7 +999,7 @@ components: right) when decoding. It is not safe to strip all bits with value zero from the end of the decoded key since this can bias keys. Decoding needs to make use of independent knowledge of the requested key size to correctly strip such padding in order to the requested key size to correctly strip such padding to recover a valid key. (The base64 data encoding scheme and the `=` padding character rules it includes can only indicate the size of the encoding input in integer byte sizes. The final character Loading Loading
README.md +1 −1 Original line number Diff line number Diff line Loading @@ -13,7 +13,7 @@ Note: The default branch in this repository has been renamed `main` as per QKD(2 ## 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/main/interop-kms_ExtraMarkup.yaml). [Swagger Editor](https://forge.etsi.org/swagger/editor-versions/v3.8.0/?url=https://forge.etsi.org/rep/qkd/gs020-interop-kms/-/raw/wrk_rapporteur_dec/interop-kms_ExtraMarkup.yaml). ## Contact Loading
interop-kms_ExtraMarkup.yaml +222 −48 Original line number Diff line number Diff line Loading @@ -3,22 +3,168 @@ 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: Draft 0.6.1 version: Proposed changes to Draft 0.6.1 license: name: BSD 3-Clause url: https://forge.etsi.org/legal-matters x-logo: url: 'https://www.etsi.org/templates/etsi/img/logo.svg' altText: ETSI logo description: | # Overview OpenAPI description of the Interoperable Key Management System API being developed by ETSI ISG QKD under work item DGS/QKD-020_InteropKMS. The present document describes a communication protocol and data format for quantum key distribution (QKD) networks to exchanges keys within a trusted interworking node. It is intended to allow interoperability of equipment from different vendors as well as between different network operators. A REST (REpresentational State Transfer) API is specified as a simple, scalable, widely deployed approach that is familiar to a large developer community. The REST-based API specifies the format of the URIs, the communication protocols (HTTPS), and the JSON (JavaScript Object Notation) data format encoding of posted parameters and responses, including key material. The interface is intended for use within a trusted node and enables the transfer of keys between key management systems. # Connection Specification The common connection specifications for the API are as follows: | Name | Description | |---------------------|--------------------------------------------------| | Communication Protocol | HTTPS | | Character code | UTF-8 | | HTTP Content-type | application/json | SAEs shall connect to KMEs using HTTPS protocols with Transport Layer Security (TLS) version 1.3 (or higher). At the connection establishment, mutual authentication between the SAE and KME shall be performed. The SAE shall verify the validity of the certificate possessed by the KME and confirm the KME ID based on the certificate. If the KME certificate is not valid, the SAE will not proceed to use the API with the KME. Similarly, the KME shall verify the validity of the certificate possessed by the SAE and confirm its SAE ID based on the certificate. Practically, X.509 certificates should be used where the identifying information is specified as a Distinguished Name (DN). Specifically, the SAE's ID should be included as the UID field of the DN or if that is not possible, as the Common Name (CN). If the certificate is invalid, or if the SAE ID in the certificate does not match the SAE ID for which the API call refers to, the KME will reject the API call. # Operation of the API The primary purpose of the key management system in network of QKD systems is to deliver QKD keys to cryptographic applications. Aligned with the terminology in ETSI GS QKD 014 [i.1], cryptographic key-consuming applications at each node are Secure Application Entities (SAEs) and instances of key management software that they connect to are Key Management Entities (KMEs). When an SAE initiates a request to a KME for symmetric keys shared with the "target SAE" it becomes the "initiator SAE". The key management system of the network is responsible for implementing secure key distribution between the KMEs to enable key requests from the initiator and target SAEs to be honoured. APIs have been specified in ETSI GS QKD 014 [i.1] and ETSI GS QKD 004 [i.2] that define methods and data formats for the delivery of keys from a KME to a SAE. However, where different parts of a network use key management systems that are incompatible or managed separately etc. a standardized interface is required for KMEs to pass keys horizontally between different parts of the network. The API described in the present document enables such key transfers such that shared keys can be delivered to SAEs that connect to KMEs in different parts of the network. To ensure interoperability between the KMEs, asynchronous mode shall be the required mode of operation supported by all KMEs for the API methods defined in the present document. In asynchronous API calls, the KME shall respond quickly with an HTTP status code 202 (Request Accepted) and does not wait for the completion of the key request. Upon the completion of the key request, it will issue a separate call(s) to the `ack_callback_url`<!-- ~p_kmapi_v1_ext_keys_ack_cb_url --> to notify the completion result. This mode allows scalability and improves efficiency especially in large scale networks with heavy operations and high traffic. Synchronous mode can be supported as an optional mode in addition to the asynchronous mode for specific implementation(s). Synchronous mode allows KMEs to manage key transfer sessions directly as HTTPS sessions to simplify the implementation of the KMEs. This benefit might outweigh the flexibility and scalability advantages for systems where the volume and frequency of key transfers are relatively low. An example of a network with several parts using systems from different vendors is illustrated in Figure 1. Each node includes QKD module(s) and at least one KME from the vendor of the links that it connects to. Nodes that are a point of presence in more than one part of the network are referred to as "interworking nodes". The use of this API within the network is transparent to the SAEs and does not impose any additional requirements on the API(s) used for key delivery from the KMEs to the SAEs. NOTE: The API described in the present document is aligned with the API specified in ETSI GS QKD 014 [i.1] but a similar API could be developed aligned with ETSI GS QKD 004 [i.2]. Figure 1: Schematic of multi-vendor QKD network # Example of use of the API Figure 2 shows a use-case in which the ext_keys method is used to pass keys using between KMEs in a node of a three-node network comprised of two parts using otherwise incompatible systems from different vendors. The asynchronous key delivery between 2 QKD network vendors is uncoupled from any SAE protocol or workflow. These steps can be triggered when keys are requested by an initiator SAE (reactive pattern), or by an initiator KME node that fills a buffer of keys (proactive pattern). The asynchronous key delivery steps are as follows: - Step 1-2: KME A and KME B (vendor 1) obtain keys from the QKD modules that were established over QKD link #1. - Step 3: In the interworking node, KME B (vendor 1) sends an `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> ext_keys request to KME B (vendor 2), including a set of keys with corresponding key IDs, the initiator_sae_id and the target_sae_id. - Step 4: KME B (vendor 2) responds to the `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request from KME B (Vendor 1) with a success message (HTTP status code 202), meaning request accepted. - Step 5: KME B (vendor 2) obtains keys established over QKD link #2 from the QKD modules and uses them to securely relay the keys and key IDs obtained from KME B (vendor 1) to KME C. - Step 6-7: Once the keys have been successfully delivered to KME C, KME B (Vendor 2) sends an ack request to KME B (Vendor 1), including a set of key IDs and delivered key status, the `initiator_sae_id`<!-- ~ref_initiator_sae_id --> and the `target_sae_id`<!-- ~ref_target_sae_id -->. - Step 8: KME B (vendor 1) notifies the initiator KME A (vendor 1) node that the keys have been delivered or not, to their final destination nodes. - Step 9: KME B (vendor 1) responds to the ack request from KME B (Vendor 2) with a success message (HTTP status code 200). For any reason, if status code indicates an error, KME B (vendor 2) notifies final destination that keys are not available anymore. Separately an SAE pair receives keys as follow: - SAE A (the initiator SAE) sends a keys request to KME A, specifying SAE C as the target_sae_id. - KME A returns keys and associated key IDs to SAE A. - SAE A tells SAE C the key IDs and SAE C sends a keys_with_id request to KME C with the key IDs. - KME C returns the keys and corresponding key IDs to SAE C. In this manner keys are shared between SAEs A and C via the use of ext_keys within the interworking node. servers: - url: https://{kme_hostname} description: Local KME server Loading Loading @@ -83,7 +229,7 @@ paths: mode, as the KMEs shall not respond with an acknowledgement, `ack_callback_url`<!-- ~ref_ack_callback_url --> is omitted in this implementation. Instead, the KME shall respond with a `200`<!-- ~op_po_kmapi_v1_ext_keys_c_200 -->` ('Successful'). `200`<!-- ~op_po_kmapi_v1_ext_keys_c_200 --> ('Successful'). A `400`<!-- ~op_po_kmapi_v1_ext_keys_c_400 --> error shall be returned if the container format is invalid or includes initiator/target SAE IDs Loading Loading @@ -185,8 +331,9 @@ paths: KMS. The status of all keys in the container is indicated by the status field. The `ack_status`<!-- ~ref_ack_status --> field may be `relayed`, `voided`, `failed`, or `key not present`. The `ack_status`<!-- ~ref_ack_status --> field shall not take a value other than one of the following: `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 Loading Loading @@ -401,8 +548,7 @@ components: title: timeout details: - timeout: >- No response received from KME to `ext_keys`<!-- ~op_post_kmapi_v1_ext_keys --> request in No response received from KME to ext_keys request in sufficient time. 503-extkey: Loading Loading @@ -465,21 +611,26 @@ components: extension: $ref: '#/components/schemas/extension' example: - key_ids: - key_id: 550e8400-e29b-41d4-a716-446655440000 - extension: - E32473_extension1: Some string - ack_status: relayed - initiator_sae_id: encryptor1 - target_sae_id: encryptor2 - message: string - extension: - E32473_extension1: Some string - E32473_extension2: key_ids: key_id: 550e8400-e29b-41d4-a716-446655440000 extension: E32473_extension1: Some string applicable to a particular key E32473_extension2: - property1: 10111 - property2: - subprop1: 21 - subprop2: true ack_status: relayed initiator_sae_id: encryptor1 target_sae_id: encryptor2 message: string extension: E32473_extension1: Some string applicable to all keys in the container E32473_extension2: property1: 10111 property2: subprop1: 21 subprop2: true ack_containers: description: Acknowledgements container `ack_containers`<!-- ~ref_ack_containers --> Loading @@ -489,36 +640,43 @@ components: items: $ref: '#/components/schemas/ack_container' example: - - key_ids: - key_id: 550e8400-e29b-41d4-a716-446655440000 - extension: - E32473_extension1: Some string - - ack_status: relayed - - initiator_sae_id: encryptor1 - - target_sae_id: encryptor2 - - message: string - - extension: - E32473_extension1: Some string - E32473_extension2: - key_ids: key_id: 550e8400-e29b-41d4-a716-446655440000 extension: E32473_extension1: Some string applicable to a particular key E32473_extension2: - property1: 10111 - property2: - subprop1: 21 - subprop2: true ack_status: relayed initiator_sae_id: encryptor1 target_sae_id: encryptor2 message: string extension: E32473_extension1: Some string applicable to all keys in the container E32473_extension2: property1: 10111 property2: subprop1: 21 subprop2: true ack_message: description: | Acknowledgement message `ack_message`<!-- ~ref_ack_message --> Optional further details to expand upon the optionally provides further details to expand upon the `ack_status`<!-- ~ref_ack_status -->. type: string maxLength: 4096 ack_status: description: Acknowledgement status `ack_status`<!-- ~ref_ack_status --> describes the status of acknowledged keys. is an enum that describes the status of the acknowledged keys. See `ext_keys/ack`<!-- ~op_post_kmapi_v1_ext_keys_ack --> for details of the usage of `ack_status`<!-- ~ref_ack_status -->. type: string maxLength: 4096 maxLength: 16 enum: - relayed - voided Loading @@ -529,7 +687,7 @@ components: capabilities: type: array description: | Capabilities `capabilities`<!-- ~ref_ack_status --> is an Capabilities `capabilities`<!-- ~ref_capabilities --> is an array of strings each indicating a `capability`<!-- ~ref_capability --> supported by the host. Loading @@ -543,7 +701,7 @@ components: - synchronous_mode capability: description: Capability `capabiity`<!-- ~ref_capability --> is a string that description: Capability `capability`<!-- ~ref_capability --> is a string that indicates a capability supported by the host. type: string maxLength: 128 Loading Loading @@ -576,7 +734,7 @@ components: - key_id: '550e8400-e29b-41d4-a716-446655440000' - value: wHHVxRwDJs3/bXd38GHP3oe4svTuRpZS0yCC7x4Ly+s= - extension: E32473_extension1: Some string E32473_extension1: Some string applicable to a particular key E32473_extension2: property1: 10111 property2: Some text Loading @@ -594,6 +752,7 @@ components: - primary: qkd - secondary: pqc extension_optional: - E32473_extension1: Some string applicable to all keys in the container - E32473_module_type: - vendor: Company ABC - protocol: BB84 Loading @@ -613,6 +772,11 @@ components: ETSI might specify extensions in future and ETSI's IANA Private Enterprise Number `13019` is reserved and shall not be used at this time. Key management entities shall follow the specificaion of any `extension`<!-- ~ref_extension --> it implements. This includes passing on without change any information indicated to be immutable in the specification of the extension. example: - E32473_extension1: 'Some string' - E32473_extension2: Loading @@ -638,6 +802,11 @@ components: ETSI might specify extensions in future and ETSI's IANA Private Enterprise Number `13019` is reserved and shall not be used at this time. Unless a recieving key managment entity recognises and can implement all requirements within the specification of an `extension_mandatory`<!-- ~ref_extension_mandatory --> extension it shall reject the request. example: - E32473_module_type: - vendor: Company ABC Loading @@ -660,6 +829,11 @@ components: ETSI might specify extensions in future and ETSI's IANA Private Enterprise Number `13019` is reserved and shall not be used at this time. If a key managment entity does not recognise an `extension_optional`<!-- ~ref_extension_optional --> extension it shall ensure that the `extension_optional`<!-- ~ref_extension_optional --> extension is passed on without change. example: - E32473_module_type: - vendor: Company ABC Loading @@ -670,7 +844,7 @@ components: initiator_sae_id: type: string description: >- Initiatior SAE ID `initiator_sae_id`<!-- ~ref_initiator_sae_id --> is the ID Initiator SAE ID `initiator_sae_id`<!-- ~ref_initiator_sae_id --> is the ID of the SAE that initiated the request to share the key(s) relevant to the request. example: encryptor1 Loading Loading @@ -757,7 +931,7 @@ components: type: object description: | Problem Details `problem_details`<!-- ~ref_problem_details --> is an object according shall satisfy the requirements in IETF RFC 9457<!-- ~i_rfc_9457 --> according shall satisfy the requirements in IETF RFC 9457<!-- ~n_REF_IETFRFC9457 --> for Problem Details for HTTP APIs. properties: type: Loading Loading @@ -825,7 +999,7 @@ components: right) when decoding. It is not safe to strip all bits with value zero from the end of the decoded key since this can bias keys. Decoding needs to make use of independent knowledge of the requested key size to correctly strip such padding in order to the requested key size to correctly strip such padding to recover a valid key. (The base64 data encoding scheme and the `=` padding character rules it includes can only indicate the size of the encoding input in integer byte sizes. The final character Loading
