# Key management with the AWS CloudHSM KMU If using the [latest SDK version series](use-hsm.md), use [CloudHSM CLI](cloudhsm_cli.md) to manage the keys in your AWS CloudHSM cluster. If using the [previous SDK version series](choose-client-sdk.md), you can manage keys on the hardware security modules (HSM) in your AWS CloudHSM cluster using the key\$1mgmt\$1util (KMU) command line tool. Before you can manage keys, you must start the AWS CloudHSM client, start key\$1mgmt\$1util, and log in to the HSMs. For more information, see [Getting Started with key\$1mgmt\$1util](key_mgmt_util-getting-started.md). + [Using trusted keys](cloudhsm_using_trusted_keys_control_key_wrap.md) describes how to use PKCS \$111 library attributes and CMU to create trusted keys to secure data. + [Generating keys](generate-keys.md) has instructions on generating keys, including symmetric keys, RSA keys, and EC keys. + [Importing keys](import-keys.md) provides details on how key owners import keys. + [Exporting keys](export-keys.md) provides details on how key owners export keys. + [Deleting keys](delete-keys.md) provides details on how key owners delete keys. + [Sharing and unsharing keys](share-keys.md) details how key owners share and unshare keys. # Generate keys with the AWS CloudHSM KMU To generate keys on the hardware security module (HSM), use the command in AWS CloudHSM key\$1mgmt\$1util (KMU) that corresponds to the type of key that you want to generate. **Topics** + [Generate symmetric keys](generate-symmetric-keys.md) + [Generate RSA key pairs](generate-rsa-key-pairs.md) + [Generate ECC (elliptic curve cryptography) key pairs](generate-ecc-key-pairs.md) # Generate symmetric keys with the AWS CloudHSM KMU Use the [genSymKey](key_mgmt_util-genSymKey.md) command in AWS CloudHSM key\$1mgmt\$1util (KMU) to generate AES and other types of symmetric keys for AWS CloudHSM. To see all available options, use the **genSymKey -h** command. The following example creates a 256-bit AES key. ``` Command: genSymKey -t 31 -s 32 -l aes256 Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Created. Key Handle: 524295 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` # Generate RSA key pairs with the AWS CloudHSM KMU To generate an RSA key pair for AWS CloudHSM, use the [genRSAKeyPair](key_mgmt_util-genRSAKeyPair.md) command in AWS CloudHSM key\$1mgmt\$1util. To see all available options, use the **genRSAKeyPair -h** command. The following example generates an RSA 2048-bit key pair. ``` Command: genRSAKeyPair -m 2048 -e 65537 -l rsa2048 Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS Cfm3GenerateKeyPair: public key handle: 524294 private key handle: 524296 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` # Generate ECC (elliptic curve cryptography) key pairs using the AWS CloudHSM KMU To generate an ECC key pair for AWS CloudHSM, use the [genECCKeyPair](key_mgmt_util-genECCKeyPair.md) command in AWS CloudHSM key\$1mgmt\$1util. To see all available options, including a list of the supported elliptic curves, use the **genECCKeyPair -h** command. The following example generates an ECC key pair using the P-384 elliptic curve defined in [NIST FIPS publication 186-4](http://dx.doi.org/10.6028/NIST.FIPS.186-4). ``` Command: genECCKeyPair -i 14 -l ecc-p384 Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS Cfm3GenerateKeyPair: public key handle: 524297 private key handle: 524298 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` # Import keys with the AWS CloudHSM KMU To import secret keys—that is, symmetric keys and asymmetric private keys—into the hardware security module (HSM) using the AWS CloudHSM key\$1mgmt\$1util, you must first create a wrapping key on the HSM. You can import public keys directly without a wrapping key. **Topics** + [Import secret keys](import-secret-keys.md) + [Import public keys](import-public-keys.md) # Import secret keys with the AWS CloudHSM KMU Complete the following steps to import a secret key into AWS CloudHSM using the key\$1mgmt\$1util (KMU). Before you import a secret key, save it to a file. Save symmetric keys as raw bytes, and asymmetric private keys in PEM format. This example shows how to import a plaintext secret key from a file into the HSM. To import an encrypted key from a file into the HSM, use the [unWrapKey](key_mgmt_util-unwrapKey.md) command. **To import a secret key** 1. Use the [genSymKey](key_mgmt_util-genSymKey.md) command to create a wrapping key. The following command creates a 128-bit AES wrapping key that is valid only for the current session. You can use a session key or a persistent key as a wrapping key. ``` Command: genSymKey -t 31 -s 16 -sess -l import-wrapping-key Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Created. Key Handle: 524299 Cluster Error Status Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` 1. Use one of the following commands, depending on the type of secret key that you are importing. + To import a symmetric key, use the [imSymKey](key_mgmt_util-imSymKey.md) command. The following command imports an AES key from a file named `aes256.key` using the wrapping key created in the previous step. To see all available options, use the **imSymKey -h** command. ``` Command: imSymKey -f aes256.key -t 31 -l aes256-imported -w 524299 Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Unwrapped. Key Handle: 524300 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` + To import an asymmetric private key, use the [importPrivateKey](key_mgmt_util-importPrivateKey.md) command. The following command imports a private key from a file named `rsa2048.key` using the wrapping key created in the previous step. To see all available options, use the **importPrivateKey -h** command. ``` Command: importPrivateKey -f rsa2048.key -l rsa2048-imported -w 524299 BER encoded key length is 1216 Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Private Key Unwrapped. Key Handle: 524301 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` # Import public keys with the AWS CloudHSM KMU Use the [importPubKey](key_mgmt_util-importPubKey.md) command in the AWS CloudHSM key\$1mgmt\$1util (KMU) to import a public key. To see all available options, use the **importPubKey -h** command. The following example imports an RSA public key from a file named `rsa2048.pub`. ``` Command: importPubKey -f rsa2048.pub -l rsa2048-public-imported Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS Public Key Handle: 524302 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` # Export keys with the AWS CloudHSM KMU To export AWS CloudHSM secret keys—that is, symmetric keys and asymmetric private keys—from the hardware security module (HSM) using the AWS CloudHSM key\$1mgmt\$1util (KMU), you must first create a wrapping key. You can export public keys directly without a wrapping key. Only the key owner can export a key. Users with whom the key is shared can use the key in cryptographic operations, but they cannot export it. When running this example, be sure to export a key that you created. **Important** The [exSymKey](key_mgmt_util-exSymKey.md) command writes a plaintext (unencrypted) copy of the secret key to a file. The export process requires a wrapping key, but the key in the file is ***not*** a wrapped key. To export a wrapped (encrypted) copy of a key, use the [wrapKey](key_mgmt_util-wrapKey.md) command. **Topics** + [Export secret keys](export-secret-keys.md) + [Export public keys](export-public-keys.md) # Export secret keys with the AWS CloudHSM KMU Complete the following steps to export a secret key from AWS CloudHSM using the key\$1mgmt\$1util (KMU). **To export a secret key** 1. Use the [genSymKey](key_mgmt_util-genSymKey.md) command to create a wrapping key. The following command creates a 128-bit AES wrapping key that is valid only for the current session. ``` Command: genSymKey -t 31 -s 16 -sess -l export-wrapping-key Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Created. Key Handle: 524304 Cluster Error Status Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` 1. Use one of the following commands, depending on the type of secret key that you are exporting. + To export a symmetric key, use the [exSymKey](key_mgmt_util-exSymKey.md) command. The following command exports an AES key to a file named `aes256.key.exp`. To see all available options, use the **exSymKey -h** command. ``` Command: exSymKey -k 524295 -out aes256.key.exp -w 524304 Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS Wrapped Symmetric Key written to file "aes256.key.exp" ``` **Note** The command's output says that a "Wrapped Symmetric Key" is written to the output file. However, the output file contains a plaintext (not wrapped) key. To export a wrapped (encrypted) key to a file, use the [wrapKey](key_mgmt_util-wrapKey.md) command. + To export a private key, use the **exportPrivateKey** command. The following command exports a private key to a file named `rsa2048.key.exp`. To see all available options, use the **exportPrivateKey -h** command. ``` Command: exportPrivateKey -k 524296 -out rsa2048.key.exp -w 524304 Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS PEM formatted private key is written to rsa2048.key.exp ``` # Export public keys with the AWS CloudHSM KMU Use the **exportPubKey** command in the AWS CloudHSM key\$1mgmt\$1util (KMU) to export a public key. To see all available options, use the **exportPubKey -h** command. The following example exports an RSA public key to a file named `rsa2048.pub.exp`. ``` Command: exportPubKey -k 524294 -out rsa2048.pub.exp PEM formatted public key is written to rsa2048.pub.key Cfm3ExportPubKey returned: 0x00 : HSM Return: SUCCESS ``` # Delete keys with KMU and CMU Use the [deleteKey](key_mgmt_util-deleteKey.md) command to delete a key, as in the following example. Only the key owner can delete a key. ``` Command: deleteKey -k 524300 Cfm3DeleteKey returned: 0x00 : HSM Return: SUCCESS Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS ``` # Share and unshare keys with KMU and CMU In AWS CloudHSM, the CU who creates the key owns it. The owner manages the key, can export and delete it, and can use the key in cryptographic operations. The owner can also share the key with other CU users. Users with whom the key is shared can use the key in cryptographic operations, but they cannot export or delete the key, or share it with other users. You can share keys with other CU users when you create the key, such as by using the `-u` parameter of the [genSymKey](key_mgmt_util-genSymKey.md) or [genRSAKeyPair](key_mgmt_util-genRSAKeyPair.md) commands. To share existing keys with a different HSM user, use the [cloudhsm\$1mgmt\$1util](cloudhsm_mgmt_util.md) command line tool. This is different from most of the tasks documented in this section, which use the [key\$1mgmt\$1util](key_mgmt_util.md) command line tool. Before you can share a key, you must start cloudhsm\$1mgmt\$1util, enable end-to-end encryption, and log in to the HSMs. To share a key, log in to the HSM as the crypto user (CU) that owns the key. Only key owners can share a key. Use the **shareKey** command to share or unshare a key, specifying the handle of the key and the IDs of the user or users. To share or unshare with more than one user, specify a comma-separated list of user IDs. To share a key, use `1` as the command's last parameter, as in the following example. To unshare, use `0`. ``` aws-cloudhsm > shareKey 524295 4 1 *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)? y shareKey success on server 0(10.0.2.9) shareKey success on server 1(10.0.3.11) shareKey success on server 2(10.0.1.12) ``` The following shows the syntax for the **shareKey** command. ``` aws-cloudhsm > shareKey ``` # How to mark a key as trusted with the AWS CloudHSM Management Utility The content in this section provides instructions on using the AWS CloudHSM management Utility (CMU) to mark a key as trusted. 1. Using the [loginHSM](cloudhsm_mgmt_util-loginLogout.md) command, log in as a crypto officer (CO). 1. Use the [Set the attributes of AWS CloudHSM keys using CMU](cloudhsm_mgmt_util-setAttribute.md) command with `OBJ_ATTR_TRUSTED` (value `134`) set to true (`1`). ``` aws-cloudhsm > setAttribute 134 1 ```