Copy a key between HSMs - Cloud Hardware Security Module (HSM)

If you want to copy a key from a hardware security module (HSM) to another HSM, you can export the key from the source HSM and then import the key to the destination HSM. This topic describes how to copy a key between two HSMs.

Applicable HSM types

General virtual security modules (GVSMs) that are validated by Federal Information Processing Standards (FIPS)

Scenarios

You can copy keys in scenarios when two HSMs do not belong to the same cluster and automatic key synchronization is not supported.

Note

If two HSMs belong to the same cluster, keys in the cluster are automatically synchronized. You do not need to copy the keys.

Prerequisites

Tools

The key_mgmt_tool CLI is required. For more information, see key_mgmt_tool.

Before you perform the operations that are described in this topic, make sure that you are logged on to a crypto user (CU) by using key_mgmt_tool. The following sample code shows the required command.

Note

Replace /opt/hsm/bin/key_mgmt_tool with the actual path.
Replace <yourCuUserName> and <yourCuUserPassword> with the actual username and password of the CU.

$/opt/hsm/bin/key_mgmt_tool 
Command: loginHSM -u CU -s <yourCuUserName> -p <yourCuUserPassword>

Copy a symmetric key

In this example, a symmetric key in HSM A is copied to HSM B.

The symmetric key uses the Advanced Encryption Standard (AES) algorithm and is 256 bits in length.
The wrapping key uses the Rivest–Shamir–Adleman (RSA) algorithm and is 2,048 bits in length. The public exponent is 65537.
During the export of the symmetric key, RSA_OAEP (SHA-256)-based wrapping and unwrapping are used.

In HSM B, create and export a wrapping key.
1. Run the genRSAKeyPair command to generate an RSA key as the wrapping key.
```
Command:  genRSAKeyPair -m 2048 -e 65537 -l rsa_wrapping_key
```
  Parameter
  Description
  -m
  The key length.
  -e
  The public exponent. The value must be an odd number within the range of 65537 to 2^31-1.
  -l
  The key tag.
  Expected output:
```
	Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
  Cfm3GenerateKeyPair:    public key handle: 33    private key handle: 32
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS
```
2. Run the exportPubKey command to export the public key of the RSA key.
```
Command:  exportPubKey -k 33 -out rsa_wrapping_key.pub 
```
  Parameter
  Description
  -k
  The identity of the public key.
  -out
  The file name of the exported public key.
  Expected output:
```
	PEM formatted public key is written to rsa_wrapping_key.pub
	Cfm3ExportPubKey returned: 0x00 : HSM Return: SUCCESS
```

In HSM A, use the public key that is exported from HSM B to wrap the symmetric key that you want to copy.

Run the genSymKey command to generate a symmetric key. If a symmetric key already exists, skip this step.

Command:  genSymKey -t 31 -s 32 -l mySymmetricKey

Parameter	Description
-t	The key type. Valid values: 16: GENERIC_SECRET 21: 3DES 31: AES
-s	The key length. Unit: bytes. For a key of the AES type, set the value to 16, 24, or 32. For a key of the 3DES type, set the value to 24. For a key of the GENERIC_SECRET type, specify a value that is less than or equal to 800.
-l	The key tag.

Expected output:

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
	Symmetric Key Created.  Key Handle: 29
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Run the importPubKey command to import the public key that is obtained from HSM B.
```
Command:  importPubKey -sess -l rsa_pub_key -f rsa_wrapping_key.pub
```
Parameter
Description
-sess
Specifies that the key is a session key. A session key is intended for temporary use rather than for prolonged storage.
-l
The key tag.
-f
The file name of the public key.
Expected output:
```
	Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS
  Public Key Handle: 28 
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS
```

Run the wrapKey command to wrap the symmetric key by using the public key and save the wrapped symmetric key to a file.

Command:  wrapKey -k 29 -w 28 -m 8 -t 3 -out symmetric_key_wrapped_with_rsa.wrap

