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.
If this method is called without specifying an `ack_callback_url`, it will execute in 'blocking mode', whereby the KME will only respond once the keys have been relayed to the KME corresponding to the `target_sae_id`. If this method is called with an `ack_callback_url` specified, then it will execute in 'non-blocking mode', whereby the KME will respond quickly with an HTTP code 202 ('Accepted'), then it will issue a separate call (or multiple calls) to the `ack_callback_url` endpoint once the keys are actually delivered (or fail to be delivered).
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` endpoint once the keys are actually delivered (or fail to be delivered).
When 'non-blocking mode' is requested, the server shall respond with Code 202 if it accepts the request.
When operating in 'blocking mode', there will be a delay while the remote KMS relays the key(s), then a Code 200 response will be returned. This response includes a status field which may have either the value `success` or `partial_success`. `success` indicates that all keys were delivered to the destination KME. An array of acknowledgement containers may be optionally returned that includes extension fields (which could be, e.g. metadata for each key to indicate its routing information from the remote KMS). If such containers are returned, the extensions should be handled by the requesting KMS (e.g. to keep the provided metadata with each key so it can be relayed to the initiator SAE). If one or more key failed to be relayed successfully the KME shall respond with a value of `partial_success` in the status field and the KME shall return an array of acknowledgement containers that includes the status of each key.
parameters:
-$ref:'#/components/parameters/initiator_sae_id'
-$ref:'#/components/parameters/target_sae_id'
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.
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 blocks when the `ack_callback_url` field is omitted and operates in non-blocking mode when the `ack_callback_url` field is supplied. 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).
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).
Pass one or more key acknowledgement containers 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 `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.
description:ID of target SAE that the initiator SAE wishes to share keys with (single target only; for sharing to multiple targets, specify additional_target_sae_ids in body).
description:ID of target SAE that the initiator SAE wishes to share keys with.
example:encryptor2
additional_target_sae_ids:
target_sae_ids:
type:array
description:Array of IDs of target SAEs. It is used for specifying two or more target SAEs to share identical keys. The maximum number of IDs is defined as max_sae_id_count in Status data format.
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.
