From dcf1f4520c7bb58477a28394c4631103295552ba Mon Sep 17 00:00:00 2001 From: Martin Ward Date: Tue, 16 Dec 2025 12:49:32 +0000 Subject: [PATCH] Changes as at QKD-AH#39aa --- README.md | 2 +- interop-kms_ExtraMarkup.yaml | 270 ++++++++++++++++++++++++++++------- 2 files changed, 223 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 024b4fc..518b5db 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/interop-kms_ExtraMarkup.yaml b/interop-kms_ExtraMarkup.yaml index d894269..aa3eda7 100644 --- a/interop-kms_ExtraMarkup.yaml +++ b/interop-kms_ExtraMarkup.yaml @@ -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` 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` 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` + 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` + and the `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 @@ -83,7 +229,7 @@ paths: mode, as the KMEs shall not respond with an acknowledgement, `ack_callback_url` is omitted in this implementation. Instead, the KME shall respond with a - `200`` ('Successful'). + `200` ('Successful'). A `400` error shall be returned if the container format is invalid or includes initiator/target SAE IDs @@ -185,8 +331,9 @@ paths: 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 present`. + The `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 @@ -401,8 +548,7 @@ components: title: 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: @@ -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` @@ -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: - - property1: 10111 - - property2: - - subprop1: 21 - - subprop2: true + - 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` - Optional further details to expand upon the + optionally provides further details to expand upon the `ack_status`. type: string maxLength: 4096 ack_status: description: Acknowledgement status `ack_status` - describes the status of acknowledged keys. + is an enum that describes the status of the acknowledged keys. + See `ext_keys/ack` for details + of the usage of `ack_status`. type: string - maxLength: 4096 + maxLength: 16 enum: - relayed - voided @@ -529,7 +687,7 @@ components: capabilities: type: array description: | - Capabilities `capabilities` is an + Capabilities `capabilities` is an array of strings each indicating a `capability` supported by the host. @@ -543,7 +701,7 @@ components: - synchronous_mode capability: - description: Capability `capabiity` is a string that + description: Capability `capability` is a string that indicates a capability supported by the host. type: string maxLength: 128 @@ -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 @@ -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 @@ -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` 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: @@ -634,10 +798,15 @@ components: key relaying to use the `ext_keys` endpoint). Objects may be of any type and custom extensions should be named starting with a vendor prefix that shall be the letter `E` - followed byan IANA Private Enterprise Number (PEN) followed by an underscore. + followed by an IANA Private Enterprise Number (PEN) followed by an underscore. 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` extension it shall + reject the request. example: - E32473_module_type: - vendor: Company ABC @@ -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` extension it shall ensure + that the `extension_optional` extension is + passed on without change. example: - E32473_module_type: - vendor: Company ABC @@ -670,7 +844,7 @@ components: initiator_sae_id: type: string description: >- - Initiatior SAE ID `initiator_sae_id` is the ID + Initiator SAE ID `initiator_sae_id` is the ID of the SAE that initiated the request to share the key(s) relevant to the request. example: encryptor1 @@ -757,7 +931,7 @@ components: type: object description: | Problem Details `problem_details` is an object - according shall satisfy the requirements in IETF RFC 9457 + according shall satisfy the requirements in IETF RFC 9457 for Problem Details for HTTP APIs. properties: type: @@ -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 -- GitLab