Parameter	Description
-k	The identifier of the key that you want to wrap.
-w	The identifier of the wrapping key.
-m	The wrapping method. Valid values: 0: AES_CBC_PAD (If -noheader is specified, the initial vector is required.) 1: AES_CBC (If -noheader is specified, the initial vector is required.) 4: CLOUDHSM_AES_KEY_WRAP 5: NIST_AES_WRAP_NO_PAD (The key length must be a multiple of 8 in bytes.) 6 (default): NIST_AES_WRAP_PAD 7: RSA_AES 8: RSA_OAEP (The key length must be less than or equal to the calculation result of the following formula: Mod_len - 2 × Hash_len - 2. The unit is bytes.) 9: NIST_TDEA_WRAP (The key length must be a multiple of 4 in bytes.) 10: AES_GCM 11: CLOUDHSM_AES_GCM 12: RSA_PKCS (The key length must be less than or equal to the calculation result of the following formula: Mod_len - 11. The unit is bytes.)
-t	The hash type. If you set the -m parameter to 7 or 8, this parameter is required. Valid values: 2 (default): SHA-1 3: SHA-256 4: SHA-384 5: SHA-512 6: SHA-224
-out	The name of the file that stores the wrapped key.

Expected output:

	Cfm2WrapKey5 returned: 0x00 : HSM Return: SUCCESS
	Key Wrapped.
	Wrapped Key written to file "symmetric_key_wrapped_with_rsa.wrap" length 525

In HSM B, run the unWrapKey command to unwrap the wrapped symmetric key by using the private key of the RSA key. Then, save the unwrapped symmetric key to HSM B.

Command:  unWrapKey  -f symmetric_key_wrapped_with_rsa.wrap -w 32 -m 8 -t 3

Parameter	Description
-f	The file name of the wrapped key.
-w	The identifier of the wrapping key.
-m	The wrapping method. Valid values: 0: AES_CBC_PAD (If -noheader is specified, the initial vector is required.) 1: AES_CBC (If -noheader is specified, the initial vector is required.) 4: CLOUDHSM_AES_KEY_WRAP 5: NIST_AES_WRAP_NO_PAD 6 (default): NIST_AES_WRAP_PAD 7: RSA_AES 8: RSA_OAEP 9: NIST_TDEA_WRAP 10: AES_GCM 11: CLOUDHSM_AES_GCM 12: RSA_PKCS
-t	The hash type. If you set the -m parameter to 7 or 8, this parameter is required. Valid values: 2 (default): SHA-1 3: SHA-256 4: SHA-384 5: SHA-512 6: SHA-224

	Cfm2UnWrapKey5 returned: 0x00 : HSM Return: SUCCESS
	Key Unwrapped.  Key Handle: 31 
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Copy an asymmetric key

In this example, an asymmetric key in HSM A is copied to HSM B.

The asymmetric key is an EC secp256k1 key.
The wrapping key uses the RSA algorithm and is 2,048 bits in length. The public exponent is 65537.
During the export of the asymmetric key, RSA_OAEP (SHA-256)-based wrapping and unwrapping are used.

In HSM B, create and export a wrapping key.
1. Run the genRSAKeyPair command to generate an RSA key as the wrapping key.
```
Command:  genRSAKeyPair -m 2048 -e 65537 -l rsa_wrapping_key
```
  Parameter
  Description
  -m
  The key length.
  -e
  The public exponent. The value must be an odd number within the range of 65537 to 2^31-1.
  -l
  The key tag.
  Expected output:
```
	Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
  Cfm3GenerateKeyPair:    public key handle: 33    private key handle: 32
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS
```
2. Run the exportPubKey command to export the public key of the RSA key.
```
Command:  exportPubKey -k 33 -out rsa_wrapping_key.pub 
```
  Parameter
  Description
  -k
  The identity of the public key.
  -out
  The file name of the exported public key.
  Expected output:
```
	PEM formatted public key is written to rsa_wrapping_key.pub
	Cfm3ExportPubKey returned: 0x00 : HSM Return: SUCCESS
```

In HSM A, use the public key that is exported from HSM B to wrap the asymmetric key that you want to copy.

Run the genECCKeyPair command to generate an asymmetric key. If an asymmetric key already exists, skip this step.

Command:   genECCKeyPair -i 16 -l  secp256k1_key

Parameter	Description
-i	The ECC curve. Valid values: 1 to 16.
-l	The key tag.

Expected output:

	Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
	Cfm3GenerateKeyPair:    public key handle: 29    private key handle: 28
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Run the importPubKey command to import the public key that is obtained from HSM B.
```
Command:  importPubKey -sess -l rsa_pub_key -f rsa_wrapping_key.pub
```
Parameter
Description
-sess
Specifies that the key is a session key. A session key is intended for temporary use rather than for prolonged storage.
-l
The key tag.
-f
The file name of the public key.
Expected output:
```
	Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS
  Public Key Handle: 31 
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS
```

