8. QKDLite Scripts API Reference¶

This section describes the various key management commands supported by the QKDLite Scripts. QKDLite Scripts uses the QKDLite Utility to perform key management operations at a higher level than QKDLite Utility.

8.1. Types of QKDLite Scripts¶

There are 3 types of scripts:

Local scripts for the user to invoke key management activities locally on one QKDLite node. Local scripts have filenames that do not begin with replicate_ nor cron_.
Replication scripts for the user to invoke key management activities locally on one QKDLite and replicate these key management activities to another QKDLite node. Replication scripts have filenames that begin with replicate_.
Cron scripts for automation by job schedulers to invoke key management activities on a periodic time interval. Cron scripts can invoke local scripts or replication scripts. Cron scripts have filenames that begin with cron_.

Note

You can use crontab -e to enter new cron jobs in user context, use crontab -l to list currently configured cron jobs. An example to have a cron job execute every 10 minutes is as follows:
```
*/10 * * * * cd /home/pqcee/QKDLite && /bin/bash /home/pqcee/QKDLite/cron_maintain_min_num_keys.sh NicholasKey 10 2>&1 | logger -t cron_maintain_key
```

8.2. Script Error Codes¶

QKDLite Scripts are designed to perform workflow execution across multiple QKDLite nodes. As such, all scripts will return a code to the caller to provide information on execution status. Scripts will return one of the following codes to the caller:

0 : Script completed successfully.
1 : Script failed at initialisation. This is likely due to improper setup of environment variables.
2 : Script failed at performing key management task. Check local syslog for specific error code caused by HSM or QKD appliance for further troubleshooting.
4 : Script failed at performing replication activity. Check both local syslog and remote syslog for specific error codes for further troubleshooting.
255 : Script failed to establish ssh connection to a remote QKDLite node.

8.3. Logging Approach¶

All scripts that perform important actions in key management workflows will log the activity to the local syslog in the same machine that QKDLite is deployed on. The format of the Syslog message will conform to the newer RFC5424 standard.

If you wish to view the messages logged to your local syslog, you can use a cat or tail command on the syslog log file. The syslog location for various Linux distros are as follows:

Debian and Ubuntu: /var/log/syslog
Red Hat and CentOS: /var/log/messages

8.4. Choice of Syslog Facility and Priority Values¶

Every syslog message must define a pair of facility and priority values.

“Local use 0 (local0)” will be used in all syslog messages generated by QKDLite Scripts.

The following priority values will be used according to the type of syslog message generated by the scripts. The priority numerical codes with associated use cases are as follows:

1: “Alert: action must be taken immediately”. The scenarios for this priority level involve events that result from a failure from the HSM or from the QKD appliance. The scenarios that invoke a Priority 1 syslog message include:
- HSM or QKD appliance returned an error code during the key management operation.
- Connection to next QKDLite site cannot be established.
- Next QKDLite site returned an error code.
6: “Informational: informational messages”. The scenarios for this priority level involve key management events that complete successfully without errors. The scenarios that invoke a Priority 6 syslog message include:
- Successful completion of key management operation with no errors returned from HSM nor QKD appliance.
- Successful completion of key management activity with no errors returned from next QKDLite site.

8.5. Scope of Information Captured in Logs¶

In each log, the following information will be included:

Username logged in
Key management operation attempted
(Optional) Key ID
HSM Slot number
(Optional) KME IP
(Optional) Target SAE

If the operation was unsuccessful, the additional information will be included:

Error code from HSM or QKD appliance via QKDLite Utility.
Error code from QKDLite Script.

8.6. QKDLite Script Commands¶

Note

Scripts are invoked by preceding the script name with ./, followed by the parameters given in order of listing. For example:

./create_key.py QKDLITE_B ETSI

Additional information about the nomenclature of parameters, devices and nodes referred to below can be found at API Terms and Definitions.

8.6.1. Local Scripts¶

create_key.py [remote_qnode] [keyID] (keyLabel)

Parameters:

