7. 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.

7.1. 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

Key [<keyID>,<keyLabel>] with Object ID [<object_id>] created

One instance of a newly-created Key Object is

Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1597] created

7.1.1. 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.

7.2. QKDLite Utility Commands

Usage:

./QKD2HSM <operation>
   -slot <slot>
   -keyID <KeyID>
   [-password <HSM slot password>
   -kme <QKD KME URL>
   -remote <Remote ID>
   -keyType <KeyType>
   -keyLabel <KeyLabel>
   -keyData <Key material>
   [-cacert <cacertfilename>
   -cert <certfile>
   -key <keyfilename>]
   -infile <file to enc/dec>
   -outfile <output of enc/dec>
   -library <PKCS#11 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.

7.2.1. Key Creation

  1. 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.

    ./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:

+--------------------------+
| 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)

  1. 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.

    ./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:

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1234] created

  1. 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.

    ./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:

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1234] created

7.2.2. Key Listing

  1. List all keys with same keyID

    The following sample command lists all keys in the HSM with keyID = “MyKey”:

    ./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:

+--------------------------+
| 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]

  1. List all keys

    The following sample command lists all keys in the HSM regardless of keyID value:

    ./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:

+--------------------------+
| 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]
...

7.2.3. Key Counting

  1. Count specific keys

    The following sample command counts all keys in the HSM with keyID = keyID:

    ./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:

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
[3] Keys found

  1. Count all keys

    The following sample command counts all keys in the HSM regardless of keyID value:

    ./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:

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
[5] Keys found

7.2.4. Key Deletion

  1. Delete all keys with same keyID

    The following sample command deletes all keys in the HSM with keyID = “MyKey”:

    ./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:

+--------------------------+
| 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

  1. Delete specific number of keys with same keyID

    The following sample command deletes a given count keys in the HSM with keyID = “MyKey”:

    ./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:

+--------------------------+
| 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.

  1. Delete key with same keyID and keyLabel

    The following sample command deletes one key with the associated keyID and keyLabel if it exists:

    ./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:

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1111] deleted

Otherwise, no key will be deleted.

7.2.5. File Encryption and Decryption

  1. 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.

    ./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:

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1234] used for encryption and deleted

  1. 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.

    ./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:

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Key [MyKey,c44946a0ce9c4030ab056bb604653262] with Object ID [1234] used for decryption and deleted

7.2.6. 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:

    ./Insert2HSM \
   -slot 0 \
   -password "some_password" \
   -keyID "some_key" \
   -keyData "<keyData material>"

    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 = “<keyData material>” 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:

    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:

    ./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.

  2. Key Pull

    Using the QKD2HSM Utility script, the following sample command in the local HSM retrieves an encrypted version of the key:

    ./QKD2HSM pull -slot 0 -password "some_password" -keyID "MyKey"

    This produces the output:

    +--------------------------+
| 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.

  3. 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:

    ./QKD2HSM push \
   -slot 0 \
   -password "some_password" \
   -keyID "MyKey" \
   -keyLabel "52414e44b995ff4b1068f04fbc3450b9" \
   -keyData "5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E"

    This produces the output:

    +--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Key [MyKey,52414e44b995ff4b1068f04fbc3450b9] with Object ID [1234] value [5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E] pushed into HSM

7.2.7. 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.

  1. 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:

    ./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:

    +--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Key [MyKey,52414e44b995ff4b1068f04fbc3450b9] with Object ID [1234] with transient value [5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E] deleted

  2. Specific key retrieval given keyID and keyLabel

    The following sample command retrieves a key from a HSM given a specified keyID and keyLabel:

    ./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:

    +--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Key [MyKey,52414e44b995ff4b1068f04fbc3450b9] with Object ID [1234] with transient value [5360E007CF084DACF4993CD974C94C36C1AE5FE162A2632CD2DF1CDDE221E35E] deleted