From 882469e1213e921d2e6c8317affc42b6acc8f3cf Mon Sep 17 00:00:00 2001 From: wardmart Date: Tue, 26 Nov 2024 10:10:24 +0000 Subject: [PATCH 1/2] Editorial changes and extra markup for Word --- LICENSE | 2 +- README.md | 2 +- interop-kms.yaml | 392 +++++++++++---------- interop-kms_ExtraMarkup.yaml | 650 +++++++++++++++++++++++++++++++++++ 4 files changed, 859 insertions(+), 187 deletions(-) create mode 100644 interop-kms_ExtraMarkup.yaml diff --git a/LICENSE b/LICENSE index 6adf313..2708889 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright 2021 ETSI +Copyright 2024 ETSI Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/README.md b/README.md index 12621ec..4be5700 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.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-editorial01/interop-kms.yaml). ## Contact diff --git a/interop-kms.yaml b/interop-kms.yaml index 90d1251..b9a148e 100644 --- a/interop-kms.yaml +++ b/interop-kms.yaml @@ -10,10 +10,13 @@ info: contact: name: ETSI ISG QKD email: isgsupport@etsi.org - version: 0.4.1 + version: Proposed changes to 0.4.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 servers: - url: https://{kme_hostname} description: Local KME server @@ -23,11 +26,20 @@ servers: externalDocs: description: Work Item description url: https://portal.etsi.org/webapp/WorkProgram/Report_WorkItem.asp?WKI_ID=63115 +tags: + - name: versions + description: Information about supported API versions + + - name: ext-keys + description: Pass keys to another KME (external keys) + paths: /kmapi/versions: get: summary: Get supported API versions operationId: get-versions + tags: + - versions description: | Return list of supported ETSI GS QKD 020 API versions. @@ -52,6 +64,8 @@ paths: post: summary: Transfer keys to external KMS operationId: post-ext_keys + tags: + - ext-keys description: | Pass an extended key request container comprising key material and associated data to another KME, for the key(s) to be delivered (by relay @@ -59,14 +73,15 @@ paths: request container contains keys matching those to be delivered to the initiator SAE. - This method is 'non-blocking'. Upon a valid request, the KME will - respond with an HTTP code 202 ('Accepted'), then it will issue a - separate call (or multiple calls) to the specified `ack_callback_url` + Upon a valid request, the KME should aim to resond without undue delay with + a `202` ('Accepted'), + then it will issue a separate call (or multiple calls) to the specified + `ack_callback_url` endpoint once the keys are actually delivered (or fail to be delivered). - A Code 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. + A `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. required: true @@ -85,33 +100,37 @@ paths: $ref: '#/components/responses/408-extkey' '503': $ref: '#/components/responses/503-extkey' - '555': - $ref: '#/components/responses/503-extkey' /kmapi/v1/ext_keys/void: post: summary: Signal keys as void to external KMS (i.e. discard keys) operationId: post-ext_keys-void + tags: + - ext-keys description: | Pass an 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 those already passed to the KME. - As for `ext_keys`, this method is 'non-blocking'. 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. Any subsequent 'get key with key ID' requests made to the KME - (using ETSI 014) for those keys will be rejected. - - A Code 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. - - If this is called without supplying a `key_ids` array, then all keys - shared between the provided SAEs will be voided (to prevent accidental - key loss, to confirm this action an `all_confirmation` boolean field - must also be passed as true, otherwise a Code 400 error is returned). + 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 + key, and it shall reject any requests to retrieve them using + ETSI GS QKD 014, ETSI GS QKD 004, or otherwise. + + A `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` + + 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). parameters: - $ref: '#/components/parameters/all_confirmation' requestBody: @@ -137,6 +156,8 @@ paths: post: summary: Acknowledge completion of a previous ext_key request operationId: post-ext_keys-ack + tags: + - 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 @@ -267,8 +288,8 @@ components: - no_key_ids_or_confirmation: >- When no key_ids are passed, all keys shared between the SAEs will be voided. If this is the intended action, the - `all_confirmation` field must also be set to true. - Otherwise, please specify key_ids to be voided. + `all_confirmation` field also needs to be set with a value + of `true`. Otherwise, please specify key_ids to be voided. 400-extkey-ack: description: Bad request format response @@ -324,65 +345,78 @@ components: - server_side_general_error: The server encountered a general failure and cannot respond. schemas: - initiator_sae_id: - type: string - description: >- - ID of the SAE that initiated the request to share the key(s) relevant to - the request. - example: encryptor1 - target_sae_id: + ack_callback_url: + description: >- + URL to which acknowledgement(s) should be sent after all or part of the + request completes or fails. type: string - description: ID of target SAE that the initiator SAE wishes to share keys with. - example: encryptor2 + example: https://kme1/kmapi/v1/ext_keys/ack + + ack_container: + title: Acknowledgements container + type: object + required: + - key_ids + - ack_status + - initiator_sae_id + - target_sae_id + properties: + key_ids: + $ref: '#/components/schemas/key_id_container' + ack_status: + $ref: '#/components/schemas/ack_status' + initiator_sae_id: + $ref: '#/components/schemas/initiator_sae_id' + target_sae_id: + $ref: '#/components/schemas/target_sae_id' + message: + $ref: '#/components/schemas/ack_message' + extension: + $ref: '#/components/schemas/extension' - target_sae_ids: + ack_containers: + description: Array of acknowledgement containers 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 - 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. items: - $ref: '#/components/schemas/target_sae_id' + $ref: '#/components/schemas/ack_container' - key_id: - description: 'ID of the key: UUID format.' + ack_message: + title: message + description: Optional further details to expand upon the `ack_status`. type: string - format: uuid - example: 550e8400-e29b-41d4-a716-446655440000 - value: - description: | - Key data encoded by the base64 data encoding scheme specified in IETF - RFC 4648 (October 2006): "The Base16, Base32, and Base64 Data Encodings" - [7] using the alphabet in Table 1 of the RFC. - - Implementations shall ensure that padding used in the base64 data - encoding scheme is never used as key material. This includes the - zero, two, or one `=` padding characters at the end of the final - encoded unit of output where the final quantum of encoding input - is exactly 24 bits, 8 bits, or 16 bits, respectively. - - When non-integer-byte-size keys are used it is essential to - strip any padding bits with value zero that were added (on the - 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 - 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 - of the encoded output or the final character before the first - `=` padding character can include information from padding bits - with value zero that were added when during encoding in the case - of non-integer-byte-size keys.) - - Note that support for non-integer-byte-size keys is optional and - many vendors choose to support only integer byte sizes. + ack_status: + description: Status of acknowledged keys type: string - example: wHHVxRwDJs3/bXd38GHP3oe4svTuRpZS0yCC7x4Ly+s= + enum: + - relayed + - voided + - failed + - key not present + example: relayed + + ext_key_container: + title: Extended key request container + type: object + required: + - keys + - initiator_sae_id + - target_sae_ids + - ack_callback_url + properties: + keys: + $ref: '#/components/schemas/keys' + initiator_sae_id: + $ref: '#/components/schemas/initiator_sae_id' + target_sae_ids: + $ref: '#/components/schemas/target_sae_ids' + ack_callback_url: + $ref: '#/components/schemas/ack_callback_url' + extension_mandatory: + $ref: '#/components/schemas/extension_mandatory' + extension_optional: + $ref: '#/components/schemas/extension_optional' extension: type: object @@ -437,139 +471,122 @@ components: min_version: 2.5 abc_qos_session: 'e73d9abe' - ack_callback_url: - description: >- - URL to which acknowledgement(s) should be sent after all or part of the - request completes or fails. + initiator_sae_id: type: string - example: https://kme1/kmapi/v1/ext_keys/ack - - ack_status: - description: Status of acknowledged keys + description: >- + ID of the SAE that initiated the request to share the key(s) relevant to + the request. + example: encryptor1 + + key_id: + description: 'ID of the key: UUID format.' type: string - enum: - - relayed - - voided - - failed - - key not present - example: relayed + format: uuid + example: 550e8400-e29b-41d4-a716-446655440000 - keys: + key_id_container: type: array - description: Array of keys. + description: Array of key IDs. items: type: object required: - key_id - - value properties: key_id: $ref: '#/components/schemas/key_id' - value: - $ref: '#/components/schemas/value' extension: $ref: '#/components/schemas/extension' - ext_key_container: - title: Extended key request container - type: object - required: - - keys - - initiator_sae_id - - target_sae_ids - - ack_callback_url - properties: - keys: - $ref: '#/components/schemas/keys' - initiator_sae_id: - $ref: '#/components/schemas/initiator_sae_id' - target_sae_ids: - $ref: '#/components/schemas/target_sae_ids' - ack_callback_url: - $ref: '#/components/schemas/ack_callback_url' - extension_mandatory: - $ref: '#/components/schemas/extension_mandatory' - extension_optional: - $ref: '#/components/schemas/extension_optional' - - key_id_container: + key_ids: type: array description: Array of key IDs. + items: + $ref: '#/components/schemas/key_id' + + keys: + type: array + description: Array of keys. items: type: object required: - key_id + - value properties: key_id: $ref: '#/components/schemas/key_id' + value: + $ref: '#/components/schemas/value' extension: $ref: '#/components/schemas/extension' - key_ids: - type: array - description: Array of key IDs. - items: - $ref: '#/components/schemas/key_id' - - void_container: - title: Void request container - type: object - required: - - key_ids - - initiator_sae_id - - target_sae_ids - - ack_callback_url - properties: - key_ids: - $ref: '#/components/schemas/key_ids' - initiator_sae_id: - $ref: '#/components/schemas/initiator_sae_id' - target_sae_ids: - $ref: '#/components/schemas/target_sae_ids' - ack_callback_url: - $ref: '#/components/schemas/ack_callback_url' - extension: - $ref: '#/components/schemas/extension' - - ack_container: - title: Acknowledgements container + message_data: + title: Message data format type: object required: - - key_ids - - ack_status - - initiator_sae_id - - target_sae_id + - message properties: - key_ids: - $ref: '#/components/schemas/key_id_container' - ack_status: - $ref: '#/components/schemas/ack_status' - initiator_sae_id: - $ref: '#/components/schemas/initiator_sae_id' - target_sae_id: - $ref: '#/components/schemas/target_sae_id' message: - $ref: '#/components/schemas/ack_message' - extension: - $ref: '#/components/schemas/extension' + description: Response message + type: string + example: success + details: + description: Array of objects containing details + type: array + items: + type: object - ack_containers: - description: Array of acknowledgement containers + target_sae_id: + type: string + description: ID of target SAE that the initiator SAE wishes to share keys with. + example: encryptor2 + + target_sae_ids: type: array + description: >- + Array of IDs of target SAEs relevant to the request. (In a call to + 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. items: - $ref: '#/components/schemas/ack_container' + $ref: '#/components/schemas/target_sae_id' + + value: + description: | + Key data encoded by the base64 data encoding scheme specified in IETF + RFC 4648 (October 2006): "The Base16, Base32, and Base64 Data Encodings" + [7] using the alphabet in Table 1 of the RFC. + + Implementations shall ensure that padding used in the base64 data + encoding scheme is never used as key material. This includes the + zero, two, or one `=` padding characters at the end of the final + encoded unit of output where the final quantum of encoding input + is exactly 24 bits, 8 bits, or 16 bits, respectively. + + When non-integer-byte-size keys are used it is essential to + strip any padding bits with value zero that were added (on the + 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 + 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 + of the encoded output or the final character before the first + `=` padding character can include information from padding bits + with value zero that were added when during encoding in the case + of non-integer-byte-size keys.) + + Note that support for non-integer-byte-size keys is optional and + many vendors choose to support only integer byte sizes. + type: string + example: wHHVxRwDJs3/bXd38GHP3oe4svTuRpZS0yCC7x4Ly+s= version: type: string description: Supported API version. example: v1 - versions: - type: array - description: Array of supported API versions. - items: - $ref: '#/components/schemas/version' - version_container: title: Version container type: object @@ -581,26 +598,31 @@ components: extension: $ref: '#/components/schemas/extension' - ack_message: - title: message - description: Optional further details to expand upon the `ack_status`. - type: string + versions: + type: array + description: Array of supported API versions. + items: + $ref: '#/components/schemas/version' - message_data: - title: Message data format + void_container: + title: Void request container type: object required: - - message + - key_ids + - initiator_sae_id + - target_sae_ids + - ack_callback_url properties: - message: - description: Response message - type: string - example: success - details: - description: Array of objects containing details - type: array - items: - type: object + key_ids: + $ref: '#/components/schemas/key_ids' + initiator_sae_id: + $ref: '#/components/schemas/initiator_sae_id' + target_sae_ids: + $ref: '#/components/schemas/target_sae_ids' + ack_callback_url: + $ref: '#/components/schemas/ack_callback_url' + extension: + $ref: '#/components/schemas/extension' parameters: all_confirmation: diff --git a/interop-kms_ExtraMarkup.yaml b/interop-kms_ExtraMarkup.yaml new file mode 100644 index 0000000..bad031d --- /dev/null +++ b/interop-kms_ExtraMarkup.yaml @@ -0,0 +1,650 @@ +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: Proposed changes to 0.4.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 +servers: + - url: https://{kme_hostname} + description: Local KME server + variables: + kme_hostname: + default: 127.0.0.1:443 +externalDocs: + description: Work Item description + url: https://portal.etsi.org/webapp/WorkProgram/Report_WorkItem.asp?WKI_ID=63115 +tags: + - name: versions + description: Information about supported API versions + + - name: ext-keys + description: Pass keys to another KME (external keys) + +paths: + /kmapi/versions: + get: + summary: Get supported API versions + operationId: get-versions + tags: + - versions + description: | + Return list of supported ETSI GS QKD 020 API versions. + + When an SAE makes a request to a KME, it should use the most recent + version of the API that the KME and SAE support. + + The SAE can use this end-point to determine which API versions the KME + supports. + responses: + '200': + description: Supported versions + content: + application/json: + schema: + $ref: '#/components/schemas/version_container' + '401': + $ref: '#/components/responses/401-extkey' + '503': + $ref: '#/components/responses/503-extkey' + + /kmapi/v1/ext_keys: + post: + summary: Transfer keys to external KMS + operationId: post-ext_keys + tags: + - ext-keys + description: | + Pass an 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` ('Accepted'), + then it will issue a separate call (or multiple calls) to the specified + `ack_callback_url` + endpoint once the keys are actually delivered (or fail to be delivered). + + A `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. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ext_key_container' + responses: + '202': + $ref: '#/components/responses/202-extkey' + '400': + $ref: '#/components/responses/400-extkey' + '401': + $ref: '#/components/responses/401-extkey' + '408': + $ref: '#/components/responses/408-extkey' + '503': + $ref: '#/components/responses/503-extkey' + + /kmapi/v1/ext_keys/void: + post: + summary: Signal keys as void to external KMS (i.e. discard keys) + operationId: post-ext_keys-void + tags: + - ext-keys + description: | + Pass an 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 + 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 + key, and it shall reject any requests to retrieve them using + ETSI GS QKD 014, ETSI GS QKD 004, or otherwise. + + A `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` + + 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). + parameters: + - $ref: '#/components/parameters/all_confirmation' + requestBody: + description: Void request container + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/void_container' + responses: + '202': + $ref: '#/components/responses/202-extkey' + '400': + $ref: '#/components/responses/400-extkey-void' + '401': + $ref: '#/components/responses/401-extkey' + '408': + $ref: '#/components/responses/408-extkey' + '503': + $ref: '#/components/responses/503-extkey' + + /kmapi/v1/ext_keys/ack: + post: + summary: Acknowledge completion of a previous ext_key request + operationId: post-ext_keys-ack + tags: + - 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 + 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`. + + - `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 + initiator requested multiple targets, the acknowledgements for each + target are separate acknowledgement containers (since the status for + each target may be different). + + - `voided` indicates the KME has successfully voided the specified keys + 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 + 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. + + - `key not present` indicates that the specified keys could not be found + by the KME. + + 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, + 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 + keys. A single container should be used for each target SAE ID. + + Extension fields may also be optionally included (which could be, e.g. + metadata for each key to indicate its routing information from the + remote KMS). If such extensions are included, the extensions should be + 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. + requestBody: + description: Acknowledgements containers + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ack_containers' + responses: + '200': + $ref: '#/components/responses/200-ack-response' + '400': + $ref: '#/components/responses/400-extkey-ack' + '401': + $ref: '#/components/responses/401-extkey' + '503': + $ref: '#/components/responses/503-extkey' + +components: + responses: + 200-ack-response: + description: Successful response + + 202-extkey: + description: Request accepted response + + 400-extkey: + description: Bad request format response + content: + application/json: + schema: + $ref: '#/components/schemas/message_data' + examples: + missing_parameters: + value: + message: missing parameters + details: + - missing_parameters: required parameters are missing from the API call + unknown_sae_id: + value: + message: key routing error + details: + - target_sae_id_not_recognized: KME associated with a target SAE ID is not known. + no_known_route: + value: + message: key routing error + details: + - no_known_route: KME does not know a route to deliver to target SAE ID. + no_passback_allowed: + value: + message: key routing error + details: + - invalid_routing: >- + Routing this key to target SAE ID requires directly + passing it back to the calling KME, which is invalid. + insufficient_key_material: + value: + message: insufficient key material + details: + - insufficient_key_material: Insufficient key material available to deliver key. + + 400-extkey-void: + description: Bad request format response + content: + application/json: + schema: + $ref: '#/components/schemas/message_data' + examples: + failed: + value: + message: void request not understood + details: + - key_voiding_error: KME cannot parse the submitted void request. + key_not_present: + value: + message: key not present + details: + - key_not_present: The requested key ID(s) are not available to be voided. + no_key_ids_or_confirmation: + value: + message: no_key_ids_or_confirmation + details: + - no_key_ids_or_confirmation: >- + When no key_ids are passed, all keys shared between the + SAEs will be voided. If this is the intended action, the + `all_confirmation` field also needs to be set with a value + of `true`. Otherwise, please specify key_ids to be voided. + + 400-extkey-ack: + description: Bad request format response + content: + application/json: + schema: + $ref: '#/components/schemas/message_data' + examples: + not_understood: + value: + message: ack not understood + details: + - ack_not_understood: KME cannot parse the submitted acknowledgement. + key_not_present: + value: + message: key not present + details: + - key_not_present: The acknowledged key ID(s) are not known to this KME. + + 401-extkey: + description: Unauthorized response + content: + application/json: + schema: + $ref: '#/components/schemas/message_data' + example: + message: unauthorized + details: + - unauthorized: User-supplied certificate is invalid. + + 408-extkey: + description: Timeout response + content: + application/json: + schema: + $ref: '#/components/schemas/message_data' + example: + message: timeout + details: + - timeout: >- + No response received from KME to ext_keys request in + sufficient time. + + 503-extkey: + description: Error of server side response + content: + application/json: + schema: + $ref: '#/components/schemas/message_data' + example: + message: server side general error + details: + - server_side_general_error: The server encountered a general failure and cannot respond. + + schemas: + + ack_callback_url: + description: >- + URL to which acknowledgement(s) should be sent after all or part of the + request completes or fails. + type: string + example: https://kme1/kmapi/v1/ext_keys/ack + + ack_container: + title: Acknowledgements container + type: object + required: + - key_ids + - ack_status + - initiator_sae_id + - target_sae_id + properties: + key_ids: + $ref: '#/components/schemas/key_id_container' + ack_status: + $ref: '#/components/schemas/ack_status' + initiator_sae_id: + $ref: '#/components/schemas/initiator_sae_id' + target_sae_id: + $ref: '#/components/schemas/target_sae_id' + message: + $ref: '#/components/schemas/ack_message' + extension: + $ref: '#/components/schemas/extension' + + ack_containers: + description: Array of acknowledgement containers + type: array + items: + $ref: '#/components/schemas/ack_container' + + ack_message: + title: message + description: Optional further details to expand upon the `ack_status`. + type: string + + ack_status: + description: Status of acknowledged keys + type: string + enum: + - relayed + - voided + - failed + - key not present + example: relayed + + ext_key_container: + title: Extended key request container + type: object + required: + - keys + - initiator_sae_id + - target_sae_ids + - ack_callback_url + properties: + keys: + $ref: '#/components/schemas/keys' + initiator_sae_id: + $ref: '#/components/schemas/initiator_sae_id' + target_sae_ids: + $ref: '#/components/schemas/target_sae_ids' + ack_callback_url: + $ref: '#/components/schemas/ack_callback_url' + extension_mandatory: + $ref: '#/components/schemas/extension_mandatory' + extension_optional: + $ref: '#/components/schemas/extension_optional' + + extension: + type: object + additionalProperties: + type: object + additionalProperties: true + description: >- + Reserved for future use. Dictionary of objects. Objects may be of any + type and custom extensions should be named starting with a vendor prefix + followed by an underscore. + example: + abc_extension1: 'Some string' + abc_extension2: + property1: 10111 + property2: 'Some text' + property3: + subprop1: 21 + subprop2: true + + extension_mandatory: + type: object + additionalProperties: + type: object + 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. + example: + abc_route_type: 'direct' + abc_method: + hybrid_keys: true + primary: 'qkd' + secondary: 'pqc' + + extension_optional: + type: object + additionalProperties: + type: object + additionalProperties: true + 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. + example: + abc_module_type: + vendor: 'Company ABC' + protocol: 'BB84' + min_version: 2.5 + abc_qos_session: 'e73d9abe' + + initiator_sae_id: + type: string + description: >- + ID of the SAE that initiated the request to share the key(s) relevant to + the request. + example: encryptor1 + + key_id: + description: 'ID of the key: UUID format.' + type: string + format: uuid + example: 550e8400-e29b-41d4-a716-446655440000 + + key_id_container: + type: array + description: Array of key IDs. + items: + type: object + required: + - key_id + properties: + key_id: + $ref: '#/components/schemas/key_id' + extension: + $ref: '#/components/schemas/extension' + + key_ids: + type: array + description: Array of key IDs. + items: + $ref: '#/components/schemas/key_id' + + keys: + type: array + description: Array of keys. + items: + type: object + required: + - key_id + - value + properties: + key_id: + $ref: '#/components/schemas/key_id' + value: + $ref: '#/components/schemas/value' + extension: + $ref: '#/components/schemas/extension' + + message_data: + title: Message data format + type: object + required: + - message + properties: + message: + description: Response message + type: string + example: success + details: + description: Array of objects containing details + type: array + items: + type: object + + target_sae_id: + type: string + description: ID of target SAE that the initiator SAE wishes to share keys with. + example: encryptor2 + + target_sae_ids: + type: array + description: >- + Array of IDs of target SAEs relevant to the request. (In a call to + 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. + items: + $ref: '#/components/schemas/target_sae_id' + + value: + description: | + Key data encoded by the base64 data encoding scheme specified in IETF + RFC 4648 (October 2006): "The Base16, Base32, and Base64 Data Encodings" + [7] using the alphabet in Table 1 of the RFC. + + Implementations shall ensure that padding used in the base64 data + encoding scheme is never used as key material. This includes the + zero, two, or one `=` padding characters at the end of the final + encoded unit of output where the final quantum of encoding input + is exactly 24 bits, 8 bits, or 16 bits, respectively. + + When non-integer-byte-size keys are used it is essential to + strip any padding bits with value zero that were added (on the + 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 + 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 + of the encoded output or the final character before the first + `=` padding character can include information from padding bits + with value zero that were added when during encoding in the case + of non-integer-byte-size keys.) + + Note that support for non-integer-byte-size keys is optional and + many vendors choose to support only integer byte sizes. + type: string + example: wHHVxRwDJs3/bXd38GHP3oe4svTuRpZS0yCC7x4Ly+s= + + version: + type: string + description: Supported API version. + example: v1 + + version_container: + title: Version container + type: object + required: + - versions + properties: + versions: + $ref: '#/components/schemas/versions' + extension: + $ref: '#/components/schemas/extension' + + versions: + type: array + description: Array of supported API versions. + items: + $ref: '#/components/schemas/version' + + void_container: + title: Void request container + type: object + required: + - key_ids + - initiator_sae_id + - target_sae_ids + - ack_callback_url + properties: + key_ids: + $ref: '#/components/schemas/key_ids' + initiator_sae_id: + $ref: '#/components/schemas/initiator_sae_id' + target_sae_ids: + $ref: '#/components/schemas/target_sae_ids' + ack_callback_url: + $ref: '#/components/schemas/ack_callback_url' + extension: + $ref: '#/components/schemas/extension' + + parameters: + all_confirmation: + name: all_confirmation + in: query + required: false + description: >- + Confirmation flag used to confirm deletion of all keys when no key IDs + are specified. + schema: + type: boolean + examples: + 'true': + value: true + summary: Confirmation + + securitySchemes: + mutualTLS: + type: http + scheme: mutual + description: >- + Mutual TLS authentication using certificates, TLSv1.3 (or later). + NOTE - OpenAPI 3.1.0 introduces better support for describing mTLS. +security: + - mutualTLS: [] -- GitLab From 94a7f6477123f7f9bbbe07a8fc6aa44ebf05fee9 Mon Sep 17 00:00:00 2001 From: wardmart Date: Tue, 3 Jun 2025 08:03:19 +0000 Subject: [PATCH 2/2] Changes for V0.5.1 --- interop-kms.yaml | 80 +++++++++++++++++------------- interop-kms_ExtraMarkup.yaml | 95 ++++++++++++++++++++---------------- 2 files changed, 101 insertions(+), 74 deletions(-) diff --git a/interop-kms.yaml b/interop-kms.yaml index b9a148e..096bd64 100644 --- a/interop-kms.yaml +++ b/interop-kms.yaml @@ -1,3 +1,5 @@ +# 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 @@ -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 @@ -50,7 +52,7 @@ paths: supports. responses: '200': - description: Supported versions + description: Successful response content: application/json: schema: @@ -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` @@ -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: @@ -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. @@ -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: @@ -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). @@ -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. @@ -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 @@ -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 @@ -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: @@ -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: @@ -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: @@ -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' @@ -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' diff --git a/interop-kms_ExtraMarkup.yaml b/interop-kms_ExtraMarkup.yaml index bad031d..464da5a 100644 --- a/interop-kms_ExtraMarkup.yaml +++ b/interop-kms_ExtraMarkup.yaml @@ -1,4 +1,5 @@ -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: | @@ -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 @@ -50,7 +51,7 @@ paths: supports. responses: '200': - description: Supported versions + description: Successful response content: application/json: schema: @@ -67,23 +68,25 @@ 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 - a `202` ('Accepted'), + 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` + `ack_callback_url` endpoint once the keys are actually delivered (or fail to be delivered). - A `400` error will be returned + A `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` extended key request container. required: true content: application/json: @@ -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` + 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 + `ack_callback_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` code should be returned + A `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` + `ack_callback_url` 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). + `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` code. parameters: - $ref: '#/components/parameters/all_confirmation' requestBody: @@ -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` 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). @@ -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` 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. @@ -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` 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 @@ -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` code, otherwise an Error Code + shall be returned including details of the error. requestBody: description: Acknowledgements containers required: true @@ -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` request in sufficient time. 503-extkey: @@ -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`. type: string ack_status: @@ -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` 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: @@ -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` 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' @@ -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` 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' -- GitLab