Export an encrypted copy of a symmetric key or private key from a Hardware Security Module (HSM) to a file.
Prerequisites
Before you begin, ensure that you have:
Started
key_mgmt_toolLogged in to HSM as a Crypto User (CU)
Ownership of the key to export — only the CU who created the key can export it; users with shared access can use the key for encryption but cannot export it
Syntax
wrapKey -k <exported-key-handle>
-w <wrapping-key-handle>
-out <output-file>
[-m <wrapping-mechanism>]
[-t <hash-type>]
[-noheader]
[-i <wrapping IV>]
[-iv_file <IV file>]
[-tag_size <num_tag_bytes>]Important
Enter parameters in the order shown above.
Example
Export an RSA asymmetric key (handle 8) encrypted with an AES key (handle 6) to a file:
wrapKey -k 8 -w 6 -out aes-encrypted.key -m 4Expected output:
Cfm2WrapKey5 returned: 0x00 : HSM Return: SUCCESS
Key Wrapped.
Wrapped Key written to file "aes-encrypted.key" length 1516Parameters
| Parameter | Required | Description | Valid values |
|---|---|---|---|
-k | Yes | Handle of the symmetric or private key to export. | — |
-w | Yes | Handle of the wrapping key. | — |
-out | Yes | Path and name of the output file. | — |
-m | Yes | Wrapping mechanism. See Wrapping mechanisms below. | 4–11 |
-t | No | Hash algorithm. | 2: SHA1 / 3: SHA-256 / 4: SHA-384 / 5: SHA-512 / 6: SHA224 (RSA_AES and RSA_OAEP only) |
-noheader | No | Omit the header that contains key properties from the output. | — |
-i | No | Initialization vector (IV). Applies only with -noheader for CLOUDHSM_AES_KEY_WRAP and NIST_AES_WRAP mechanisms. | — |
-iv_file | No | Path to a file containing the initialization vector (IV). Applies only with -noheader for the AES_GCM mechanism. | — |
-tag_size | No | Block size for the operation. Applies only with -noheader for AES_GCM and CLOUDHSM_AES_GCM mechanisms. | Minimum: 8 |
Wrapping mechanisms
| Value | Mechanism |
|---|---|
4 | AES_KEY_WRAP_PAD_PKCS5 |
5 | NIST_AES_WRAP_NO_PAD |
6 | NIST_AES_WRAP_PAD |
7 | RSA_AES |
8 | RSA_OAEP |
9 | NIST_TDEA_WRAP |
10 | AES_GCM |
11 | CLOUDHSM_AES_GCM |
What's next
To re-import an encrypted key into HSM, use unWrapKey.
To export a key in plaintext, use exSymKey for symmetric keys or exportPrivateKey for private keys.