Changes for key-deliv.yaml: 525 added lines, 0 removed lines.
Original line number
Diff line number
Diff line
# Copyright 2023 ETSI
# Licensed under the BSD-3 Clause (https://forge.etsi.org/legal-matters)
openapi:'3.0.3'
info:
title:Draft ETSI GS QKD 014 - Protocol and data format of REST-based key delivery for QKD
description:|
The present document describes a communication protocol and data format for a quantum key distribution (QKD) network to supply cryptographic keys to an application. It is intended to allow interoperability of equipment from different vendors. 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.
Quantum key distribution (QKD) networks connect nodes using QKD links for the generation of cryptographic keys.
Applications need to be able to request key material from QKD Systems and their associated Key Management Systems (KMSs).
This document defines a key delivery specification to ensure interoperability between QKD networks, equipment, and applications offered by different vendors.
The Application Programming Interface (API) defined in this document utilizes a REST-based approach.
This API operates over the HTTPS protocol and encodes data in the JSON format, allowing the secure delivery of block keys with key IDs to applications.
REST-based APIs are popular across various application domains as a result of their simplicity.
Indeed, various software libraries are available off-the-shelf to implement REST-based API interactions, and for parsing JSON data.
-name:Connection Specification
description:|
The common specifications for the Key Delivery API are as follows:
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.
-name:Protocol Specification
description:|
The list of available API methods shall be as follows.
paths:
/kdapi/versions:
get:
summary:'GetsupportedAPIversions'
operationId:get-versions
tags:
-'ProtocolSpecification'
description:|
Returns list of supported ETSI GS QKD 014 API versions.
When an SAE makes a request to a KME, it should always 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.
Note that this endpoint was introduced in v2 (ADD ETSI VERSION NUMBER HERE ONCE FINALISED).
Thus, if an SAE does not receive a response from a KME using this call, it should use v1 (i.e. ETSI GS QKD 014 V1.1.1).
If both `initiator_sae_id` and `target_sae_id` are specified in the request body, a single status container is returned containing information on keys available to be requested by the initiator SAE for the specified target SAE.
If only `initiator_sae_id` is specified in the request body, a status container will be returned for each link where the calling SAE is the specified initiator SAE.
If only `target_sae_id` is specified in the request body, a status container will be returned for each link where the target SAE is the specified target SAE.
If neither `initiator_sae_id` nor `target_sae_id` are specified, an Error Code 400 is returned.
requestBody:
description:Link status request.
content:
application/json:
schema:
$ref:'#/components/schemas/link_status_request'
responses:
'200':
description:Array of link statuses
content:
application/json:
schema:
$ref:'#/components/schemas/array_link_status'
'400':
$ref:'#/components/responses/400'
'401':
$ref:'#/components/responses/401'
'503':
$ref:'#/components/responses/503'
/kdapi/v2/keys:
post:
summary:'Getkey'
operationId:post-v2-keys
tags:
-'ProtocolSpecification'
description:|
Returns Key container data from the KME to the calling initiator SAE.
Key container data contains one or more keys. The calling initiator SAE may supply Key request data to specify the requirement on Key container data. The target SAE specified by the target_sae_id parameter may subsequently request matching keys from a remote KME using key_id identifiers from the returned Key container.
requestBody:
description:Key request.
content:
application/json:
schema:
$ref:'#/components/schemas/key_request'
responses:
'200':
$ref:'#/components/responses/200-getkey'
'400':
$ref:'#/components/responses/400'
'401':
$ref:'#/components/responses/401'
'503':
$ref:'#/components/responses/503'
/kdapi/v2/keys_with_id:
post:
summary:'GetkeywithkeyID'
operationId:post-v2-keys_with_id
tags:
-'ProtocolSpecification'
description:|
Returns 'Key container' from the KME to the calling target SAE.
Key container contains keys matching those previously delivered to a remote initiator SAE based on the Key IDs supplied from the remote initiator SAE in response to its call to Get key. The KME shall reject the request with a 401 HTTP status code if the SAE ID of the requestor was not an SAE ID supplied to the "Get key" method each time it was called resulting in the return of any of the Key IDs being requested.
# NOTE: the descriptions here don't get used for parameters in Swagger (but do in redocly)
kme_id:
type:string
example:kme1
description:KME ID of the KME
initiator_kme_id:
type:string
example:kme1
description:KME ID of the KME
target_kme_id:
type:string
example:kme2
description:KME ID of the target KME
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:
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 that 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.