Editorial changes and extra markup for Word (882469e1) · Commits · QKD - Quantum Key Distribution / QKD Interoperable KMS API

LICENSE

+1 −1

Original line number	Diff line number	Diff line
		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:

README.md

+1 −1

Original line number	Diff line number	Diff line
		@@ -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

interop-kms.yaml

+207 −185

Original line number	Diff line number	Diff line
		@@ -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

		ack_callback_url:
		description: >-
		ID of the SAE that initiated the request to share the key(s) relevant to
		the request.
		example: encryptor1
		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:
		type: string
		description: ID of target SAE that the initiator SAE wishes to share keys with.
		example: encryptor2
		$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,60 +471,18 @@ 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.
		type: string
		example: https://kme1/kmapi/v1/ext_keys/ack

		ack_status:
		description: Status of acknowledged keys
		initiator_sae_id:
		type: string
		enum:
		- relayed
		- voided
		- failed
		- key not present
		example: relayed
		description: >-
		ID of the SAE that initiated the request to share the key(s) relevant to
		the request.
		example: encryptor1

		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'

		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'
		description: 'ID of the key: UUID format.'
		type: string
		format: uuid
		example: 550e8400-e29b-41d4-a716-446655440000

		key_id_container:
		type: array
		@@ -511,65 +503,90 @@ components:
		items:
		$ref: '#/components/schemas/key_id'

		void_container:
		title: Void request container
		keys:
		type: array
		description: Array of keys.
		items:
		type: object
		required:
		- key_ids
		- initiator_sae_id
		- target_sae_ids
		- ack_callback_url
		- key_id
		- value
		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'
		key_id:
		$ref: '#/components/schemas/key_id'
		value:
		$ref: '#/components/schemas/value'
		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:

interop-kms_ExtraMarkup.yaml

0 → 100644

+650 −0

File added.

Preview size limit exceeded, changes collapsed.