QKDLite Utility API Reference ================================================================================ This section describes the various key management commands supported by the QKDLite Utility contained in the ``QKD2HSM`` binary. The QKDLite Utility communicates with both the HSM and QKD KME to manage keys stored in the HSM as Key Objects. Key Object -------------------------------------------------------------------------------- A **Key Object** in the HSM has several components. Depending on the key operation involved, QKDLite Utility will describe the various components of the Key Object in the console. For example, in the key creation operation, the newly-created Key Object is described by QKDLite Utility with the following layout .. code-block:: text Key [,] with Object ID [] created One instance of a newly-created Key Object is .. code-block:: text Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1597] created Components in Key Object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The components in a Key Object are: - ``keyID`` refers to the application purpose tagged to the key in the HSM. There can be more than one **Key Object** having the same ``keyID``. - ``keyLabel`` refers to the unique identifier for a quantum key generated by the paired QKD SAE appliances. When paired QKD SAE appliances generate a quantum key, they will both generate and store the same unique ``keyID`` in each of them. - ``object_id`` refers to an internal object identifier managed by the HSM. The ``object_id`` is a unique identifier for each **Key Object** in each HSM. .. note:: The ``keyID`` and ``keyLabel`` is used together as a 2-tuple to uniquely identify a QKD key stored across multiple HSMs. QKDLite Utility Commands -------------------------------------------------------------------------------- Usage: .. code-block:: bash ./QKD2HSM -slot -keyID [-password -kme -remote -keyType -keyLabel -keyData [-cacert -cert -key ] -infile -outfile -library -count -debug ] Explanation of parameters: ==================== ======================================================== ``operation``\* The operation to be performed. One of: - ``c`` create key - ``l`` list keys - ``d`` delete key(s) - ``e`` encrypt and decrypt files - ``pull`` retrieve encrypted key with transport key - ``push`` insert key encrypted with transport key - ``pop`` retrieve a derived key value ``slot``\* The HSM slot where the key operation will occur. ``password`` Used to access target HSM slot. If not provided in parameters as plaintext, it will be required to type in afterwards. ``keyID``\* An identifier for secret quantum keys. Not required to be unique. ``keyLabel`` A unique identifier for secret quantum keys generated by the QKD. ``kme`` URL to the associated KME. Do not provide if obtaining a key from ``/dev/urandom``. ``remote`` Name of the paired QKD SAE. Do not provide if obtaining a key from ``/dev/urandom``. ``keyType`` One of "AES128", "AES192", "AES256" (default). ``keyData`` The ``keyData`` is hashed with a KDF, and encrypts the secret key for secure transportation. The keyData material is given to the user. ``keyFlags`` Total integer value of flags. Flags listed: - ``1`` sensitive - ``2`` extractable - ``4`` used for encryption - ``8`` wrapped For example, ``7`` means the key is sensitive, extractable and used for encryption. ``cacert`` Name of file containing the CA certificate. ``cert`` Name of file containing the client certificate. ``key`` Name of file containing the client private key. ``infile`` Name of input file to be encrypted. ``outfile`` Name of output file after decryption. ``library`` Name of PKCS#11 library file. ``count`` Integer value for bulk operation, or ``*``. Applicable for key creation, deletion and listing. ``debug`` Turn on this flag to print out information for debugging purposes. ==================== ======================================================== *\*always required.* Note that only specific parameters are required for certain operations. Such operations are listed in greater detail below. Key Creation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. **Create new QKD Key(s) from QKD KME** The following sample command demonstrates the creation of a new QKD key in the HSM generated by the associated QKD KME. .. code-block:: bash ./QKD2HSM c \ -slot 0 \ -password "some_password" \ -keyID "MyKey" \ -kme "https://4.14.4.14" \ -remote "SAE_B" \ -keyType "AES256" \ -count 100 Explanation of parameters for the newly created key: ====================== ====================================================== ``c`` "create" operation; indicates a key will be created ``slot`` Will be stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Will be tagged with ``keyID`` = "MyKey" ``kme`` Gets the QKD quantum key from the QKD KME at IP address 4.14.4.14 ``remote`` Name of the paired QKD SAE = "SAE_B" ``keyType`` (optional) One of "AES128", "AES192", "AES256" (default). In this case the created key will have 256-bit entropy. ``count`` (optional) Integer value indicating 100 keys to be created ====================== ====================================================== This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,c83786d5ba69484ebe5658e1b116322f] with Object ID [1234] created Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [5678] created ...(repeats 98 more times) #. **Create new Key Object with Existing QKD Key** The following sample command demonstrates the creation of a new Key Object in the HSM with a QKD key that has been previously generated by the QKD KME. .. code-block:: bash ./QKD2HSM c \ -slot 1 \ -password "example_password" \ -keyID "MyKey" \ -keyLabel "c44946a0ce9c4030ab056bb604653262" \ -kme "https://3.13.3.13" \ -remote "SAE_A" Explanation of parameters for the newly created key: ======================= ====================================================== ``c`` "create" operation; indicates a key will be created ``slot`` Will be stored inside HSM Slot 1 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Will be tagged with ``keyID`` = "MyKey" ``keyLabel`` Will get the QKD key from QKD KME with QKD ``keyLabel`` = "c44946a0ce9c4030ab056bb604653262" ``kme`` Gets the QKD quantum key from the QKD KME at IP address 3.13.3.13 ``remote`` Name of the paired QKD SAE = "SAE_A" ======================= ====================================================== This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1234] created #. **Create new Key Object from internal urandom function** The following sample command demonstrates the creation of a new Key Object in the HSM with a QKD key that is generated from the ``/dev/urandom`` function internally. Note that this method does not require a paired QKD KME as it generates keys from the ``/dev/urandom`` function internal to the localhost QKDLite node. .. code-block:: bash ./QKD2HSM c -slot 0 -password 12345678 -keyID "MyKey" Explanation of parameters for the newly created key: ==================== ======================================================== ``c`` "create" operation; indicates a key will be created ``slot`` Will be stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Will be tagged with ``keyID`` = "MyKey" ``count`` (optional) Integer value indicating any more than one key to be created ==================== ======================================================== This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1234] created Key Listing ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. **List all keys with same keyID** The following sample command lists all keys in the HSM with ``keyID`` = "MyKey": .. code-block:: bash ./QKD2HSM l -slot 0 -password "some_password" -keyID "MyKey" Explanation of parameters for the listed key(s): ==================== ======================================================== ``l`` "list" operation ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "MyKey" ==================== ======================================================== This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Found Key [MyKey,c83786d5ba69484ebe5658e1b116322f] with Object ID [1234] Found Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [5678] #. **List all keys** The following sample command lists all keys in the HSM regardless of ``keyID`` value: .. code-block:: bash ./QKD2HSM l -slot 0 -password "some_password" Explanation of parameters for the listed key(s): ==================== ======================================================== ``l`` "list" operation ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ==================== ======================================================== This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Found Key [MyKey,c83786d5ba69484ebe5658e1b116322f] with Object ID [1234] Found Key [MyKey2,c44946a0ce9c4030ab056bb604653262] with Object ID [5678] Found Key [MyKey3,c44646a0ce9642305h856bt408613278] with Object ID [10] ... Key Counting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. **Count specific keys** The following sample command counts all keys in the HSM with keyID = ``keyID``: .. code-block:: bash ./QKD2HSM l \ -slot 0 \ -password "some_password" \ -keyID "myKey" \ -count "*" Explanation of parameters for the listed key(s): ==================== ======================================================== ``l`` "list" operation ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "MyKey" ``count`` Changes the output from a list of keys to the number of keys found in the HSM slot ==================== ======================================================== If there are three keys with ``keyID`` = "MyKey", this produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ [3] Keys found #. **Count all keys** The following sample command counts all keys in the HSM regardless of ``keyID`` value: .. code-block:: bash ./QKD2HSM l -slot 0 -password "some_password" -count "*" Explanation of parameters for the listed key(s): ==================== ======================================================== ``l`` "list" operation ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``count`` Changes the output from a list of keys to the number of keys found in the HSM slot ==================== ======================================================== If there are five keys, this produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ [5] Keys found Key Deletion ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. **Delete all keys with same keyID** The following sample command deletes all keys in the HSM with ``keyID`` = "MyKey": .. code-block:: bash ./QKD2HSM d -slot 0 -password "some_password" -keyID "MyKey" Explanation of parameters that match the keys to be deleted: ==================== ======================================================== ``d`` "delete" operation ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "MyKey" ==================== ======================================================== This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,c83786d5ba69484ebe5658e1b116322f] with Object ID [1234] deleted Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [5678] deleted #. **Delete specific number of keys with same keyID** The following sample command deletes a given ``count`` keys in the HSM with ``keyID`` = "MyKey": .. code-block:: bash ./QKD2HSM d \ -slot 0 \ -password "some_password" \ -keyID "MyKey" \ -count 5 Explanation of parameters that match the keys to be deleted: ==================== ======================================================== ``d`` "delete" operation ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "MyKey" ``count`` Deletes ``count`` number of keys from the HSM slot with the given ``keyID`` ==================== ======================================================== If there are at least five keys with ``keyID`` = "MyKey", this produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,c83786d5ba69484ebe5658e1b116322f] with Object ID [1111] deleted Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [2222] deleted Key [MyKey,b44946a0ce9c4030ab056bb604653262] with Object ID [3333] deleted Key [MyKey,d44946a0ce9c4030ab056bb604653262] with Object ID [4444] deleted Key [MyKey,e44946a0ce9c4030ab056bb604653262] with Object ID [5555] deleted Note that if there are less than five then all they will be deleted. #. **Delete key with same keyID and keyLabel** The following sample command deletes one key with the associated ``keyID`` and ``keyLabel`` if it exists: .. code-block:: bash ./QKD2HSM d \ -slot 0 \ -password "some_password" \ -keyID "MyKey" \ -keyLabel "c44946a0ce9c4030ab056bb604653262" Explanation of parameters that match the key to be deleted: ==================== ======================================================== ``d`` "delete" operation ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "MyKey" ``keyLabel`` Tagged with ``keyLabel`` = "c44946a0ce9c4030ab056bb604653262" inside the HSM ==================== ======================================================== If such a key exists, this produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1111] deleted Otherwise, no key will be deleted. .. Key Replacement .. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. Key Replacement is used in the case of deleting an existing secret key and .. creating a new secret key with the same ``keyID``. It performs Key Deletion .. followed by Key Creation. .. #. **Replace all keys with same keyID** .. The following sample command deletes all keys in the HSM with ``keyID`` = .. "MyKey" if they exist, and creates one new key with ``keyID`` = "MyKey": .. .. code-block:: bash .. ./QKD2HSM r -slot 0 -password "some_password" -keyID "MyKey" .. Explanation of parameters for key replacement: .. ==================== ======================================================== .. ``r`` "replace" operation .. ``slot`` Stored inside HSM Slot 0 .. ``password`` Uses ``password`` = "some_password" to access target HSM .. slot .. ``keyID`` Tagged with ``keyID`` = "MyKey" .. ==================== ======================================================== .. #. **Replace specific key with same keyID and keylabel** [TODO] .. The following sample command deletes one key with the associated ``keyID`` .. and ``keyLabel`` if it exists, then creates a new key with ``keyID`` = .. "MyKey": and ``keyLabel`` = "c44946a0ce9c4030ab056bb604653262": .. .. code-block:: bash .. ./QKD2HSM r -slot 0 -password "some_password" -keyID "MyKey" -keyLabel .. "c44946a0ce9c4030ab056bb604653262" .. Explanation of parameters that match specific key to be replaced: .. ==================== ======================================================== .. ``r`` "replace" operation .. ``slot`` Stored inside HSM Slot 0 .. ``password`` Uses ``password`` = "some_password" to access target HSM .. slot .. ``keyID`` Tagged with ``keyID`` = "MyKey" .. ``keyLabel`` Tagged with ``keyLabel`` = .. "c44946a0ce9c4030ab056bb604653262" inside the HSM .. ==================== ======================================================== File Encryption and Decryption ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. **File Encryption** The following sample command encrypts a file = "a.txt" to an output file = "a.enc" using a previously created key. Note that the key is consumed after encryption of the file, and that the keyLabel is not needed. .. code-block:: bash ./QKD2HSM e \ -slot 0 \ -password "some_password" \ -keyID "MyKey" \ -infile "a.txt" \ -outfile "a.enc" Explanation of parameters for file encryption: ==================== ======================================================== ``e`` "file encrypt and decrypt" operation ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "MyKey" ``infile`` The name of file to be encrypted = "a.txt". ``outfile`` The name of the file where the contents of the encrypted infile will be placed. ==================== ======================================================== If such a key and file exist, this produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1234] used for encryption and deleted #. **File Decryption** File decryption follows the exact same method as file encryption. The following sample command decrypts a file = "a.enc" to an output file = "a.dec" using the previously created key used to encrypt the file. Note that the key is consumed after decryption of the file. .. code-block:: bash ./QKD2HSM e \ -slot 0 \ -password "some_password" \ -keyID "MyKey" \ -infile "a.enc" \ -outfile "a.dec" If such a key and file exist, this produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1234] used for decryption and deleted Key Synchronization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. **Setup** Before the Key Push operation can be performed, both the local and remote HSM must first have the same TPT (Transport) key inserted. There must only be one TPT key in each HSM. Use the Utility Script ``Insert2HSM`` to insert the TPT key in the localhost HSM if not already there: .. code-block:: bash ./Insert2HSM \ -slot 0 \ -password "some_password" \ -keyID "some_key" \ -keyData "" Explanation of parameters for TPT key insertion: ====================== ====================================================== ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "some_key". The keyID of the TPT Key is not important. ``keyData`` The ``keyData`` = "" is hashed with a KDF, and encrypts the secret key for secure transportation. The keyData material is given to the user. ``keyType`` (optional) One of "AES128", "AES192" or "AES256" (default) ``library`` (optional) Name of PKCS#11 library file where keys will be stored ====================== ====================================================== Output after creating the TPT key locally: .. code-block:: bash TPT Key [some_key] with Object ID [1234] inserted Check that this is the only TPT key in the local HSM, then repeat the setup for the remote HSM where the key will be synchronized. Note that the ``keylabel`` will be "QKDLite TPT". Below is a sample command for listing keys: .. code-block:: bash ./QKD2HSM l -slot 0 -password "some_password" -keyLabel "QKDLite TPT" +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Found Key [some_key,QKDLite TPT] with Object ID [1234] Now that it is confirmed there is one TPT Key in both the local and remote HSM, created keys in the local HSM can be exported to the remote HSM. #. **Key Pull** Using the ``QKD2HSM`` Utility script, the following sample command in the local HSM retrieves an encrypted version of the key: .. code-block:: bash ./QKD2HSM pull -slot 0 -password "some_password" -keyID "MyKey" This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,52414e44b995ff4b1068f04fbc3450b9] with Object ID [1234] value [5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E] pulled from HSM Take note of the ``keyLabel`` and encrypted key value of the output as these are used to insert the key into the remote HSM. #. **Key Push** Using the ``QKD2HSM`` Utility script, the following sample command in the remote HSM pushes the supplied existing encrypted secret key into the HSM: .. code-block:: bash ./QKD2HSM push \ -slot 0 \ -password "some_password" \ -keyID "MyKey" \ -keyLabel "52414e44b995ff4b1068f04fbc3450b9" \ -keyData "5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E" This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,52414e44b995ff4b1068f04fbc3450b9] with Object ID [1234] value [5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E] pushed into HSM Key Retrieval ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the event that a secret key needs to be retrieved, a derived value of the key can be returned. After retrieval, the key is deleted from the HSM. #. **Random key retrieval given keyID** The following sample command retrieves a key from a HSM with ``keyID`` = "MyKey". If there are multiple keys that match, one will be chosen at random to retrieve: .. code-block:: bash ./QKD2HSM pop -slot 0 -password "some_password" -keyID "MyKey" Explanation of parameters for key retrieval: ==================== ======================================================== ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "MyKey". ==================== ======================================================== This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,52414e44b995ff4b1068f04fbc3450b9] with Object ID [1234] with transient value [5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E] deleted #. **Specific key retrieval given keyID and keyLabel** The following sample command retrieves a key from a HSM given a specified ``keyID`` and ``keyLabel``: .. code-block:: bash ./QKD2HSM pop \ -slot 0 \ -password "some_password" \ -keyID "MyKey" \ -keyLabel "52414e44b995ff4b1068f04fbc3450b9" Explanation of parameters for key retrieval: ==================== ======================================================== ``slot`` Stored inside HSM Slot 0 ``password`` Uses ``password`` = "some_password" to access target HSM slot ``keyID`` Tagged with ``keyID`` = "MyKey". ``keyLabel`` Tagged with ``keyLabel`` = "52414e44b995ff4b1068f04fbc3450b9" inside the HSM ==================== ======================================================== This produces the output: .. code-block:: bash +--------------------------+ | QKD2HSM utility by pQCee | | | | Copyright (c) pQCee | | info@pqcee.com | +--------------------------+ Key [MyKey,52414e44b995ff4b1068f04fbc3450b9] with Object ID [1234] with transient value [5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E] deleted