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. 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: .. code-block:: bash */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 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. 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`` 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. 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. QKDLite Script Commands -------------------------------------------------------------------------------- .. note:: Scripts are invoked by preceding the script name with ``./``, followed by the parameters given in order of listing. For example: .. code-block:: bash ./create_key.py QKDLITE_B ETSI Additional information about the nomenclature of parameters, devices and nodes referred to below can be found at :doc:`/terms_and_definitions`. 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: .. code:: text , 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: .. code:: text , , ... , 0 If no keys of supplied ``keyID`` are found, the output will return: .. code:: text 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: .. code:: text , , ... , 0 If there are no keys in the localhost QKDLite node or no keys match the given ``keyID``, the output will return: .. code:: text 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. 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: .. code:: text Creating key locally on ... , Replicating key on remote QKDLite node ... , If local key creation is successful but replication is unsuccessful, the output will be as follows: .. code:: text Creating key locally on ... , Attempt to undo key creation on localhost QKDLite node by deleting key... Deleting keys locally on ... , 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: .. code:: text Deleting keys on remote QKDLite node QKDLITE_B... , , ... , Deleting keys locally on QKDLITE_A... , , ... , If unsuccessful due to incorrect input, there will be no output, indicating no key was deleted. 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: .. code:: text Counting keys locally in HSM Slot with keyID =... SUCCESS: Found <#keys> key(s). Require minimum 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: .. code:: text Counting keys locally in HSM Slot with keyID =... SUCCESS: Found <#keys> key(s). Require minimum 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= and replicate remotely to node with 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: .. code:: text Counting keys locally in HSM Slot with keyID =... FAILED: QKD2HSM Return Code = . 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: .. code:: text Counting keys locally in HSM Slot with keyID =... SUCCESS: Found <#keys> key(s). Require minimum 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= and replicate remotely to node with keyID=... FAILED: Script Error Code = . Failed to create key #1 (of <#keys-number_of_keys>) locally and replicate remotely. FAILED: Script Error Code = . 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: .. code:: text Get list of keys locally in HSM Slot with keyID = ... SUCCESS: List contains <#> key(s). Get list of keys in remote QKDLite node with 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: .. code:: text Get list of keys locally in HSM Slot with keyID = ... SUCCESS: List contains <#> key(s). Get list of keys in remote QKDLite node with 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 = and keyLabel = after delay of seconds. Created subprocess to delete key with keyID = and keyLabel = after delay of seconds. ... If unsuccessful due failure in count key operation locally or remotely, the output returns in the following format: .. code:: text Get list of keys locally in HSM Slot with keyID = ... FAILED: QKD2HSM Return Code = . Failed to get key list locally. Return Script Error Code = 4. .. code:: text Get list of keys locally in HSM Slot with keyID = ... SUCCESS: List contains <#> key(s). Get list of keys in remote QKDLite node with keyID = ... FAILED: QKDLite Script Return 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.