# Unwrap an AWS CloudHSM key using KMU Use the **unWrapKey** command in the AWS CloudHSM key\$1mgmt\$1util 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](key_mgmt_util-wrapKey.md) command in key\$1mgmt\$1util, but it can also be used to unwrap keys that were wrapped with other tools. However, in those situations, we recommend using the [PKCS\$111](pkcs11-library.md) or [JCE](java-library.md) software libraries to unwrap the key. Imported keys work like keys generated by AWS CloudHSM. However, the value of their [OBJ\$1ATTR\$1LOCAL attribute](key-attribute-table.md) 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\$1mgmt\$1util command, you must [start key\$1mgmt\$1util](key_mgmt_util-setup.md#key_mgmt_util-start) and [log in](key_mgmt_util-log-in.md) to the HSM as a crypto user (CU). ## Syntax ``` unWrapKey -h unWrapKey -f -w [-sess] [-min_srv ] [-timeout ] [-aad ] [-tag_size ] [-iv_file ] [-attest] [-m ] [-t ] [-nex] [-u ] [-m_value ] [-noheader] [-l ] [-id ] [-kt ] [-kc ] [-i ] ``` ## 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-wrapKey.md)** key\$1mgmt\$1util command, and thus has a header. In the second example, we unwrap a key that was wrapped outside of key\$1mgmt\$1util, 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 4 Cfm3UnWrapKey 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\$1mgmt\$1util, 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 4 Cfm3CreateUnwrapTemplate2 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](key_mgmt_util-findKey.md) command. To create a wrapping key, use [genSymKey](key_mgmt_util-genSymKey.md) to generate an AES key (type 31) or [genRSAKeyPair](key_mgmt_util-genRSAKeyPair.md) 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](key_mgmt_util-getAttribute.md) to get the value of the `OBJ_ATTR_WRAP` attribute, which is represented by constant `262`. 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](key_mgmt_util-setAttribute.md). Default: The key is persistent. Required: No **-min\$1srv** Specifies the minimum number of HSMs on which the key is synchronized before the value of the `-timeout` parameter 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_srv` to 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_srv` parameter. This parameter is valid only when the `min_srv` parameter 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](export-keys.md). Default: The key is extractable. Required: No **-m** The value representing the wrapping mechanism. CloudHSM supports the following mechanisms: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-unwrapKey.html) Required: Yes When using the `RSA_OAEP` wrapping 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\$1hashLengthInBytes)-2. When using the RSA\$1PKCS 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** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-unwrapKey.html) Required: No **-noheader** If you are unwrapping a key that was wrapped outside of key\$1mgmt\$1util, you must specify this parameter and all other associated parameters. Required: No If you specify this parameter, you **must** also specify the following `-noheader` parameters: + **-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 = `RSA` 1 = `DSA` 3 = `ECC` 16 = `GENERIC_SECRET` 21 = `DES3` 31 = `AES` Required: Yes You can also **optionally** specify the following `-noheader` parameters: + **-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](compliance-dep-notif.md#compliance-dep-notif-1) for details. ## Related topics + [wrapKey](key_mgmt_util-wrapKey.md) + [exSymKey](key_mgmt_util-exSymKey.md) + [imSymKey](key_mgmt_util-imSymKey.md)