Name	Input type	Description
`remote_qnode`	string	Name of the node where the secret key will be shared to.
`keyID`	string	The identifier for the secret key.
`keyLabel` (optional)	string	The unique identifier for the secret key, generated by the QKD appliance.

Description

Invokes creation of a quantum secret key.

Supplying remote_qnode and keyID arguments will invoke QKD KME (associated with the localhost QKDLite node) to perform QKD protocol with a remote QKD SAE (associated with the remote_qnode QKDLite node) and create a new quantum secret key with a new keyLabel. This new quantum secret key will only be inserted into the HSM associated with the localhost QKDLite node. It will have identifiers keyID and keyLabel.

Supplying all remote_qnode, keyID and keyLabel arguments will invoke QKD KME (associated with the localhost QKDLite node) to retrieve a previously-generated quantum secret key associated with keyLabel. This quantum secret key will be inserted into HSM associated with the localhost QKDLite node. It will have identifiers keyID and keyLabel.

Output

If successful, the output returns in the following format:

<keyID>,<generated keyLabel of new key>
0

If unsuccessful due to incorrect input, there will be no output, indicating no key created.

If unsuccessful due to QKD2HSM script failure, the non-zero error code from the QKD2HSM script will be returned.

delete_keys.py [keyID] (keyLabel)
Parameters:

Name

Input type

Description

keyID

string

The identifier for the secret key.

keyLabel (optional)

string

The unique identifier for the secret key, generated by the QKD appliance.

Description
Invokes deletion of the quantum secret key(s) with the associated keyID and keyLabel at the localhost QKDLite node.

Supplying a keyID argument will delete all keys associated with the provided keyID at the localhost QKDLite node.

Supplying both keyID and keyLabel arguments will delete one key associated with the keyID and keyLabel at the localhost QKDLite node.

Output
If one or more keys were deleted successfully, the output returns in the following format:

<keyID_1>,<keyLabel_1> <keyID_2>,<keyLabel_2> ... <keyID_N>,<keyLabel_N> 0

If no keys of supplied keyID are found, the output will return:

0

If unsuccessful due to incorrect input, there will be no output, indicating no key(s) deleted.

If unsuccessful due to QKD2HSM script failure, the non-zero error code from the QKD2HSM script will be returned.
list_keys.py (keyID)
Parameters:

Name

Input type

Description

keyID (optional)

string

The identifier for the secret key.

Description
Generates a list of all keys at the localhost QKDLite node. Note that this script is assumed to be executed locally and remotely via cron jobs, so the output is designed to facilitate processing by scripts rather than by a human operator.

Supplying no arguments will invoke a list of all quantum secret key identifiers at the localhost QKDLite node.

Supplying a keyID argument will invoke a list of quantum secret key identifiers with a matching keyID value at the localhost QKDLite node.

Output
If successful and more than one key is listed, the output returns in the following format:

<keyID_1>,<keyLabel_1> <keyID_2>,<keyLabel_2> ... <keyID_N>,<keyLabel_N> 0

If there are no keys in the localhost QKDLite node or no keys match the given keyID, the output will return:

0

If unsuccessful due to incorrect input, there will be no output, indicating no keys listed.

If unsuccessful due to QKD2HSM script failure, the non-zero error code from the QKD2HSM script will be returned.

8.6.2. Replication Scripts¶

replicate_create_key.py [remote_qnode] [keyID]
Parameters:

Name

Input type

Description

remote_qnode

string

Name of the node where the secret key will be replicated to.

keyID

string

The identifier for the secret key.

Description
Invokes creation of one secret quantum key at the localhost QKDLite node and replicate this key at the indicated remote QKDLite node.

Supplying remote_qnode and keyID arguments will invoke creation of a quantum secret key in the localhost QKDLite node. This secret key will be replicated to the indicated remote QKDLite node remote_qnode and inserted into its connected HSM with the associated keyLabel.

Note that if local creation is successful but replication is unsuccessful, the newly created quantum secret key will be deleted locally.

Output
If successful, the output returns in the following format:

Creating key locally on <localhost QKDLite node>... <keyID>,<keyLabel> Replicating key on remote QKDLite node <remote QKDLite node>... <keyID>,<keyLabel>

