Syntax Example Parameters Related topics

Export an AWS CloudHSM key using KMU

Use the wrapKey command in the AWS CloudHSM key_mgmt_util to export an encrypted copy of a symmetric or private key from the hardware security module (HSM) to a file. When you run wrapKey, you specify the key to export, a key on the HSM to encrypt (wrap) the key that you want to export, and the output file.

The wrapKey command writes the encrypted key to a file that you specify, but it does not remove the key from the HSM or prevent you from using it in cryptographic operations. You can export the same key multiple times.

Only the owner of a key, that is, the crypto user (CU) who created the key, can export it. Users who share the key can use it in cryptographic operations, but they cannot export it.

To import the encrypted key back into the HSM, use unWrapKey. To export a plaintext key from an HSM, use exSymKey or exportPrivateKey as appropriate. The aesWrapUnwrap command cannot decrypt (unwrap) keys that wrapKey encrypts.

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


wrapKey -h

wrapKey -k <exported-key-handle>
        -w <wrapping-key-handle>
        -out <output-file>
        [-m <wrapping-mechanism>]
        [-aad <additional authenticated data filename>]
        [-t <hash-type>]
        [-noheader]
        [-i <wrapping IV>]  
        [-iv_file <IV file>]
        [-tag_size <num_tag_bytes>>]

Example

This command exports a 192-bit Triple DES (3DES) symmetric key (key handle 7). It uses a 256-bit AES key in the HSM (key handle 14) to wrap key 7. Then, it writes the encrypted 3DES key to the 3DES-encrypted.key file.

The output shows that key 7 (the 3DES key) was successfully wrapped and written to the specified file. The encrypted key is 307 bytes long.


        Command:  wrapKey -k 7 -w 14 -out 3DES-encrypted.key -m 4

        Key Wrapped.

        Wrapped Key written to file "3DES-encrypted.key length 307

        Cfm2WrapKey returned: 0x00 : HSM Return: SUCCESS

Parameters

-h

Displays help for the command.

Required: Yes

-k

The key handle of the key that you want to export. Enter the key handle of a symmetric or private key that you own. To find key handles, use the findKey command.

To verify that a key can be exported, use the getAttribute command to get the value of the OBJ_ATTR_EXTRACTABLE attribute, which is represented by constant 354. For help interpreting the key attributes, see the AWS CloudHSM key attribute reference for KMU.

You can export only those keys that you own. To find the owner of a key, use the getKeyInfo command.

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

-out

The path and name of the output file. When the command succeeds, this file contains an encrypted copy of the exported key. If the file already exists, the command overwrites it without warning.

Required: Yes

-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

The value representing the hash algorithm. CloudHSM supports the following algorithms:

Hash algorithm	Value
`SHA1`	2
`SHA256`	3
`SHA384`	4
`SHA512`	5
`SHA224` (valid for `RSA_AES` and `RSA_OAEP` mechanisms)	6

Required: No

-aad

The file name containing AAD.

Note

Valid only for AES_GCM and CLOUDHSM_AES_GCM mechanisms.

Required: No

-noheader

Omits the header that specifies CloudHSM-specific key attributes. Use this parameter only if you want to unwrap the key with tools outside of key_mgmt_util.

Required: No

-i

The initialization vector (IV) (hex value).

Note

Valid only when passed with the -noheader parameter for CLOUDHSM_AES_KEY_WRAP, and NIST_AES_WRAP mechanisms.

Required: No

-iv_file

The file in which you want to write the IV value obtained in response.

Note

Valid only when passed with the -noheader parameter for AES_GCM mechanism.

Required: No

-tag_size

The size of tag to be saved along with wrapped blob.

Note

Valid only when passed with the -noheader parameter for AES_GCM and CLOUDHSM_AES_GCM mechanisms. Minimum tag size is eight.

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.