Command Line Interface Reference v3.2.0¶
A list of commands, or the options for a specific command, can be obtained using the --help parameter:
$ ./qo_hsm_cli --help
QO Luna Reseed CLI v2.6.2
Usage: ./qo_hsm_cli [OPTIONS] SUBCOMMAND
OPTIONS:
-h, --help Print this help message and exit
-v, --verbose
--p11_lib TEXT [/usr/safenet/lunaclient/lib/libCryptoki2_64.so]
P11 library path
SUBCOMMANDS:
seed Seed entropy
password Load slot password
genrsaenc Generate RSA encryption key
rsaenc RSA encrypt a password
delkey Delete key/s
version Print version
seed- Runs a single iteration of entropy reseeding.password- Loads a password value into an object, to be used to authenticate to slots for reseeding.genrsaenc- Generates an RSA encryption key, that can be used for encrypting slot passwords.rsaenc- Encrypts a password using an RSA encryption key.delkey- Deletes all keys with a given label.version- Prints the CLI version.
RSA Encryption Key Generation¶
The genrsaenc command is used to generate an RSA encryption key:
$ ./qo_hsm_cli genrsaenc --help
Generate RSA encryption key
Usage: ./qo_hsm_cli genrsaenc [OPTIONS]
OPTIONS:
-h, --help Print this help message and exit
-p, --pass TEXT Primary slot CO password (omit to be prompted securely)
-w, --label TEXT [rsaEncryptionKey]
RSA encryption key label, default=rsaEncryptionKey
-s, --key_size UINT RSA encryption key size in bits, default=4096
[Option Group: primary slot]
[Exactly 1 of the following options are required]
OPTIONS:
-h, --help Print this help message and exit
--primary_slot_index UINT
Index of primary slot
--primary_slot_id UINT
ID of primary slot
--primary_slot_token_label TEXT
Token label of primary slot
-p,--pass TEXT- The Crypto Officer (CO) password for the primary slot.
Note
For security it is recommended this be omitted from the command-line; you will then be prompted to enter the password interactively.
-w,--label TEXT- The label to give the generated RSA key. The same label will be given to both the public and private halves.-s,--key_size UINT- The size of RSA key to generate (in bits).
The primary slot which the generated RSA key will be stored under should be specified using one of the following options:
--primary_slot_index UINT- Index of the primary slot. This value will be used as an index into the array of slot IDs returned from the C_GetSlotList function.--primary_slot_id UINT- ID of the primary slot. This ID will be used directly as if it were one of the values returned from C_GetSlotList.--primary_slot_token_label- The slots will be searched for one containing a token with a matching label. The first matching slot will be used.
Password Object Loading¶
The password command is used to load the password (aka PIN) for a slot into a PKCS#11 object so it can be securely accessed by the functionality module:
$ ./qo_hsm_cli password --help
Load slot password
Usage: ./qo_hsm_cli password [OPTIONS]
OPTIONS:
-h, --help Print this help message and exit
-p, --primary_pass TEXT Primary slot CO password (omit to be prompted securely)
-n, --password TEXT Password to load (omit to be prompted securely)
-l, --label TEXT REQUIRED
Label to give the password object
[Option Group: primary slot]
[Exactly 1 of the following options are required]
OPTIONS:
-h, --help Print this help message and exit
--primary_slot_index UINT
Index of primary slot
--primary_slot_id UINT
ID of primary slot
--primary_slot_token_label TEXT
Token label of primary slot
-p,--primary_pass TEXT- The Crypto Officer (CO) password for the primary slot.
Note
For security it is recommended this be omitted from the command-line; you will then be prompted to enter the password interactively.
-n,--password TEXT- The password to be loaded. This should be the Crypto User (CU) password of the slot to be reseeded. This password must be at least 8 characters in length.
Note
For security it is recommended this be omitted from the command-line; you will then be prompted to enter the password interactively.
-l,--label TEXT REQUIRED- The label to be given to the password object.
The primary slot which the password object will be stored under should be specified using one of the following options:
--primary_slot_index UINT- Index of the primary slot. This value will be used as an index into the array of slot IDs returned from the C_GetSlotList function.--primary_slot_id UINT- ID of the primary slot. This ID will be used directly as if it were one of the values returned from C_GetSlotList.--primary_slot_token_label- The slots will be searched for one containing a token with a matching label. The first matching slot will be used.
Password Object Encryption¶
The rsaenc command is used to encrypt the password (aka PIN) for a slot so it can be securely stored in a configuration file:
$ ./qo_hsm_cli rsaenc --help
RSA encrypt a password
Usage: ./qo_hsm_cli rsaenc [OPTIONS]
OPTIONS:
-h, --help Print this help message and exit
-p, --primary_pass TEXT Primary slot CO password (omit to be prompted securely)
--login_type co|cu Login type, co or cu, default=cu
-w, --label TEXT [rsaEncryptionKey]
RSA encryption key label, default=rsaEncryptionKey
-n, --password TEXT Password to encrypt (omit to be prompted securely)
[Option Group: primary slot]
[Exactly 1 of the following options are required]
OPTIONS:
-h, --help Print this help message and exit
--primary_slot_index UINT
Index of primary slot
--primary_slot_id UINT
ID of primary slot
--primary_slot_token_label TEXT
Token label of primary slot
-p,--primary_pass TEXT- The Crypto Officer (CO) password for the primary slot.
Note
For security it is recommended this be omitted from the command-line; you will then be prompted to enter the password interactively.
-n,--password TEXT- The password to be encrypted. This should be the Crypto User (CU) password of the slot to be reseeded. This password must be at least 8 characters in length.
Note
For security it is recommended this be omitted from the command-line; you will then be prompted to enter the password interactively.
--login_type co|cu- (Optional) Login type to use for the primary slot. ‘co’ for Crypto Officer (write-access) or ‘cu’ for Crypto User (read-only). It is recommended that the read-only login be used if possible, to avoid unnecessarily exposing write access to the partition. Default: ‘cu’ (Crypto User, read-only).-l,--label TEXT REQUIRED- The label of the RSA key to be used for encryption.
The primary slot which the password object will be stored under should be specified using one of the following options:
--primary_slot_index UINT- Index of the primary slot. This value will be used as an index into the array of slot IDs returned from the C_GetSlotList function.--primary_slot_id UINT- ID of the primary slot. This ID will be used directly as if it were one of the values returned from C_GetSlotList.--primary_slot_token_label- The slots will be searched for one containing a token with a matching label. The first matching slot will be used.
Key Deletion¶
The delkey command can be used to delete a key that is no longer required. Caution should be taken when using this
command as it may not be possible to recover a deleted key, and you will not be prompted for confirmation:
$ ./qo_hsm_cli delkey --help
Delete key/s
Usage: ./qo_hsm_cli delkey [OPTIONS]
OPTIONS:
-h, --help Print this help message and exit
-p, --pass TEXT Primary slot CO password (omit to be prompted securely)
-l, --label TEXT REQUIRED
Label of key to delete
[Option Group: primary slot]
[Exactly 1 of the following options are required]
OPTIONS:
-h, --help Print this help message and exit
--primary_slot_index UINT
Index of primary slot
--primary_slot_id UINT
ID of primary slot
--primary_slot_token_label TEXT
Token label of primary slot
-p,--pass TEXT- The Crypto Officer (CO) password for the primary slot.
Note
For security it is recommended this be omitted from the command-line; you will then be prompted to enter the password interactively.
-l,--label TEXT- Label of the key/s to be deleted.
Caution
All keys with matching labels will be deleted without confirmation.
The primary slot which the keys to be deleted are stored under should be specified using one of the following options:
--primary_slot_index UINT- Index of the primary slot. This value will be used as an index into the array of slot IDs returned from the C_GetSlotList function.--primary_slot_id UINT- ID of the primary slot. This ID will be used directly as if it were one of the values returned from C_GetSlotList.--primary_slot_token_label- The slots will be searched for one containing a token with a matching label. The first matching slot will be used.
Seeding¶
The seed command can be used to perform a single reseeding of the HSM’s PRNG using Quantum Origin entropy:
$ ./qo_hsm_cli seed --help
Seed entropy
Usage: ./qo_hsm_cli seed [OPTIONS]
OPTIONS:
-h, --help Print this help message and exit
-p, --pass TEXT Primary slot password (omit to be prompted securely)
--login_type co|cu Login type, co or cu, default=cu
-a, --amount UINT Amount of entropy to reseed with, default=48 (bytes)
[Option Group: primary slot]
[Exactly 1 of the following options are required]
OPTIONS:
-h, --help Print this help message and exit
--primary_slot_index UINT
Index of primary slot
--primary_slot_id UINT
ID of primary slot
--primary_slot_token_label TEXT
Token label of primary slot
[Option Group: slot to reseed]
[Exactly 1 of the following options are required]
OPTIONS:
-h, --help Print this help message and exit
--reseed_slot_index UINT
Index of slot to reseed
--reseed_slot_id UINT
ID of slot to reseed
--reseed_slot_token_label TEXT
Token label of slot to reseed
[Option Group: Slot to reseed password]
[Exactly 1 of the following options are required]
OPTIONS:
-h, --help Print this help message and exit
-r, --pass_label TEXT Excludes: --reseed_pass
Slot to reseed password object label
--reseed_pass TEXT Excludes: --pass_label
Slot to reseed password
-p,--pass TEXT- The password for the primary slot.
Note
For security it is recommended this be omitted from the command-line; you will then be prompted to enter the password interactively.
--login_type co|cu- (Optional) Login type to use for the primary slot. ‘co’ for Crypto Officer (write-access) or ‘cu’ for Crypto User (read-only). It is recommended that the read-only login be used if possible, to avoid unnecessarily exposing write access to the partition. Default: ‘cu’ (Crypto User, read-only).-a,--amount UINT- The amount of entropy (in bytes) to reseed with.
The primary slot should be specified using one of the following options:
--primary_slot_index UINT- Index of the primary slot. This value will be used as an index into the array of slot IDs returned from the C_GetSlotList function.--primary_slot_id UINT- ID of the primary slot. This ID will be used directly as if it were one of the values returned from C_GetSlotList.--primary_slot_token_label- The slots will be searched for one containing a token with a matching label. The first matching slot will be used.
The slot to be reseeded should be specified using one of the following options:
--reseed_slot_index UINT- Index of the slot to reseed, this must be the slot index as visible to the HSM, the partition does not need to be assigned to the reseed client.--reseed_slot_id UINT- ID of the slot to reseed. To use this option, the partition must be assigned to the reseed client, and the MD_GetEmbeddedSlotID function will be used to map the local slot ID to the HSM’s slot ID.--reseed_slot_token_label- The slots will be searched for one containing a token with a matching label. The first matching slot will be used.
The password for the slot to be reseeded should be specified using one of the following options:
-r,--pass_label TEXT- The label of the password object containing the password for the slot to be reseeded.--reseed_pass TEXT- The plaintext password for the slot to be reseeded.