Use the unWrapKey command in the AWS CloudHSM key_mgmt_util tool to import a wrapped (encrypted) symmetric or private key from a file into the HSM. It is designed to import encrypted keys that were wrapped by the wrapKey command in key_mgmt_util, but it can also be used to unwrap keys that were wrapped with other tools. However, in those situations, we recommend using the PKCS#11 or JCE software libraries to unwrap the key.
Imported keys work like keys generated by AWS CloudHSM. However, the value of their OBJ_ATTR_LOCAL attribute is zero, which indicates that they were not generated locally.
After you import a key, ensure that you mark or delete the key file. This command does not prevent you from importing the same key material multiple times. The results—multiple keys with distinct key handles and the same key material—make it difficult to track use of the key materials and prevent them from exceeding their cryptographic limits.
Before you run any key_mgmt_util command, you must start key_mgmt_util and log in to the HSM as a crypto user (CU).
Syntax
unWrapKey -h unWrapKey -f<key-file-name>-w<wrapping-key-handle>[-sess] [-min_srv<minimum-number-of-HSMs>] [-timeout<number-of-seconds>] [-aad<additional authenticated data filename>] [-tag_size<tag size>] [-iv_file<IV file>] [-attest] [-m<wrapping-mechanism>] [-t<hash-type>] [-nex] [-u<user id list>] [-m_value<number of users needed for approval>] [-noheader] [-l<key-label>] [-id<key-id>] [-kt<key-type>] [-kc<key-class] [-i<unwrapping-IV>]
Example
These examples show how to use unWrapKey to import a wrapped key from a file into the HSMs. In the first example, we unwrap a key that was wrapped with the wrapKey key_mgmt_util command, and thus has a header. In the second example, we unwrap a key that was wrapped outside of key_mgmt_util, and thus does not have a header.
Example : Unwrap a key (with header)
This command imports a wrapped copy of a 3DES symmetric key into an HSM. The key is
unwrapped with an AES key with label 6, which is cryptographically identical to
the one that was used to wrap the 3DES key. The output shows that the key in the file was
unwrapped and imported, and that the imported key's handle is 29.
Command:unWrapKey -f 3DES.key -w 6 -m 4Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Key Unwrapped. Key Handle: 29 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Example : Unwrap a key (no header)
This command imports a wrapped copy of a 3DES symmetric key into an HSM. The key is
unwrapped with an AES key with label 6, which is cryptographically identical to
the one that was used to wrap the 3DES key. As this 3DES key was not wrapped with key_mgmt_util, the
noheader parameter is specified, along with its required accompanying
parameters: a key label (unwrapped3DES), key class (4), and key
type (21). The output shows that the key in the file was unwrapped and
imported, and that the imported key's handle is 8.
Command:unWrapKey -f 3DES.key -w 6 -noheader -l unwrapped3DES -kc 4 -kt 21 -m 4Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS Cfm2UnWrapWithTemplate3 returned: 0x00 : HSM Return: SUCCESS Key Unwrapped. Key Handle: 8 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Parameters
- -h
-
Displays help for the command.
Required: Yes
- -f
-
The path and name of the file that contains the wrapped key.
Required: Yes
- -w
-
Specifies the wrapping key. Enter the key handle of an AES key or RSA key on the HSM. This parameter is required. To find key handles, use the findKey command.
To create a wrapping key, use genSymKey to generate an AES key (type 31) or genRSAKeyPair to generate an RSA key pair (type 0). If you are using an RSA key pair, be sure to wrap the key with one of the keys, and unwrap it with the other. To verify that a key can be used as a wrapping key, use getAttribute to get the value of the
OBJ_ATTR_WRAPattribute, which is represented by constant262.Required: Yes
- -sess
-
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.
To change a session key to a persistent (token) key, use setAttribute.
Default: The key is persistent.
Required: No
- -min_srv
-
Specifies the minimum number of HSMs on which the key is synchronized before the value of the
-timeoutparameter expires. If the key is not synchronized to the specified number of servers in the time allotted, it is not created.AWS CloudHSM automatically synchronizes every key to every HSM in the cluster. To speed up your process, set the value of
min_srvto less than the number of HSMs in the cluster and set a low timeout value. Note, however, that some requests might not generate a key.Default: 1
Required: No
- -timeout
-
Specifies how long (in seconds) the command waits for a key to be synchronized to the number of HSMs specified by the
min_srvparameter.This parameter is valid only when the
min_srvparameter is also used in the command.Default: No timeout. The command waits indefinitely and returns only when the key is synchronized to the minimum number of servers.
Required: No
- -attest
Runs an integrity check that verifies that the firmware on which the cluster runs has not been tampered with.
Default: No attestation check.
Required: No
- -nex
-
Makes the key nonextractable. The key that is generated cannot be exported from the HSM.
Default: The key is extractable.
Required: No
- -m
-
The value representing the wrapping mechanism. CloudHSM supports the following mechanisms:
Mechanism Value AES_KEY_WRAP_PAD_PKCS54 NIST_AES_WRAP_NO_PAD5 NIST_AES_WRAP_PAD6 RSA_AES7 RSA_OAEP(for maximum data size, see the note later in this section)8 AES_GCM10 CLOUDHSM_AES_GCM11 RSA_PKCS(for maximum data size, see the note later in this section). See note 1 below for an upcoming change.12 Required: Yes
Note
When using the
RSA_OAEPwrapping mechanism, the maximum key size that you can wrap is determined by the modulus of the RSA key and the length of the specified hash as follows: Maximum key size = modulusLengthInBytes-(2*hashLengthInBytes)-2.When using the RSA_PKCS wrapping mechanism, the maximum key size that you can wrap is determined by the modulus of the RSA key as follows: Maximum key size = (modulusLengthInBytes -11).
- -t
-
Hash algorithm Value SHA12 SHA2563 SHA3844 SHA5125 SHA224(valid forRSA_AESandRSA_OAEPmechanisms)6 Required: No
- -noheader
-
If you are unwrapping a key that was wrapped outside of key_mgmt_util, you must specify this parameter and all other associated parameters.
Required: No
Note
If you specify this parameter, you must also specify the following
-noheaderparameters:-
-l
Specifies the label to be added to the unwrapped key.
Required: Yes
-
-kc
Specifies the class of the key to be unwrapped. The following are acceptable values:
3 = private key from a public-private key pair
4 = secret (symmetric) key
Required: Yes
-
-kt
Specifies the type of key to be unwrapped. The following are acceptable values:
0 =
RSA1 =
DSA3 =
ECC16 =
GENERIC_SECRET21 =
DES331 =
AESRequired: Yes
You can also optionally specify the following
-noheaderparameters:-
-id
The ID to be added to the unwrapped key.
Required: No
-
-i
The unwrapping initialization vector (IV) to be used.
Required: No
-
[1] In accordance with NIST guidance, this is disallowed for clusters in FIPS mode after 2023. For clusters in non-FIPS mode, it is still allowed after 2023. See FIPS 140 Compliance: 2024 Mechanism Deprecation for details.
Related topics
