# Keys in AWS CloudHSM
Before you can use your AWS CloudHSM cluster for cryptoprocessing, you must create [users](manage-hsm-users.md) and keys on the hardware security modules (HSM) in your cluster.
In AWS CloudHSM, use any of the following to manage keys on the HSMs in your cluster:
+ PKCS \$111 library
+ JCE provider
+ CNG and KSP providers
+ CloudHSM CLI
Before you can manage keys, you must log in to the HSM with the user name and password of a crypto user (CU). Only a CU can create a key. The CU who creates a key owns and manages that key.
See the following topics for more information about managing keys in AWS CloudHSM.
**Topics**
+ [Key sync and durability](manage-key-sync.md)
+ [AES key wrapping](manage-aes-key-wrapping.md)
+ [Trusted keys](manage-keys-using-trusted-keys.md)
+ [Key management with CloudHSM CLI](manage-keys-chsm-cli.md)
+ [Key management with KMU](manage-keys-kmu-cmu.md)
# Key synchronization and durability settings in AWS CloudHSM
AWS CloudHSM synchronizes every token key you create. Key synchronization is mostly an automatic process, but you can use a minimum of two hardware security modules (HSM) in your cluster to make keys more durable. This topic describes key synchronization settings, common issues customers face working with keys on a cluster, and strategies for making keys more durable.
This topic describes key synchronization settings in AWS CloudHSM, common issues customers face working with keys on a cluster, and strategies for making keys more durable.
**Topics**
+ [Concepts](concepts-key-sync.md)
+ [Understanding key synchronization](understand-key-sync.md)
+ [Change client key durability settings](working-client-sync.md)
+ [Synchronizing keys across cloned clusters](cli-sync.md)
# AWS CloudHSM key concepts
The following are concepts to be aware of when working with keys in AWS CloudHSM.
**Token keys**
Persistent keys that you create during key generate, import or unwrap operations. AWS CloudHSM synchronizes token keys across a cluster.
**Session keys**
Ephemeral keys that exist only on one hardware security module (HSM) in the cluster. AWS CloudHSM does *not* synchronize session keys across a cluster.
**Client-side key synchronization**
A client-side process that clones token keys you create during key generate, import or unwrap operations. You can make token keys more durable by running a cluster with a minimum of two HSMs.
**Server-side key synchronization**
Periodically clones keys to every HSM in the cluster. Requires no management.
**Client key durability settings**
Settings you configure on the client that impact key durability. These settings work differently in Client SDK 5 and Client SDK 3.
+ In Client SDK 5, use this setting to run a single HSM cluster.
+ In Client SDK 3, use this setting to specify the number of HSMs required for key creation operations to succeed.
# Understanding AWS CloudHSM key synchronization
AWS CloudHSM uses key synchronization to clone token keys across all the hardware security modules (HSM) in a cluster. You create token keys as persistent keys during key generation, import, or unwrap operations. To distribute these keys across the cluster, CloudHSM offers both client-side and server-side key synchronization.
![\[Key synchronization diagram showing client-side and server-side sync for CloudHSM cluster.\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/key-synch.png)
The goal with key synchronization—both server side and client side—is to distribute new keys across the cluster as quickly as possible after you create them. This is important because the subsequent calls you make to use new keys can get routed to any available HSM in the cluster. If the call you make routes to an HSM without the key, then the call fails. You can mitigate these type failures by specifying that your applications retry subsequent calls made after key creation operations. The time required to synchronize can vary, depending on the workload of your cluster and other intangibles. Use CloudWatch metrics to determine the timing your application should employ in this type situation. For more information, see [CloudWatch Metrics](hsm-metrics-cw.md).
The challenge with key synchronization in a cloud environment is key durability. You create keys on a single HSM and often begin using those keys immediately. If the HSM on which you create keys should fail before the keys have been cloned to another HSM in the cluster, you lose the keys *and* access to anything encrypted by the keys. To mitigate this risk, we offer *client-side synchronization*. Client side synchronization is a client-side process that clones the keys you create during key generate, import, or unwrap operations. Cloning keys as you create them makes keys more durable. Of course, you can't clone keys in a cluster with a single HSM. To make keys more durable, we also recommend you configure your cluster to use a minimum of two HSMs. With client-side synchronization and a cluster with two HSMs, you can meet the challenge of key durability in a cloud environment.
# Change AWS CloudHSM client key durability settings
Key synchronization is mostly an automatic process, but you can manage client-side key durability settings. Client-side key durability settings works differently in Client SDK 5 and Client SDK 3.
+ In Client SDK 5, we introduce the concept of *key availability quorums* which requires you to run clusters with a minimum of two HSMs. You can use client-side key durability settings to opt out of the two HSM requirement. For more information about quorums, see [AWS CloudHSM key concepts](concepts-key-sync.md).
+ In Client SDK 3, you use client-side key durability settings to specify the number of HSMs on which key creation must succeed for the overall operation to be deemed a success.
## Client SDK 5 client key durability settings
In Client SDK 5, key synchronization is a fully automatic process. With key availability quorum, newly created keys must exist on two HSMs in the cluster before your application can use the key. To use key availability quorum, your cluster must have a minimum of two HSMs.
If your cluster configuration doesn’t meet the key durability requirements, any attempt to create or use a token key will fail with the following error message in the logs:
```
Key does not meet the availability requirements - The key must be available on at least 2 HSMs before being used.
```
You can use client configuration settings to opt out of key availability quorum. You might want to opt out to run a cluster with a single HSM, for example.
### Client SDK 5 concepts
**Key Availability Quorum**
AWS CloudHSM specifies the number of HSMs in a cluster on which keys must exist before your application can use the key. Requires clusters with a minimum of two HSMs.
### Managing client key durability settings
To manage client key durability settings, you must use the configure tool for Client SDK 5.
------
#### [ PKCS \$111 library ]
**To disable client key durability for Client SDK 5 on Linux**
+ Use the configure tool to disable client key durability settings.
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 --disable-key-availability-check
```
**To disable client key durability for Client SDK 5 on Windows**
+ Use the configure tool to disable client key durability settings.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --disable-key-availability-check
```
------
#### [ OpenSSL Dynamic Engine ]
**To disable client key durability for Client SDK 5 on Linux**
+ Use the configure tool to disable client key durability settings.
```
$ sudo /opt/cloudhsm/bin/configure-dyn --disable-key-availability-check
```
------
#### [ OpenSSL Dynamic Engine Provider ]
**To disable client key durability for Client SDK 5 on Linux**
+ Use the configure tool to disable client key durability settings.
```
$ sudo /opt/cloudhsm/bin/configure-openssl-provider --disable-key-availability-check
```
------
#### [ Key Storage Provider (KSP) ]
**To disable client key durability for Client SDK 5 on Windows**
+ Use the configure tool to disable client key durability settings.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-key-availability-check
```
------
#### [ JCE provider ]
**To disable client key durability for Client SDK 5 on Linux**
+ Use the configure tool to disable client key durability settings.
```
$ sudo /opt/cloudhsm/bin/configure-jce --disable-key-availability-check
```
**To disable client key durability for Client SDK 5 on Windows**
+ Use the configure tool to disable client key durability settings.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-key-availability-check
```
------
#### [ CloudHSM CLI ]
**To disable client key durability for Client SDK 5 on Linux**
+ Use the configure tool to disable client key durability settings.
```
$ sudo /opt/cloudhsm/bin/configure-cli --disable-key-availability-check
```
**To disable client key durability for Client SDK 5 on Windows**
+ Use the configure tool to disable client key durability settings.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" --disable-key-availability-check
```
------
## Client SDK 3 client key durability settings
In Client SDK 3, key synchronization is mostly an automatic process, but you can use the client key durability settings to make keys more durable. You specify the number of HSMs on which key creation must succeed for the overall operation to be deemed a success. Client-side synchronization always makes a best-effort attempt to clone keys to every HSM in the cluster no matter what setting you choose. Your setting enforces key creation on the number of HSMs you specify. If you specify a value and the system cannot replicate the key to that number of HSMs, then the system automatically cleans up any unwanted key material and you can try again.
**Important**
If you don’t set client key durability settings (or if you use the default value of 1), your keys are vulnerable to loss. If your current HSM should fail before the server-side service has cloned that key to another HSM, you lose the key material.
To maximize key durability, consider specifying at least two HSMs for client-side synchronization. Remember that no matter how many HSMs you specify, the workload on your cluster remains the same. Client-side synchronization always makes a best-effort attempt to clone keys to every HSM in the cluster.
**Recommendations**
+ **Minimum**: Two HSMs per cluster
+ **Maximum**: One fewer than the total number of HSMs in your cluster
If client-side synchronization fails, the client service cleans up any unwanted keys that may have been created and are now unwanted. This clean up is a best-effort response that may not always work. If cleanup fails, you may have to delete unwanted key material. For more information, see [Key Synchronization Failures](ts-client-sync-fail.md).
### Setting up the configuration file for client key durability
To specify client key durability settings, you must edit `cloudhsm_client.cfg`.
**To edit the client configuration file**
1. Open `cloudhsm_client.cfg`.
**Linux**:
```
/opt/cloudhsm/etc/cloudhsm_client.cfg
```
**Windows**:
```
C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg
```
1. In the `client` node of the file, add `create_object_minimum_nodes` and specify a value for the minimum number of HSMs on which AWS CloudHSM must successfully create keys for key creation operations to succeed.
```
"create_object_minimum_nodes" : 2
```
**Note**
The key\$1mgmt\$1util (KMU) command-line tool has an additional setting for client key durability. For more information, see [KMU and client-side synchronization](#kmu-sync)
#### Configuration reference
These are the client-side synchronization properties, shown in an excerpt of the `cloudhsm_client.cfg`:
```
{
"client": {
"create_object_minimum_nodes" : 2,
...
},
...
}
```
**create\$1object\$1minimum\$1nodes**
Specifies the minimum number of HSMs required to deem key generation, key import, or key unwrap operations a success. If set, the default is 1. This means that for every key create operation, the client-side service attempts to create keys on every HSM in the cluster, but to return a success, only needs to create a *single key* on one HSM in the cluster.
### KMU and client-side synchronization
If you create keys with the key\$1mgmt\$1util (KMU) command-line tool, you use an optional command line parameter (`-min_srv`) to *limit* the number of HSMs on which to clone keys. If you specify the command-line parameter *and* a value in the configuration file, AWS CloudHSM honors the LARGER of the two values.
For more information, see the following topics:
+ [genDSAKeyPair](key_mgmt_util-genDSAKeyPair.md)
+ [genECCKeyPair](key_mgmt_util-genECCKeyPair.md)
+ [genRSAKeyPair](key_mgmt_util-genRSAKeyPair.md)
+ [genSymKey](key_mgmt_util-genSymKey.md)
+ [importPrivateKey](key_mgmt_util-importPrivateKey.md)
+ [importPubKey](key_mgmt_util-importPubKey.md)
+ [imSymKey](key_mgmt_util-imSymKey.md)
+ [insertMaskedObject](key_mgmt_util-insertMaskedObject.md)
+ [unWrapKey](key_mgmt_util-unwrapKey.md)
# Synchronizing keys across cloned AWS CloudHSM clusters
Client-side and server-side synchronization are only for synchronizing keys within the *same* AWS CloudHSM cluster. If you copy a backup of a cluster to another region, use the [key replicate](cloudhsm_cli-key-replicate.md) command to replicate a key between two clusters. You might use cloned clusters for cross-region redundancy or to simplify your disaster recovery process. If you haven't installed CloudHSM CLI, see the instructions in [Getting started with AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli-getting-started.md).
# AES key wrapping in AWS CloudHSM
This topic describes the options for AES key wrapping in AWS CloudHSM. AES key wrapping uses an AES key (the wrapping key) to wrap another key of any type (the target key). You use key wrapping to protect stored keys or transmit keys over insecure networks.
**Topics**
+ [Supported algorithms](#supported-types)
+ [Using AES key wrap in AWS CloudHSM](#use-aes-key-wrap)
## Supported algorithms
AWS CloudHSM offers three options for AES key wrapping, each based on how the target key is padded before being wrapped. Padding is done automatically, in accordance with the algorithm you use, when you call key wrap. The following table lists the supported algorithms and associated details to help you choose an appropriate wrapping mechanism for your application.
| AES Key Wrap Algorithm | Specification | Supported Target Key Types | Padding Scheme | AWS CloudHSM Client Availability |
| --- | --- | --- | --- | --- |
| AES Key Wrap with Zero Padding | [RFC 5649](https://tools.ietf.org/html/rfc5649) and [SP 800–38F](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf) | All | Adds zeros after key bits, if necessary, to block align | SDK 3.1 and later |
| AES Key Wrap with No Padding | [RFC 3394](https://tools.ietf.org/html/rfc3394) and [SP 800–38F](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf) | Block-aligned keys such as AES and 3DES | None | SDK 3.1 and later |
| AES Key Wrap with PKCS \$15 Padding | None | All | At least 8 bytes are added as per PKCS \$15 padding scheme to block align | All |
To learn how to use the AES key wrap algorithms from the preceding table in your application, see [Using AES Key Wrap in AWS CloudHSM.](#use-aes-key-wrap)
### Understanding initialization vectors in AES key wrap
Prior to wrapping, CloudHSM appends an initialization vector (IV) to the target key for data integrity. Each key wrap algorithm has specific restrictions on what type of IV is allowed. To set the IV in AWS CloudHSM, you have two options:
+ Implicit: set the IV to NULL and CloudHSM uses the default value for that algorithm for wrap and unwrap operations (recommended)
+ Explicit: set the IV by passing the default IV value to the key wrap function
**Important**
You must understand what IV you are using in your application. To unwrap the key, you must provide the same IV that you used to wrap the key. If you use an implicit IV to wrap, then use an implicit IV to unwrap. With an implicit IV, CloudHSM will use the default value to unwrap.
The following table describes permitted values for IVs, which the wrapping algorithm specifies.
****
| AES Key Wrap Algorithm | Implicit IV | Explicit IV |
| --- | --- | --- |
| AES Key Wrap with Zero Padding | Required Default value: (IV calculated internally based on specification) | Not allowed |
| AES Key Wrap with No Padding | Allowed (recommended) Default value: `0xA6A6A6A6A6A6A6A6` | Allowed Only this value accepted: `0xA6A6A6A6A6A6A6A6` |
| AES Key Wrap with PKCS \$15 Padding | Allowed (recommended) Default value: `0xA6A6A6A6A6A6A6A6` | Allowed Only this value accepted: `0xA6A6A6A6A6A6A6A6` |
## Using AES key wrap in AWS CloudHSM
You wrap and unwrap keys as follows:
+ In the [PKCS \$111 library](pkcs11-library.md), select the appropriate mechanism for the `C_WrapKey` and `C_UnWrapKey` functions as shown in the following table.
+ In the [JCE provider](java-library.md), select the appropriate algorithm, mode and padding combination, implementing cipher methods `Cipher.WRAP_MODE` and `Cipher.UNWRAP_MODE` as shown in the following table.
+ In the [CloudHSM CLI](cloudhsm_cli.md), choose the appropriate algorithm from the list of supported [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) and [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md) algorithms as shown in the following table.
+ In [key\$1mgmt\$1util (KMU)](key_mgmt_util.md), use commands [Export an AWS CloudHSM key using KMU](key_mgmt_util-wrapKey.md) and [Unwrap an AWS CloudHSM key using KMU](key_mgmt_util-unwrapKey.md) with appropriate m values as shown in the following table.
****
| AES Key Wrap Algorithm | PKCS \$111 Mechanism | Java Method | CloudHSM CLI Sub Command | Key Management Utility (KMU) Argument |
| --- | --- | --- | --- | --- |
| AES Key Wrap with Zero Padding | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/manage-aes-key-wrapping.html) | AESWrap/ECB/ZeroPadding | aes-zero-pad | m = 6 |
| AES Key Wrap with No Padding | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/manage-aes-key-wrapping.html) | AESWrap/ECB/NoPadding | aes-no-pad | m = 5 |
| AES Key Wrap with PKCS \$15 Padding | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/manage-aes-key-wrapping.html) | AESWrap/ECB/PKCS5Padding | aes-pkcs5-pad | m = 4 |
# Using trusted keys in AWS CloudHSM
AWS CloudHSM supports trusted key wrapping to protect data keys from insider threats. This topic describes how to create trusted keys to secure data.
**Topics**
+ [Understanding trusted keys](understand-trusted-key-wraps.md)
+ [Trusted key attributes](key_attribute_background.md)
+ [How to use trusted keys to wrap data keys](wrap_keys_using_trusted.md)
+ [How to unwrap a data key with a trusted key](unwrap_keys_using_trusted.md)
# Understanding trusted keys in AWS CloudHSM
A *trusted key* is a key that is used to wrap other keys and that admins and cryptographic officers (COs) specifically identify as trusted using the attribute `CKA_TRUSTED`. Additionally, admins and cryptographic officers (COs) use `CKA_UNWRAP_TEMPLATE` and related attributes to specify what actions data keys can do once they are unwrapped by a trusted key. Data keys that are unwrapped by the trusted key must also contain these attributes for the unwrap operation to succeed, which helps ensure that unwrapped data keys are only permitted for the use you intend.
Use the attribute `CKA_WRAP_WITH_TRUSTED` to identify all of the data keys you want to wrap with trusted keys. Doing this allows you to restrict data keys so applications can only use trusted keys to unwrap them. Once you set this attribute on the data keys, the attribute becomes read-only and you cannot change it. With these attributes in place, applications can only unwrap your data keys with the keys you trust, and unwraps always result in data keys with attributes that limit how these keys can be used.
# Trusted key attributes in AWS CloudHSM
The following attributes allow you to mark an AWS CloudHSM key as trusted, specify a data key can only be wrapped and unwrapped with a trusted key, and control what a data key can do after it is unwrapped:
+ `CKA_TRUSTED`: Apply this attribute (in addition to `CKA_UNWRAP_TEMPLATE`) to the key that will wrap data keys to specify that an admin or crypto officer (CO) has done the necessary diligence and trusts this key. Only an admin or CO can set `CKA_TRUSTED`. The crypto user (CU) owns the key, but only a CO can set its `CKA_TRUSTED` attribute.
+ `CKA_WRAP_WITH_TRUSTED`: Apply this attribute to an exportable data key to specify that you can only wrap this key with keys marked as `CKA_TRUSTED`. Once you set `CKA_WRAP_WITH_TRUSTED` to true, the attribute becomes read-only and you cannot change or remove the attribute.
+ `CKA_UNWRAP_TEMPLATE`: Apply this attribute to the wrapping key (in addition to `CKA_TRUSTED`) to specify which attribute names and values the service must automatically apply to data keys that the service unwraps. When an application submits a key for unwrapping, the application can also provide its own unwrap template. If you specify an unwrap template and the application provides its own unwrap template, the HSM uses both templates to apply attribute names and values to the key. However, if a value in the `CKA_UNWRAP_TEMPLATE` for the wrapping key conflicts with an attribute provided by the application during the unwrap request, then the unwrap request fails.
For more information about attributes, refer to the following topics:
+ [PKCS \$111 key attributes](pkcs11-attributes.md)
+ [JCE key attributes](java-lib-attributes_5.md)
+ [CloudHSM CLI key attributes](cloudhsm_cli-key-attributes.md)
# How to use trusted keys to wrap data keys in AWS CloudHSM
To use a trusted key to wrap a data key in AWS CloudHSM, you must complete three basic steps:
1. For the data key you plan to wrap with a trusted key, set its `CKA_WRAP_WITH_TRUSTED` attribute to true.
1. For the trusted key you plan to wrap the data key with, set its `CKA_TRUSTED` attribute to true.
1. Use the trusted key to wrap the data key.
## Step 1: Set the data key's `CKA_WRAP_WITH_TRUSTED` to true
For the data key you want to wrap, choose one of the following options to set the key’s `CKA_WRAP_WITH_TRUSTED` attribute to true. Doing this restricts the data key so applications can only use trusted keys to wrap it.
### Option 1: If generating a new key, set `CKA_WRAP_WITH_TRUSTED` to true
Generate a key using [PKCS \$111](pkcs11-library.md), [JCE](java-library.md), or [CloudHSM CLI](cloudhsm_cli.md). See the following examples for more details.
------
#### [ PKCS \$111 ]
To generate a key with PKCS \$111, you need to set the key's `CKA_WRAP_WITH_TRUSTED` attribute to true. As shown in the following example, do this by including this attribute in the key’s `CK_ATTRIBUTE template` and then setting the attribute to true:
```
CK_BYTE_PTR label = "test_key";
CK_ATTRIBUTE template[] = {
{CKA_WRAP_WITH_TRUSTED, &true_val, sizeof(CK_BBOOL)},
{CKA_LABEL, label, strlen(label)},
...
};
```
For more information, see [our public samples demonstrating key generation with PKCS \$111](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate).
------
#### [ JCE ]
To generate a key with JCE, you need to set the key's `WRAP_WITH_TRUSTED` attribute to true. As shown in the following example, do this by including this attribute in the key’s `KeyAttributesMap` and then setting the attribute to true:
```
final String label = "test_key";
final KeyAttributesMap keySpec = new KeyAttributesMap();
keySpec.put(KeyAttribute.WRAP_WITH_TRUSTED, true);
keySpec.put(KeyAttribute.LABEL, label);
...
```
For more information, see [our public samples demonstrating key generation with JCE](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-samples.html#java-samples-code_5).
------
#### [ CloudHSM CLI ]
To generate a key with CloudHSM CLI, you need to set the key's `wrap-with-trusted` attribute to true. Do this by including `wrap-with-trusted=true` in the appropriate argument for the key generation command:
+ For symmetric keys, add `wrap-with-trusted` to the `attributes` argument.
+ For public keys, add `wrap-with-trusted` to the `public-attributes` argument.
+ For private keys, add `wrap-with-trusted` to the `private-attributes` argument.
For more information on key pair generation, see [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md).
For more information on symmetric key generation, see [The generate-symmetric category in CloudHSM CLI](cloudhsm_cli-key-generate-symmetric.md).
------
### Option 2: If using an existing key, use CloudHSM CLI to set its `CKA_WRAP_WITH_TRUSTED` to true
To set an existing key's `CKA_WRAP_WITH_TRUSTED` attribute to true, follow these steps:
1. Use the [Log in to an HSM using CloudHSM CLI](cloudhsm_cli-login.md) command to log in as a crypto user (CU).
1. Use the [Set the attributes of keys with CloudHSM CLI](cloudhsm_cli-key-set-attribute.md) command to set the key's `wrap-with-trusted` attribute to true.
```
aws-cloudhsm > key set-attribute --filter attr.label=test_key --name wrap-with-trusted --value true
{
"error_code": 0,
"data": {
"message": "Attribute set successfully"
}
}
```
## Step 2: Set the trusted key's `CKA_TRUSTED` to true
To make a key a trusted key, its `CKA_TRUSTED` attribute must be set to true. You can either use CloudHSM CLI or the CloudHSM Management Utility (CMU) to do this.
+ If using CloudHSM CLI to set a key's `CKA_TRUSTED` attribute, see [Mark a key as trusted using CloudHSM CLI](manage-keys-cloudhsm-cli-trusted.md).
+ If using the CMU to set a key's `CKA_TRUSTED` attribute, see [How to mark a key as trusted with the AWS CloudHSM Management Utility](cloudhsm_using_trusted_keys_control_key_wrap.md).
## Step 3. Use the trusted key to wrap the data key
To wrap the data key referenced in Step 1 with the trusted key you set in Step 2, refer to the following links for code samples. Each demonstrates how to wrap keys.
+ [AWS CloudHSM PKCS \$111 examples](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/wrapping)
+ [AWS CloudHSM JCE examples](https://github.com/aws-samples/aws-cloudhsm-jce-examples/tree/sdk5/src/main/java/com/amazonaws/cloudhsm/examples)
# How to unwrap a data key with a trusted key for AWS CloudHSM
To unwrap a data key in AWS CloudHSM, you need a trusted key that has `CKA_UNWRAP` set to true. To be such a key, it must also meet the following criteria:
+ The key’s `CKA_TRUSTED` attribute must be set to true.
+ The key must use `CKA_UNWRAP_TEMPLATE` and related attributes to specify what actions data keys can perform once they are unwrapped. If, for example, you want an unwrapped key to be non-exportable, you set `CKA_EXPORTABLE = FALSE` as part of the `CKA_UNWRAP_TEMPLATE`.
**Note**
`CKA_UNWRAP_TEMPLATE` is only available with PKCS \$111.
When an application submits a key to be unwrapped, the application can also provide its own unwrap template. If you specify an unwrap template and the application provides its own unwrap template, the HSM uses both templates to apply attribute names and values to the key. However, if during the unwrap request a value in the trusted key’s `CKA_UNWRAP_TEMPLATE` conflicts with an attribute provided by the application, the unwrap request fails.
To see an example on unwrapping a data key with a trusted key, refer to [this PKCS \$111 example](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/unwrap_with_template.c).
# Key management with CloudHSM CLI
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. For more details, see the topics below.
+ [Using trusted keys](manage-keys-cloudhsm-cli-trusted.md) describes how to use CloudHSM CLI to create trusted keys to secure data.
+ [Generating keys](manage-keys-cloudhsm-cli-generate.md) includes instructions on creating keys, including symmetric keys, RSA keys, and EC keys.
+ [Deleting keys](manage-keys-cloudhsm-cli-delete.md) describes how key owners delete keys.
+ [Sharing and unsharing keys](manage-keys-cloudhsm-cli-share.md) details how key owners share and unshare keys.
+ [Filtering keys](manage-keys-cloudhsm-cli-filtering.md) offers guidelines on how to use filters to find keys.
+ [Manage key quorum authentication (M of N) ](key-quorum-auth-chsm-cli.md) offers guidelines on how to setup and use quorum authentication with keys.
# Generate keys with CloudHSM CLI
Before you can generate a key, you must start [CloudHSM CLI](cloudhsm_cli.md) and log in as a crypto user (CU). To generate keys on the HSM, use the command that corresponds to the type of key that you want to generate.
**Topics**
+ [Generate symmetric keys](cloudhsm-cli-generate-symmetric-keys.md)
+ [Generate asymmetric keys](cloudhsm-cli-generate-asymmetric-keys.md)
+ [Related topics](cloudhsm-cli-generate-keys-seealso.md)
# Generate symmetric keys with CloudHSM CLI
Use the commands listed in **[The generate-symmetric category in CloudHSM CLI](cloudhsm_cli-key-generate-symmetric.md)** to generate symmetric keys for AWS CloudHSM. To see all available options, use the **help key generate-symmetric** command.
## Generate an AES key
Use the **key generate-symmetric aes** command to generate AES keys. To see all available options, use the **help key generate-symmetric aes** command.
**Example**
The following example generates a 32-byte AES key.
```
aws-cloudhsm > key generate-symmetric aes \
--label aes-example \
--key-length-bytes 32
```
### Arguments
***