KMS to SDN Agent API - SDN server (2.2.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:
query Parameters
| master_sae_id required | string Example: master_sae_id=7184f8e9-4503-45d6-a399-afb9c0e61d06 Master SAE ID as per ETSI GS QKD 014 |
| slave_sae_id required | string Example: slave_sae_id=9dd59892-db33-4db5-8e39-76b4a44e4aea Slave SAE ID as per ETSI GS QKD 014 |
Responses
Response samples
- 200
- 400
- 500
{- "source_kms_id": "string",
- "target_kms_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 ID 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": "application_ID_1",
- "destination": [
- "application_ID_2"
], - "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": [
- "kms-1.net:5683",
- "kms-3.net:5683"
], - "qos": {
- "max_bps": 0,
- "min_bps": 128,
- "jitter": 2,
- "priority": 0,
- "ttl": 1
}, - "peer_application_info": [
- {
- "kms_id": "string",
- "application_ids": [
- "string"
]
}
]
}Update link status by destination APP
When the registered application at POST had keys successfully established, the POST is sent by the destination KMS. This indicates, that the path was closed.
Authorizations:
Request Body schema: application/jsonrequired
| key_stream_id required | string <uuid> Unique ID, corresponds to the ETSI 004 Key Stream ID parameter or identifies an ETSI 014 forwarding path |
| destination required | Array of strings[ items non-empty ] URI or ID of the destination APP, multiple in case of group key. |
Responses
Request samples
- Payload
{- "key_stream_id": "4eb81a5c-031f-4d1f-881d-309bee44fc20",
- "destination": [
- "application_ID_3a",
- "application_ID_3b"
]
}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> Unique ID, corresponds to the ETSI 004 Key Stream ID parameter or identifies an ETSI 014 forwarding path |
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 |
| 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"
}, - "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"
}