unWrapKey - AWS CloudHSM

unWrapKey

The unWrapKey command in the key_mgmt_util tool imports 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 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_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 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 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_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.

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 -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.

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_PKCS5 4
NIST_AES_WRAP_NO_PAD 5
NIST_AES_WRAP_PAD 6
RSA_AES 7
RSA_OAEP (for maximum data size, see the note later in this section) 8
AES_GCM 10
CLOUDHSM_AES_GCM 11
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_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*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
SHA1 2
SHA256 3
SHA384 4
SHA512 5
SHA224 (valid for RSA_AES and RSA_OAEP mechanisms) 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 -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] Disallowed after 2023 for FIPS compliance as per NIST guidance. See FIPS 140 Compliance: 2024 Mechanism Deprecation for details.

Related topics