If local key creation is successful but replication is unsuccessful, the output will be as follows:

Creating key locally on <localhost QKDLite node>... <keyID>,<keyLabel> Attempt to undo key creation on localhost QKDLite node by deleting key... Deleting keys locally on <remote QKDLite node>... <keyID>,<keyLabel>

If unsuccessful due to an SSH error, an error message will indicate so.

If unsuccessful due to incorrect input or other reasons, there will be no output, indicating no key replicated.

replicate_delete_keys.py [remote_qnode] [keyID] (keyLabel) (waitTime)

Parameters:

Name	Input type	Description
`remote_qnode`	string	Name of the node where the secret key(s) will be deleted.
`keyID`	string	The identifier for the secret key(s).
`keyLabel` (optional)	string	The unique identifier for the secret key, generated by the QKD appliance.
`waitTime` (optional)	int	Time in seconds that this script will delay its execution by.

Description

Deletes the specified quantum secret keys both at the localhost QKDLite node and at the remote QKDLite node.

Supplying remote_qnode and keyID arguments will delete all keys associated with the provided keyID both at the localhost QKDLite node and at the remote QKDLite node remote_qnode. This command executes immediately.

Supplying remote_qnode, keyID and keyLabel arguments will delete one key associated with this keyID and keyLabel both at the localhost QKDLite node and remote QKDLite node remote_qnode. This command executes immediately.

Supplying a waitTime argument in addition to the above will delete the specified keys, but will delay execution of the deletion after a time delay of waitTime seconds.

Output

If successful, the output returns in the following format:

Deleting keys on remote QKDLite node QKDLITE_B...
<keyID_1>,<keyLabel_1>
<keyID_2>,<keyLabel_2>
...
<keyID_N>,<keyLabel_N>
Deleting keys locally on QKDLITE_A...
<keyID_1>,<keyLabel_1>
<keyID_2>,<keyLabel_2>
...
<keyID_N>,<keyLabel_N>

If unsuccessful due to incorrect input, there will be no output, indicating no key was deleted.

8.6.3. Cron Scripts¶

cron_maintain_min_num_keys.py [keyID] [number_of_keys] [remote_qnode]

Parameters:

Name	Input type	Description
`keyID`	string	The identifier for the secret key.
`number_of_keys`	int	The quantity of keys that are being checked for in the HSM. If this quantity is not met, keys will be generated until this number is met.
`remote_qnode`	string	Name of the node where secret key(s) will be added if necessary.

Description

Checks locally how many keys of given keyID exist. If it is less than the given number_of_keys, it adds keys locally and remotely at the given remote QKDLite node until the given minimum quantity of keys exist locally.

Supplying keyID, number_of_keys and remote_qnode arguments invoke checking the number of keys with the identifier keyID at the localhost QKDLite node. If it is less than a given minimum number of keys number_of_keys, quantum secret keys shared with the remote QKDLite node remote_qnode will be generated until the minimum number of keys is met.

Output

If successful and there are sufficient keys, the output returns in the following format:

Counting keys locally in HSM Slot <slot number> with keyID =<keyID>...
SUCCESS: Found <#keys> key(s).
Require minimum <number_of_keys> keys, and found <#keys> keys in
localhost QKDLite node...
No new keys needed, sufficient keys found in localhost HSM. Return
Script Error Code = 0.

If successful and there are insufficient keys, the output returns in the following format:

Counting keys locally in HSM Slot <slot number> with keyID =<keyID>...
SUCCESS: Found <#keys> key(s).
Require minimum <number_of_keys> keys, and found <#keys> keys in localhost QKDLite node...
Insufficient keys found in localhost HSM. Attempting to create <#keys-number_of_keys> keys locally with keyID=<keyID> and replicate remotely to node <remote_qnode> with keyID=<keyID>...
SUCCESS: created key #1 (of <#keys-number_of_keys>) locally and replicate remotely.
SUCCESS: created key #2 (of <#keys-number_of_keys>) locally and replicate remotely.
...
SUCCESS: Successfully created <#keys-number_of_keys> key(s) locally and replicate remotely. Return Script Error Code = 0.

