KMS to SDN Agent API (2.1.0)
Download OpenAPI specification:
Messages the KMS sends to the SDN
Get status of link
When an application queries the KMS for the status via ETSI GS QKD 014 /status message, the KMS has to provide the information how many keys are available on the link, but this involves remote peers, therefore the message is relied to the SDN to solve.
Authorizations:
Request Body schema: application/jsonrequired
| master_sae_id required | string |
| slave_sae_id required | string |
Responses
Request samples
- Payload
{- "master_sae_id": "7184f8e9-4503-45d6-a399-afb9c0e61d06",
- "slave_sae_id": "9dd59892-db33-4db5-8e39-76b4a44e4aea"
}Response samples
- 200
- 400
- 500
{- "source_KME_ID": "string",
- "target_KME_ID": "string",
- "key_size": 0,
- "stored_key_count": 0,
- "max_key_count": 0,
- "max_key_per_request": 0,
- "max_key_size": 0,
- "min_key_size": 0,
- "max_SAE_ID_count": 0,
- "status_extension": { }
}Post new link registration
When a source APP registers with a KMS, the KMS sends the parameters supplied by the APP to the SDN. The SDN configures a path between the source and destination, verifies the QoS and returns the key stream id and adjacent node information
Authorizations:
Request Body schema: application/jsonrequired
| source required | string URI or UUID of the source APP |
| destination required | Array of strings[ items non-empty ] |
required | object (qos-data) QoS requested by the KMS, either it is an etsi_004 or etsi_014 request. |
required | Array of objects[ items non-empty ] Current performance indicators of this instance. Relevant for path selection at SDN Controller. KMS reports current values of all direct links, as it does not know yet the next hop to take. |
object Optional additional fields. "multipath" are defined. In case additional optional features are available, create new "key:value" pair in object. |
Responses
Request samples
- Payload
{- "source": "172.0.10.101:5683",
- "destination": [
- "172.0.10.102:5683"
], - "qos_request": {
- "type": "etsi_014",
- "etsi_014": {
- "number": 1,
- "size": 256,
- "extensions": [
- {
- "example_key": "example_value"
}
]
}, - "etsi_004": {
- "key_chunk_size": 32,
- "max_bps": 128,
- "min_bps": 64,
- "jitter": 1,
- "priority": 3,
- "timeout": 50,
- "ttl": 5,
- "metadata_mimetype": "application/json"
}
}, - "performance": [
- {
- "link_id": "02a2c2f0-9521-47cc-9615-2e177adeebac",
- "current_kpi": {
- "timestamp": "2024-08-27T17:41:28Z",
- "delta_t": 10000,
- "IKR": 50,
- "EXKR": 50,
- "SKR": 500,
- "KAV": 400
}
}
], - "options": {
- "multipath": true
}
}Response samples
- 201
- 400
- 500
{- "key_stream_id": "4eb81a5c-031f-4d1f-881d-309bee44fc20",
- "next_node_info": [
- "172.0.10.103:5683",
- "172.0.10.104:5683"
], - "qos": {
- "max_bps": 0,
- "min_bps": 128,
- "jitter": 2,
- "priority": 0,
- "ttl": 1
}
}Update link status by destination APP
When a destination APP registers with a KMS, the KMS informs the SDN of the destination APP registration. This indicates, that the path was closed.
Authorizations:
Request Body schema: application/jsonrequired
| key_stream_id required | string <uuid> |
| destination required | string Of type UUID or URI |
Responses
Request samples
- Payload
{- "key_stream_id": "4eb81a5c-031f-4d1f-881d-309bee44fc20",
- "destination": "string"
}Response samples
- 400
- 500
{- "type": "string",
- "title": "string",
- "status": 0,
- "detail": "string"
}Delete key stream
If the ETSI 004 application closes a key stream, this is reported to the SDN
Authorizations:
path Parameters
| key_stream_id required | string <uuid> |
Responses
Response samples
- 400
- 500
{- "type": "string",
- "title": "string",
- "status": 0,
- "detail": "string"
}Post KMS added to network
Inform the SDN of a new KMS that has been added to the network. If local instance has information about connected QKD devices or links, specify in request body.
Authorizations:
Request Body schema: application/jsonrequired
| kms_id required | string <uuid> |
required | object |
| qkd_device_ids | Array of strings <uuid> [ items <uuid > ] If known connected QKD devices |
| link_ids | Array of strings <uuid> [ items <uuid > ] If known connected links |
Responses
Request samples
- Payload
{- "kms_id": "ad24d5e1-a0b8-4fd6-a5fa-b8bed73f67c5",
- "model": {
- "device_vendor": "AIT",
- "device_model": "AURORA KMS",
- "device_version": "1.0.0"
}, - "qkd_device_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "link_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}Response samples
- 400
- 500
{- "type": "string",
- "title": "string",
- "status": 0,
- "detail": "string"
}Update KMS status
Inform the SDN of when the KMS's status changes, e.g. the KMS goes into maintenance mode
Authorizations:
Request Body schema: application/jsonrequired
| state required | string |
| reason required | string |
Responses
Request samples
- Payload
{- "state": "stopped",
- "reason": "maintenance"
}Response samples
- 400
- 500
{- "type": "string",
- "title": "string",
- "status": 0,
- "detail": "string"
}Update event at KMS
Inform the SDN of an event
Authorizations:
Request Body schema: application/jsonrequired
| level required | string Enum: "debug" "info" "warning" "error" "critical" |
| code | integer |
| reason required | string |
Responses
Request samples
- Payload
{- "level": "debug",
- "code": 14,
- "reason": "stopped"
}Response samples
- 400
- 500
{- "type": "string",
- "title": "string",
- "status": 0,
- "detail": "string"
}