The Error2String helper command in key_mgmt_util returns the error that corresponds to a key_mgmt_util hexadecimal error code. You can use this command when troubleshooting your commands and scripts.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 153) and log in (p. 154) to the HSM as a crypto user (CU).
Syntax
Error2String -h
Error2String -r <response-code>
Examples
These examples show how to use Error2String to get the error string for a key_mgmt_util error code.
Example : Get an error description
This command gets the error description for the 0xdb error code. The description explains that an attempt to log in to key_mgmt_util failed because the user has the wrong user type. Only crypto users (CU) can log in to key_mgmt_util.
Command: Error2String -r 0xdb
Error Code db maps to HSM Error: Invalid User Type.
Example : Find the error code
This example shows where to find the error code in a key_mgmt_util error. The error code, 0xc6, appears after the string: Cfm3command-name returned: .
In this example, getKeyInfo (p. 200) indicates that the current user (user 4) can use the key in
cryptographic operations. Nevertheless, when the user tries to use deleteKey (p. 160) to delete the key, the command returns error code 0xc6.
Reference
Command: deleteKey -k 262162
Cfm3DeleteKey returned: 0xc6 : HSM Error: Key Access is denied Cluster Error Status
Command: getKeyInfo -k 262162
Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS Owned by user 3
also, shared to following 1 user(s):
4
If the 0xc6 error is reported to you, you can use an Error2String command like this one to look up the error. In this case, the deleteKey command failed with an access denied error because the key is shared with the current user but owned by a different user. Only key owners have permission to delete a key.
Command: Error2String -r 0xa8
Error Code c6 maps to HSM Error: Key Access is denied
Parameters
-h
Displays help for the command.
Required: Yes -r
Specifies a hexadecimal error code. The 0x hexadecimal indicator is required.
Required: Yes
exit
The exit command in key_mgmt_util exits the key_mgmt_util. Upon successful exit, you will be returned to your standard command line.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 153).
Syntax
exit
Parameters
There are no parameters for this command.
Related topics
• Start key_mgmt_util (p. 153)
Reference
exportPrivateKey
The exportPrivateKey command in key_mgmt_util exports an asymmetric private key in an HSM to a file. You can use it to export private keys that you generate on the HSM. You can also use the command to export private keys that were imported into an HSM, such as those imported with the importPrivateKey (p. 204) command.
During the export process, exportPrivateKey uses an AES key that you select (the wrapping key) to wrap (encrypt) the private key. This way, the private key file maintains integrity during transit. For more information, see wrapKey (p. 232).
The exportPrivateKey command copies the key material to a file that you specify. But it does not remove the key from the HSM, change its key attributes (p. 235), or prevent you from using the key in further cryptographic operations. You can export the same key multiple times.
You can only export private keys that have OBJ_ATTR_EXTRACTABLE attribute value 1. To find a key's attributes, use the getAttribute (p. 194) command.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 153) and log in (p. 154) to the HSM as a crypto user (CU).
Syntax
exportPrivateKey -h
exportPrivateKey -k <private-key-handle -w <wrapping-key-handle>
-out <key-file>
[-m <wrapping-mechanism>]
[-wk <wrapping-key-file>]
Examples
This example shows how to use exportPrivateKey to export a private key out of an HSM.
Example : Export a private key
This command exports a private key with handle 15 using a wrapping key with handle 16 to a PEM file called exportKey.pem. When the command succeeds, exportPrivateKey returns a success message.
Command: exportPrivateKey -k 15 -w 16 -out exportKey.pem Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS PEM formatted private key is written to exportKey.pem
Parameters
This command takes the following parameters.
-h
Displays command line help for the command.
Required: Yes
Reference
-k
Specifies the key handle of the private key to be exported.
Required: Yes -w
Specifies the key handle of the wrapping key. This parameter is required. To find key handles, use the findKey (p. 171) command.
To determine whether a key can be used as a wrapping key, use getAttribute (p. 194) to get the value of the OBJ_ATTR_WRAP attribute (262). To create a wrapping key, use genSymKey (p. 189) to create an AES key (type 31).
If you use the -wk parameter to specify an external unwrapping key, the -w wrapping key is used to wrap, but not unwrap, the key during export.
Required: Yes -out
Specifies the name of the file to which the exported private key will be written.
Required: Yes -m
Specifies the wrapping mechanism with which to wrap the private key being exported. The only valid value is 4, which represents the NIST_AES_WRAP mechanism.
Default: 4 (NIST_AES_WRAP) Required: No
-wk
Specifies the key to be used to unwrap the key being exported. Enter the path and name of a file that contains a plaintext AES key.
When you include this parameter, exportPrivateKey uses the key in the -w file to wrap the key being exported and uses the key specified by the -wk parameter to unwrap it.
Default: Use the wrapping key specified in the -w parameter to both wrap and unwrap.
Required: No
Related topics
• importPrivateKey (p. 204)
• wrapKey (p. 232)
• unWrapKey (p. 226)
• genSymKey (p. 189)
exportPubKey
The exportPubKey command in key_mgmt_util exports a public key in an HSM to a file. You can use it to export public keys that you generate in an HSM. You can also use this command to export public keys that were imported into an HSM, such as those imported with the importPubKey (p. 207) command.
Reference
The exportPubKey operation copies the key material to a file that you specify. But it does not remove the key from the HSM, change its key attributes (p. 235), or prevent you from using the key in further cryptographic operations. You can export the same key multiple times.
You can only export public keys that have a OBJ_ATTR_EXTRACTABLE value of 1. To find a key's attributes, use the getAttribute (p. 194) command.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 153) and log in (p. 154) to the HSM as a crypto user (CU).
Syntax
exportPubKey -h
exportPubKey -k <public-key-handle -out <key-file>
Examples
This example shows how to use exportPubKey to export a public key from an HSM.
Example : Export a public key
This command exports a public key with handle 10 to a file called public.pem. When the command succeeds, exportPubKey returns a success message.
Command: exportPubKey -k 10 -out public.pem PEM formatted public key is written to public.pem Cfm3ExportPubKey returned: 0x00 : HSM Return: SUCCESS
Parameters
This command takes the following parameters.
-h
Displays command line help for the command.
Required: Yes -k
Specifies the key handle of the public key to be exported.
Required: Yes -out
Specifies the name of the file to which the exported public key will be written.
Required: Yes
Related topics
• importPubKey (p. 207)
Reference
• Generate Keys (p. 98)
exSymKey
The exSymKey command in the key_mgmt_util tool exports a plaintext copy of a symmetric key from the HSM and saves it in a file on disk. To export an encrypted (wrapped) copy of a key, use wrapKey (p. 232). To import a plaintext key, like the ones that exSymKey exports, use imSymKey (p. 209).
During the export process, exSymKey uses an AES key that you specify (the wrapping key) to wrap (encrypt) and then unwrap (decrypt) the key to be exported. However, the result of the export operation is a plaintext (unwrapped) key on disk.
Only the owner of a key, that is, the CU user who created the key, can export it. Users who share the key can use it in cryptographic operations, but they cannot export it.
The exSymKey operation copies the key material to a file that you specify, but it does not remove the key from the HSM, change its key attributes (p. 235), or prevent you from using the key in cryptographic operations. You can export the same key multiple times.
exSymKey exports only symmetric keys. To export public keys, use exportPubKey (p. 164). To export private keys, use exportPrivateKey (p. 163).
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 153) and log in (p. 154) to the HSM as a crypto user (CU).
Syntax
exSymKey -h
exSymKey -k <key-to-export>
-w <wrapping-key>
-out <key-file>
[-m 4]
[-wk <unwrapping-key-file> ]
Examples
These examples show how to use exSymKey to export symmetric keys that you own from your HSMs.
Example : Export a 3DES symmetric key
This command exports a Triple DES (3DES) symmetric key (key handle 7). It uses an existing AES key (key handle 6) in the HSM as the wrapping key. Then it writes the plaintext of the 3DES key to the 3DES.key file.
The output shows that key 7 (the 3DES key) was successfully wrapped and unwrapped, and then written to the 3DES.key file.
Warning
Although the output says that a "Wrapped Symmetric Key" was written to the output file, the output file contains a plaintext (unwrapped) key.
Command: exSymKey -k 7 -w 6 -out 3DES.key Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS
Reference
Wrapped Symmetric Key written to file "3DES.key"
Example : Exporting with session-only wrapping key
This example shows how to use a key that exists only in the session as the wrapping key. Because the key to be exported is wrapped, immediately unwrapped, and delivered as plaintext, there is no need to retain the wrapping key.
This series of commands exports an AES key with key handle 8 from the HSM. It uses an AES session key created especially for the purpose.
The first command uses genSymKey (p. 189) to create a 256-bit AES key. It uses the -sess parameter to create a key that exists only in the current session.
The output shows that the HSM creates key 262168.
Command: genSymKey -t 31 -s 32 -l AES-wrapping-key -sess Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Created. Key Handle: 262168
Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Next, the example verifies that key 8, the key to be exported, is a symmetric key that is extractable. It also verifies that the wrapping key, key 262168, is an AES key that exists only in the session. You can use the findKey (p. 171) command, but this example exports the attributes of both keys to files and then uses grep to find the relevant attribute values in the file.
These commands use getAttribute with an -a value of 512 (all) to get all attributes for keys 8 and 262168. For information about the key attributes, see the the section called “Key Attribute Reference” (p. 235).
getAttribute -o 8 -a 512 -out attributes/attr_8
getAttribute -o 262168 -a 512 -out attributes/attr_262168
These commands use grep to verify the attributes of the key to be exported (key 8) and the session-only wrapping key (key 262168).
// Verify that the key to be exported is a symmetric key.
$ grep -A 1 "OBJ_ATTR_CLASS" attributes/attr_8 OBJ_ATTR_CLASS
0x04
// Verify that the key to be exported is extractable.
$ grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_8 OBJ_ATTR_EXTRACTABLE
0x00000001
// Verify that the wrapping key is an AES key
$ grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_262168 OBJ_ATTR_KEY_TYPE
0x1f
// Verify that the wrapping key is a session key $ grep -A 1 "OBJ_ATTR_TOKEN" attributes/attr_262168 OBJ_ATTR_TOKEN
Reference
0x00
// Verify that the wrapping key can be used for wrapping $ grep -A 1 "OBJ_ATTR_WRAP" attributes/attr_262168 OBJ_ATTR_WRAP
0x00000001
Finally, we use an exSymKey command to export key 8 using the session key (key 262168) as the wrapping key.
When the session ends, key 262168 no longer exists.
Command: exSymKey -k 8 -w 262168 -out aes256_H8.key Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS
Wrapped Symmetric Key written to file "aes256_H8.key"
Example : Use an external unwrapping key
This example shows how to use an external unwrapping key to export a key from the HSM.
When you export a key from the HSM, you specify an AES key on the HSM to be the wrapping key. By default, that wrapping key is used to wrap and unwrap the key to be exported. However, you can use the -wk parameter to tell exSymKey to use an external key in a file on disk for unwrapping. When you do, the key specified by the -w parameter wraps the target key, and the key in the file specified by the -wk parameter unwraps the key.
Because the wrapping key must be an AES key, which is symmetric, the wrapping key in the HSM and unwrapping key on disk must be have the same key material. To do this, you must import the wrapping key to the HSM or export the wrapping key from the HSM before the export operation.
This example creates a key outside of the HSM and imports it into the HSM. It uses the internal copy of the key to wrap a symmetric key that is being exported, and the copy of key in the file to unwrap it.
The first command uses OpenSSL to generate a 256-bit AES key. It saves the key to the aes256-forImport.key file. The OpenSSL command does not return any output, but you can use several commands to confirm its success. This example uses the wc (wordcount) tool, which confirms that the file that contains 32 bytes of data.
$ openssl rand -out keys/aes256-forImport.key 32
$ wc keys/aes256-forImport.key 0 2 32 keys/aes256-forImport.key
This command uses the imSymKey (p. 209) command to import the AES key from the aes256-forImport.key file to the HSM. When the command completes, the key exists in the HSM with key handle 262167 and in the aes256-forImport.key file.
Command: imSymKey -f keys/aes256-forImport.key -t 31 -l aes256-imported -w 6 Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS
Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS
Reference
Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Unwrapped. Key Handle: 262167 Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
This command uses the key in an export operation. The command uses exSymKey to export key 21, a 192-bit AES key. To wrap the key, it uses key 262167, which is the copy that was imported into the HSM. To unwrap the key, it uses the same key material in the aes256-forImport.key file. When the command completes, key 21 is exported to the aes192_h21.key file.
Command: exSymKey -k 21 -w 262167 -out aes192_H21.key -wk aes256-forImport.key Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Wrapped Symmetric Key written to file "aes192_H21.key"
Parameters
-h
Displays help for the command.
Required: Yes -k
Specifies the key handle of the key to export. This parameter is required. Enter the key handle of a symmetric key that you own. This parameter is required. To find key handles, use the findKey (p. 171) command.
To verify that a key can be exported, use the getAttribute (p. 194) command to get the value of the OBJ_ATTR_EXTRACTABLE attribute, which is represented by constant 354. Also, you can export only keys that you own. To find the owner of a key, use the getKeyInfo (p. 200) command.
Required: Yes -w
Specifies the key handle of the wrapping key. This parameter is required. To find key handles, use the findKey (p. 171) command.
A wrapping key is a key in the HSM that is used to encrypt (wrap) and then decrypt (unwrap) the key to be exported. Only AES keys can be used as wrapping keys.
You can use any AES key (of any size) as a wrapping key. Because the wrapping key wraps, and then immediately unwraps, the target key, you can use as session-only AES key as a wrapping key. To determine whether a key can be used as a wrapping key, use getAttribute (p. 194) to get the value of the OBJ_ATTR_WRAP attribute, which is represented by the constant 262. To create a wrapping key, use genSymKey (p. 189) to create an AES key (type 31).
If you use the -wk parameter to specify an external unwrapping key, the -w wrapping key is used to wrap, but not to unwrap, the key during export.
Note
Key 4 represents an unsupported internal key. We recommend that you use an AES key that you create and manage as the wrapping key.Required: Yes
Reference
-out
Specifies the path and name of the output file. When the command succeeds, this file contains the exported key in plaintext. If the file already exists, the command overwrites it without warning.
Required: Yes -m
Specifies the wrapping mechanism. The only valid value is 4, which represents the NIST_AES_WRAP mechanism.
Required: No Default: 4 -wk
Use the AES key in the specified file to unwrap the key that is being exported. Enter the path and name of a file that contains a plaintext AES key.
When you include this parameter. exSymKey uses the key in the HSM that is specified by the -w parameter to wrap the key that is being exported and it uses the key in the -wk file to unwrap it. The -w and -wk parameter values must resolve to the same plaintext key.
Required: No
Default: Use the wrapping key on the HSM to unwrap.
Related topics
• genSymKey (p. 189)
• imSymKey (p. 209)
• wrapKey (p. 232)
extractMaskedObject
The extractMaskedObject command in key_mgmt_util extracts a key from an HSM and saves it to a file as a masked object. Masked objects are cloned objects that can only be used after inserting them back into the original cluster by using the insertMaskedObject (p. 215) command. You can only insert a masked object into the same cluster from which it was generated, or a clone of that cluster. This includes any cloned versions of the cluster generated by copying a backup across regions (p. 54) and using that backup to create a new cluster (p. 46).
Masked objects are an efficient way to offload and synchronize keys, including nonextractable keys (that is, keys that have a OBJ_ATTR_EXTRACTABLE (p. 235) value of 0). This way, keys can be securely synced across related clusters in different regions without the need to update the AWS CloudHSM configure file (p. 238).
Important
Upon insertion, masked objects are decrypted and given a key handle that is different from the key handle of the original key. A masked object includes all metadata associated with the original key, including attributes, ownership and sharing information, and quorum settings. If you need to sync keys across clusters in an application, use syncKey (p. 148) in the cloudhsm_mgmt_util instead.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 153) and log in (p. 154) to the HSM. The extractMaskedObject command can be used either by the CU who owns the key or any CO.
Reference
Syntax
extractMaskedObject -h
extractMaskedObject -o <object-handle>
-out <object-file>
Examples
This example shows how to use extractMaskedObject to extract a key from an HSM as a masked object.
Example : Extract a masked object
This command extracts a masked object out of an HSM from a key with handle 524295 and saves it as a file called maskedObj. When the command succeeds, extractMaskedObject returns a success message.
Command: extractMaskedObject -o 524295 -out maskedObj Object was masked and written to file "maskedObj"
Cfm3ExtractMaskedObject returned: 0x00 : HSM Return: SUCCESS
Parameters
This command takes the following parameters.
-h
Displays command line help for the command.
Required: Yes -o
Specifies the handle of the key to extract as a masked object.
Required: Yes -out
Specifies the name of the file to which the masked object will be saved.
Specifies the name of the file to which the masked object will be saved.