If unsuccessful due failure in count key operation, the output returns in the following format:

Counting keys locally in HSM Slot <slot number> with keyID =<keyID>...
FAILED: QKD2HSM Return Code = <qkd2hsm_returncode>. Failed to get key count locally. Return Script Error Code = 2.

If unsuccessful due to a connectivity error, the output returns in the following format:

Counting keys locally in HSM Slot <slot number> with keyID =<keyID>...
SUCCESS: Found <#keys> key(s).
Require minimum <number_of_keys> keys, and found <#keys> keys in localhost QKDLite node...
Insufficient keys found in localhost HSM. Attempting to create <#keys-number_of_keys> keys locally with keyID=<keyID> and replicate remotely to node <remote_qnode> with keyID=<keyID>...
FAILED: Script Error Code = <qkd2hsm_returncode>. Failed to create key #1 (of <#keys-number_of_keys>) locally and replicate remotely.
FAILED: Script Error Code = <qkd2hsm_returncode>. Failed to create key #2 (of <#keys-number_of_keys>) locally and replicate remotely.
...
FAILED: Failed to create <#keys-number_of_keys> key(s) locally and replicate remotely. Return Script Error Code = 4.

If unsuccessful due to incorrect input, there will be no output, indicating no key was replicated.

cron_cleanup_lost_keys.py [remote_qnode] [keyID] [waitTime]

Parameters:

Name	Input type	Description
`remote_qnode`	string	Name of the node where secret key(s) will be checked for and deleted if necessary.
`keyID`	string	The identifier for the secret key(s).
`waitTime`	int	Time in seconds that this script will delay its execution by.

Description

Checks for keys that either exist only locally or only remotely (but not on both nodes) associated with the given keyID. If found, deletes such keys.

Supplying remote_qnode, keyID and waitTime arguments invoke checking for any keys with the identifier keyID at the localhost QKDLite node and at the remote QKDLite node. If such keys exist on only one of the nodes but not both, the script will spawn “delete key” subprocesses that will sleep for the given waitTime in seconds then activate to delete the keyID and related keyLabel of the “lost” key. The waitTime delay minimises deleting the key during the transitional period where the first key has been consumed and the second key has yet to be consumed by external SAE.

Output

If successful and there are no keys needing deletion, the output returns in the following format:

Get list of keys locally in HSM Slot <slot_number> with keyID = <keyID>...
SUCCESS: List contains <#> key(s).
Get list of keys in remote QKDLite node <remote_qnode> with keyID = <keyID>...
SUCCESS: List contains <#> key(s).
No "lost" keys found.' Return Script Error Code = 0.

If successful and there are keys that need to be deleted, the output returns in the following format:

Get list of keys locally in HSM Slot <slot_number> with keyID = <keyID>...
SUCCESS: List contains <#> key(s).
Get list of keys in remote QKDLite node <remote_qnode> with keyID = <keyID>...
SUCCESS: List contains <#> key(s).
No "lost" keys found.' Return Script Error Code = 0.
Found <#> "lost" keys between the QKDLite nodes. Attempting to delete "lost" keys...
Created subprocess to delete key with keyID = <keyID> and keyLabel = <keyLabel> after delay of <waitTime> seconds.
Created subprocess to delete key with keyID = <keyID> and keyLabel = <keyLabel> after delay of <waitTime> seconds.
...

If unsuccessful due failure in count key operation locally or remotely, the output returns in the following format:

Get list of keys locally in HSM Slot <slot_number> with keyID = <keyID>...
FAILED: QKD2HSM Return Code = <error_code>. Failed to get key list locally. Return Script Error Code = 4.

Get list of keys locally in HSM Slot <slot_number> with keyID = <keyID>...
SUCCESS: List contains <#> key(s).
Get list of keys in remote QKDLite node <remote_qnode> with keyID = <keyID>...
FAILED: QKDLite Script Return Code = <error_code>. Failed to get key list from remote QKDLite node. Return Script Error Code = 4.

If unsuccessful due to incorrect input, there will be no output, indicating no key(s) were deleted.