bvtool Utility
The BlackVault Hardware Security Module (HSM) can perform a myriad of cryptographic functions, however a client program must be used to fully take advantage of the BlackVault. Engage Black has provided a utility that does this called bvtool. This utility allows the user to perform cryptographic operations such as sign, verify, encrypt and decrypt files, as well as basic key management.
There are 7 different funtions of bvtool they are as follows:
bvtool genkey
There are several types of keys one can create using this product they are: RSA, EC, DSA, AES, and Generic.
To create a key on the BlackVault HSM issue the command “bvtool genkey” followed by the following arguments:
- -n followed by the name of the key you are creating
- -t followed by the type of key you want to create (again, RSA, EC, DSA, AES, and Generic)
- -s followed by the size of the key if RSA, DSA, AES, or Generic are chosen
- -c followed by the curve of the key if EC is chosen
- The following curves can be created: prime192v1, prime256v1, secp224r1, secp384r1, secp521r1, sect163k1, sect163r2, sect233k1, sect233r1, sect283k1, sect283r1, sect409k1, sect409r1, sect571k1, sect571r1
- -x if you would like to use the X9.31 mechanism for key generation
- -e if you would like the key to be ephemeral (only exists during current session)
As an example of how this command might look:
- bvtool genkey -n [NAME] -t [RSA| DSA| AES| Generic] -s [SIZE]
- bvtool genkey -n [NAME] -t [EC] -c [CURVE]
bvtool -deletekey
Caution must be taken when issuing this command as it cannot be reversed
To delete a specific key off the BlackVault HSM issue the following command:
- bvtool -deletekey [NAME]
If you would like to delete all the keys off the BlackVault HSM issue the following command:
- bvtool -deletekey -all
bvtool -listkeys
To list all the keys on the BlackVault HSM issue the following command:
- bvtool -listkeys
bvtool encrypt
To encrypt a file using a key on the BlackVault HSM issue the command “bvtool encrypt” followed by the following arguments:
- -n followed by the name of the key you wish to use
- -m followed by the name of the mechanism you wish to use
- -in followed by the name of the file to be encrypted
- -out followed by the name of the output encrypted file.
Here is an example of how all this would look like:
- Bvtool encrypt -n [NAME] -m [MECHANISM] -in [FILENAME] -out [ENCRYPTED FILENAME]
bvtool decrypt
To decrypt a file using a key on the BlackVault HSM issue the command “bvtool decrypt” followed by the following arguments:
- -n followed by the name of the key you wish to use
- -m followed by the name of the mechanism you wish to use
- -in followed by the name of the encrypted file
- -out followed by the name of the output decrypted file.
Here is an example of how all this would look like:
- bvtool decrypt -n [NAME] -m [MECHANISM] -in [ENCRYPTED FILENAME] -out [DECRYPTEDFILENAME]
bvtool sign
To sign a file using a key on the BlackVault HSM issue the command “bvtool sign” followed by the following arguments:
- -n followed by the name of the key you wish to use
- -m followed by the name of the mechanism you wish to use
- -in followed by the name of the file to be signed
- -out followed by the name of the output signed file.
Here is an example of how all this would look like:
- bvtool sign -n [NAME] -m [MECHANISM] -in [FILENAME] -out [SIGNEDFILENAME]
bvtool verify
To verify a signed file using a key on the BlackVault HSM issue the command “bvtool verify” followed by the following arguments:
- -n followed by the name of the key you wish to use
- -m followed by the name of the mechanism you wish to use
- -in followed by the name of the signed file.
- -sig followed by the name of the signature file
Here is an example of how all this would look like:
- bvtool verify -n [NAME] -m [MECHANISM] -in [FILENAME] -sig [SIGNEDFILENAME]
Mechanisms Supported
Occasionally, when performing various functions of bvtool, you will need to specify a mechanism. Below is a list of supported mechanisms:
aes-ecb, aes-cbc, aes-cbc-pad, aes-ofb, aes-cfb8, aes-cfb128, aes-gcm, aes-kw
rsa-pkcs, rsa-sha1, rsa-sha224, rsa-sha256, rsa-sha384, rsa-sha512, rsa-md5, rsa-sha1-pss,
rsa-sha224-pss, rsa-sha256-pss, rsa-sha384-pss, rsa-sha512-pss, rsa-pkcs-pss, rsa-pkcs-oaep, rsa-x509, rsa-x931
ecdsa, ecdsa-sha1
sha1, sha224, sha256, sha384, sha512
dsa, dsa-sha1
cmac, hmac-sha512, hmac-sha384, hmac-sha256, hmac-sha224, hmac-sha1