Run the wrapKey command to wrap the private key of the asymmetric key by using the imported public key.

Command:  wrapKey -k 28 -w 31 -m 8 -t 3 -out secp256k1_key_wrapped_with_rsa.wrap

Parameter	Description
-k	The identifier of the key that you want to wrap.
-w	The identifier of the wrapping key.
-m	The wrapping method. Valid values: 0: AES_CBC_PAD (If -noheader is specified, the initial vector is required.) 1: AES_CBC (If -noheader is specified, the initial vector is required.) 4: CLOUDHSM_AES_KEY_WRAP 5: NIST_AES_WRAP_NO_PAD (The key length must be a multiple of 8 in bytes.) 6 (default): NIST_AES_WRAP_PAD 7: RSA_AES 8: RSA_OAEP (The key length must be less than or equal to the calculation result of the following formula: Mod_len - 2 × Hash_len - 2. The unit is bytes.) 9: NIST_TDEA_WRAP (The key length must be a multiple of 4 in bytes.) 10: AES_GCM 11: CLOUDHSM_AES_GCM 12: RSA_PKCS (The key length must be less than or equal to the calculation result of the following formula: Mod_len - 11. The unit is bytes.)
-t	The hash type. If you set the -m parameter to 7 or 8, this parameter is required. Valid values: 2 (default): SHA-1 3: SHA-256 4: SHA-384 5: SHA-512 6: SHA-224
-out	The name of the file that stores the wrapped key.

Expected output:

	Cfm2WrapKey5 returned: 0x00 : HSM Return: SUCCESS
	Key Wrapped.
	Wrapped Key written to file "secp256k1_key_wrapped_with_rsa.wrap" length 515

Run the exportPubKey command to export the public key of the asymmetric key.
```
Command:  exportPubKey -k 29 -out secp256k1_key.pub 
```
Parameter
Description
-k
The identity of the public key.
-out
The file name of the exported public key.
Expected output:
```
	PEM formatted public key is written to secp256k1_key.pub
	Cfm3ExportPubKey returned: 0x00 : HSM Return: SUCCESS
```

In HSM B, unwrap the wrapped private key of the asymmetric key and then import the public key of the asymmetric key.

Run the unWrapKey command to unwrap the wrapped private key of the asymmetric key by using the private key of the RSA key.

Command:  unWrapKey  -f secp256k1_key_wrapped_with_rsa.wrap -w 32 -m 8 -t 3

Parameter	Description
-f	The file name of the wrapped key.
-w	The identifier of the wrapping key.
-m	The wrapping method. Valid values: 0: AES_CBC_PAD (If -noheader is specified, the initial vector is required.) 1: AES_CBC (If -noheader is specified, the initial vector is required.) 4: CLOUDHSM_AES_KEY_WRAP 5: NIST_AES_WRAP_NO_PAD 6 (default): NIST_AES_WRAP_PAD 7: RSA_AES 8: RSA_OAEP 9: NIST_TDEA_WRAP 10: AES_GCM 11: CLOUDHSM_AES_GCM 12: RSA_PKCS
-t	The hash type. If you set the -m parameter to 7 or 8, this parameter is required. Valid values: 2 (default): SHA-1 3: SHA-256 4: SHA-384 5: SHA-512 6: SHA-224

Expected output:

	Cfm2UnWrapKey5 returned: 0x00 : HSM Return: SUCCESS
	Key Unwrapped.  Key Handle: 27 
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Run the importPubKey command to import the public key of the asymmetric key.
```
Command:  importPubKey -l secp256k1_key_pub_imported -f secp256k1_key.pub
```
Expected output:
Parameter
Description
-sess
Specifies that the key is a session key. A session key is intended for temporary use rather than for prolonged storage.
-l
The key tag.
-f
The file name of the public key.
```
	Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS
Public Key Handle: 26 
	Cluster Status:
	Node id 0 status: 0x00000000 : HSM Return: SUCCESS
```

Parameter	Description
-m	The key length.
-e	The public exponent. The value must be an odd number within the range of 65537 to 2^31-1.
-l	The key tag.

Parameter	Description
-k	The identity of the public key.
-out	The file name of the exported public key.

Parameter	Description
-sess	Specifies that the key is a session key. A session key is intended for temporary use rather than for prolonged storage.
-l	The key tag.
-f	The file name of the public key.