# AWS CloudHSM Command Line Interface (CLI)
<a name="cloudhsm_cli"></a>

**CloudHSM CLI** helps admins manage users and crypto users manage keys in their cluster in AWS CloudHSM. The CLI includes tools that can be used to create, delete and list users, change user passwords, update user multi-factor authentication (MFA). It also includes commands that generate, delete, import, and export keys, get and set attributes, find keys, and perform cryptographic operations.

For defined list of CloudHSM CLI users, see [HSM user management with CloudHSM CLI](manage-hsm-users-chsm-cli.md). For a defined list of key attributes for CloudHSM CLI, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md). For information on how to use CloudHSM CLI to manage keys, see [Key management with CloudHSM CLI](manage-keys-chsm-cli.md).

For a quick start, see [Getting started with AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli-getting-started.md). For detailed information about the CloudHSM CLI commands and examples of using the commands, see [Reference for CloudHSM CLI commands](cloudhsm_cli-reference.md). 

**Topics**
+ [Supported platforms](cloudhsm-cli-support.md)
+ [Getting started](cloudhsm_cli-getting-started.md)
+ [Command modes](cloudhsm_cli-modes.md)
+ [Key attributes](cloudhsm_cli-key-attributes.md)
+ [Advanced configurations](cloudhsm_cli-configs.md)
+ [Reference](cloudhsm_cli-reference.md)

# AWS CloudHSM Command Line Interface (CLI) supported platforms
<a name="cloudhsm-cli-support"></a>

This topic describes the Linux and Windows platforms that the AWS CloudHSM CLI supports.

## Linux support
<a name="w2aac23c15c11b5"></a>


| Supported platforms | X86\$164 Architecture | ARM architecture | 
| --- | --- | --- | 
| Amazon Linux 2 | Yes | Yes | 
| Amazon Linux 2023 | Yes | Yes | 
| Red Hat Enterprise Linux 8 (8.3\$1) | Yes | Yes | 
| Red Hat Enterprise Linux 9 (9.2\$1) | Yes | Yes | 
| Red Hat Enterprise Linux 10 (10.0\$1) | Yes | Yes | 
| Ubuntu 22.04 LTS | Yes | Yes | 
| Ubuntu 24.04 LTS | Yes | Yes | 
+ SDK 5.16 was the last release to provide Ubuntu 20.04 LTS platform support. For more information, see the [Ubuntu website](https://ubuntu.com/blog/ubuntu-20-04-lts-end-of-life-standard-support-is-coming-to-an-end-heres-how-to-prepare).
+ SDK 5.12 was the last release to provide CentOS 7 (7.8\$1) platform support. For more information, see the [CentOS website](https://blog.centos.org/2023/04/end-dates-are-coming-for-centos-stream-8-and-centos-linux-7/).
+ SDK 5.12 was the last release to provide Red Hat Enterprise Linux 7 (7.8\$1) platform support. For more information, see the [Red Hat website](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/rhel-7-end-of-maintenance).
+ SDK 5.4.2 was the last release to provide CentOS 8 platform support. For more information, see the [CentOS website](https://www.centos.org/centos-linux-eol/).

## Windows support
<a name="w2aac23c15c11b7"></a>
+ Microsoft Windows Server 2016
+ Microsoft Windows Server 2019
+ Microsoft Windows Server 2022
+ Microsoft Windows Server 2025

# Getting started with AWS CloudHSM Command Line Interface (CLI)
<a name="cloudhsm_cli-getting-started"></a>

With the CloudHSM CLI Command Line Interface (CLI), you can manage users in your AWS CloudHSM cluster. Use this topic to get started with basic hardware security module (HSM) user management tasks, such as creating users, listing users, and connecting CloudHSM CLI to the cluster.

**Topics**
+ [Install the CloudHSM CLI](w2aac23c15c13b7.md)
+ [Use the CloudHSM CLI](cloudhsm_cli-getting-started-use.md)

# Install the CloudHSM CLI
<a name="w2aac23c15c13b7"></a>

Use the following commands to download and install the CloudHSM CLI for AWS CloudHSM.

------
#### [ Amazon Linux 2023 ]

Amazon Linux 2023 on x86\$164 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-cli-latest.amzn2023.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.amzn2023.x86_64.rpm
```

Amazon Linux 2023 on ARM64 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-cli-latest.amzn2023.aarch64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.amzn2023.aarch64.rpm
```

------
#### [ Amazon Linux 2 ]

Amazon Linux 2 on x86\$164 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-cli-latest.el7.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.el7.x86_64.rpm
```

Amazon Linux 2 on ARM64 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-cli-latest.el7.aarch64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.el7.aarch64.rpm
```

------
#### [ RHEL 10 (10.0\$1) ]

RHEL 10 on x86\$164 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-cli-latest.el10.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.el10.x86_64.rpm
```

RHEL 10 on ARM64 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-cli-latest.el10.aarch64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.el10.aarch64.rpm
```

------
#### [ RHEL 9 (9.2\$1) ]

RHEL 9 on x86\$164 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-cli-latest.el9.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.el9.x86_64.rpm
```

RHEL 9 on ARM64 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-cli-latest.el9.aarch64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.el9.aarch64.rpm
```

------
#### [ RHEL 8 (8.3\$1) ]

RHEL 8 on x86\$164 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-cli-latest.el8.x86_64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.el8.x86_64.rpm
```

RHEL 8 on ARM64 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-cli-latest.el8.aarch64.rpm
```

```
$ sudo yum install ./cloudhsm-cli-latest.el8.aarch64.rpm
```

------
#### [ Ubuntu 24.04 LTS ]

Ubuntu 24.04 LTS on x86\$164 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-cli_latest_u24.04_amd64.deb
```

```
$ sudo apt install ./cloudhsm-cli_latest_u24.04_amd64.deb
```

Ubuntu 24.04 LTS on ARM64 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-cli_latest_u24.04_arm64.deb
```

```
$ sudo apt install ./cloudhsm-cli_latest_u24.04_arm64.deb
```

------
#### [ Ubuntu 22.04 LTS ]

Ubuntu 22.04 LTS on x86\$164 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-cli_latest_u22.04_amd64.deb
```

```
$ sudo apt install ./cloudhsm-cli_latest_u22.04_amd64.deb
```

Ubuntu 22.04 LTS on ARM64 architecture:

```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-cli_latest_u22.04_arm64.deb
```

```
$ sudo apt install ./cloudhsm-cli_latest_u22.04_arm64.deb
```

------
#### [ Windows Server 2022 ]

For Windows Server 2022 on x86\$164 architecture, open PowerShell as an administrator and run the following command:

```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMCLI-latest.msi -Outfile C:\AWSCloudHSMCLI-latest.msi
```

```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMCLI-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```

------
#### [ Windows Server 2019 ]

For Windows Server 2019 on x86\$164 architecture, open PowerShell as an administrator and run the following command:

```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMCLI-latest.msi -Outfile C:\AWSCloudHSMCLI-latest.msi
```

```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMCLI-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```

------
#### [ Windows Server 2016 ]

For Windows Server 2016 on x86\$164 architecture, open PowerShell as an administrator and run the following command:

```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMCLI-latest.msi -Outfile C:\AWSCloudHSMCLI-latest.msi
```

```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMCLI-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```

------

Use the following commands to configure CloudHSM CLI.

**To bootstrap a Linux EC2 instance for Client SDK 5**
+  Use the configure tool to specify the IP address of the HSM(s) in your cluster. 

  ```
  $ sudo /opt/cloudhsm/bin/configure-cli -a <The ENI IPv4 / IPv6 addresses of the HSMs>
  ```

**To bootstrap a Windows EC2 instance for Client SDK 5**
+  Use the configure tool to specify the IP address of the HSM(s) in your cluster. 

  ```
  PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" -a <The ENI IPv4 / IPv6 addresses of the HSMs>
  ```

# Use the CloudHSM CLI
<a name="cloudhsm_cli-getting-started-use"></a>

Use the following commands to start and use the CloudHSM CLI.

1. Use the following command to start CloudHSM CLI.

------
#### [ Linux ]

   ```
   $ /opt/cloudhsm/bin/cloudhsm-cli interactive
   ```

------
#### [ Windows ]

   ```
   PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive
   ```

------

1. Use the **login** command to log in to the cluster. All users can use this command.

   The command in the following example logs in *admin*, which is the default [admin](understanding-users.md) account. You set this user's password when you [activated the cluster](activate-cluster.md).

   ```
   aws-cloudhsm > login --username admin --role admin
   ```

   The system prompts you for your password. You enter the password, and the output shows that the command was successful.

   ```
   Enter password:
   {
     "error_code": 0,
     "data": {
       "username": "admin",
       "role": "admin"
     }
   }
   ```

1. Run the **user list** command to list all the users on the cluster.

   ```
   aws-cloudhsm > user list
   {
     "error_code": 0,
     "data": {
       "users": [
         {
           "username": "admin",
           "role": "admin",
           "locked": "false",
           "mfa": [],
           "cluster-coverage": "full"
         },
         {
           "username": "app_user",
           "role": "internal(APPLIANCE_USER)",
           "locked": "false",
           "mfa": [],
           "cluster-coverage": "full"
         }
       ]
     }
   }
   ```

1.  Use **user create** to create a CU user named **example\$1user**. 

   You can create CUs because in a previous step you logged in as an admin user. Only admin users can perform user management tasks, such as creating and deleting users and changing the passwords of other users. 

   ```
   aws-cloudhsm > user create --username example_user --role crypto-user     
   Enter password:
   Confirm password:
   {
    "error_code": 0,
    "data": {
      "username": "example_user",
      "role": "crypto-user"
    }
   }
   ```

1.  Use **user list** to list all the users on the cluster. 

   ```
   aws-cloudhsm > user list
   {
     "error_code": 0,
     "data": {
       "users": [
         {
           "username": "admin",
           "role": "admin",
           "locked": "false",
           "mfa": [],
           "cluster-coverage": "full"
         },
         {
           "username": "example_user",
           "role": "crypto_user",
           "locked": "false",
           "mfa": [],
           "cluster-coverage": "full"
         },
         {
           "username": "app_user",
           "role": "internal(APPLIANCE_USER)",
           "locked": "false",
           "mfa": [],
           "cluster-coverage": "full"
         }
       ]
     }
   }
   ```

1. Use the **logout** command to log out of AWS CloudHSM cluster.

   ```
   aws-cloudhsm > logout
   {
     "error_code": 0,
     "data": "Logout successful"
   }
   ```

1. Use the **quit** command to stop the CLI.

   ```
   aws-cloudhsm > quit
   ```

# Command modes in CloudHSM CLI
<a name="cloudhsm_cli-modes"></a>

In CloudHSM CLI, you can run commands two different ways: in single command mode and interactive mode. Interactive mode is designed for users, and single command mode is designed for scripts.

**Note**  
All commands work in interactive mode and single command mode.

## Interactive mode
<a name="cloudhsm_cli-mode-interactive"></a>

Use the following commands to start CloudHSM CLI interactive mode

------
#### [ Linux ]

```
$ /opt/cloudhsm/bin/cloudhsm-cli interactive
```

------
#### [ Windows ]

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive
```

------

When using the CLI in Interactive Mode, you can log in to a user account using the **login** command.

```
aws-cloudhsm > login --username <USERNAME> --role ROLE>
```

To list all CloudHSM CLI commands, run the following command:

```
aws-cloudhsm > help
```

To get the syntax for a CloudHSM CLI command, run the following command:

```
aws-cloudhsm >  help <command-name>
```

To get a list of users on the HSMs, enter **user list**.

```
aws-cloudhsm > user list
```

To end your CloudHSM CLI session, run the following command:

```
aws-cloudhsm > quit
```

## Single Command mode
<a name="cloudhsm_cli-mode-single-command"></a>

**Note**  
When using single command mode, you must escape any special characters in environment variables and command-line arguments that may be interpreted by your shell.

If you run CloudHSM CLI using Single Command Mode, you need to set two environment variables to provide credentials: CLOUDHSM\$1PIN and CLOUDHSM\$1ROLE:

```
$ export CLOUDHSM_ROLE=admin
```

```
$ export CLOUDHSM_PIN=admin_username:admin_password
```

After doing this, you can execute commands using the credentials stored in your environment.

```
$ cloudhsm-cli user change-password --username alice --role crypto-user
Enter password:
Confirm password:
{
    "error_code": 0,
    "data": {
      "username": "alice",
      "role": "crypto-user"
    }
}
```

# Key attributes for CloudHSM CLI
<a name="cloudhsm_cli-key-attributes"></a>

This topic describes how to use CloudHSM CLI to set key attributes. A key attribute in CloudHSM CLI can define a key’s type, how a key can function, or how a key is labeled. Some attributes define unique characteristics (a key’s type, for example). Other attributes can be set to true or false—changing them either activates or deactivates a part of the key’s functionality.

For examples showing how to use key attributes, see the commands listed under the parent command [The key category in CloudHSM CLI](cloudhsm_cli-key.md).

The following topics provide additional detail about key attributes in CloudHSM CLI.

**Topics**
+ [Supported attributes](cloudhsm_cli-key-attributes-table.md)
+ [Check value](chsm-cli-key-attribute-details.md)
+ [Related topics](chsm_cli-key-attributes-seealso.md)

# Supported attributes for CloudHSM CLI
<a name="cloudhsm_cli-key-attributes-table"></a>

As a best practice, only set values for attributes you wish to make restrictive. If you don’t specify a value, CloudHSM CLI uses the default value specified in the table below.

The following table lists the key attributes, possible values, defaults, and related notes for CloudHSM CLI. An empty cell in the **Value** column indicates that there is no specific default value assigned to the attribute.


****  

| CloudHSM CLI attribute | Value | Modifiable with [key set-attribute](cloudhsm_cli-key-set-attribute.md) | Settable at key creation | 
| --- | --- | --- | --- | 
| always-sensitive |  The value is `True` if `sensitive` has always been set to `True` and has never changed.  | No | No | 
| check-value | The check value of the key. For more information, see [Additional Details](chsm-cli-key-attribute-details.md). | No | No | 
| class | Possible values: `secret-key`, `public-key`, and `private-key`. | No | Yes | 
| curve |  Elliptic curve used to generate the EC key pair. Valid Values: `secp224r1`, `secp256r1`, `prime256v1`, `secp384r1`, `secp256k1`, `secp521r1`, and `ed25519` `ed25519` is only supported on hsm2m.medium instances in non-FIPS mode.  | No | Settable with EC, not settable with RSA | 
| decrypt | Default: `False` | Yes | Yes | 
| derive | Default: `False` | Derive can be set on hsm2m.medium instances. It cannot be set for RSA keys on hsm1.medium instances. | Yes | 
| destroyable | Default: `True` | Yes | Yes | 
| ec-point | For EC keys, DER-encoding of ANSI X9.62 ECPoint value "Q" in a hexadecimal format. For other key types, this attribute does not exist. | No | No | 
| encrypt | Default: `False` | Yes | Yes | 
| extractable | Default: `True` | No | Yes | 
| id | Default: Empty | id can be set on hsm2m.medium instances. It cannot be set on hsm1.medium instances. | Yes | 
| key-length-bytes | Required for generating an AES key.Valid values: `16`, `24`, and `32` bytes. | No | No | 
| key-type | Possible values: `aes`, `rsa`, and `ec` | No | Yes | 
| label | Default: Empty | Yes | Yes | 
| local | Default: `True` for keys generated in the HSM, `False` for keys imported into the HSM. | No | No | 
| modifiable | Default: `True` | Can be changed from true to false, but not from false to true. | Yes | 
| modulus | The modulus that was used to generate an RSA key pair. For other key types, this attribute does not exist. | No | No | 
| modulus-size-bits | Required for generating an RSA key pair.Minimum value is `2048`. | No | Settable with RSA, not settable with EC | 
| never-extractable |  The value is `True` if extractable has never been set to `False`. The value is `False` if extractable has ever been set to `True`.  | No | No | 
| private | Default: `True` | No | Yes | 
| public-exponent | Required for generating an RSA key pair.Valid values: The value must be an odd number greater than or equal to `65537`. | No | Settable with RSA, not settable with EC | 
| sensitive |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-attributes-table.html)  | No | Settable with private keys, not settable with public keys. | 
| sign |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-attributes-table.html)  | Yes | Yes | 
| token | Default: `True` | Can be changed from false to true, but not from true to false. | Yes | 
| trusted | Default: `False` | Only admin users can set this parameter. | No | 
| unwrap | Default: False | Yes | Yes, except for public keys. | 
| unwrap-template | Values should use the attribute template applied to any key unwrapped using this wrapping key. | Yes | No | 
| verify |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-attributes-table.html)  | Yes | Yes | 
| wrap | Default: False | Yes | Yes, except for private keys. | 
| wrap-template | Values should use the attribute template to match the key wrapped using this wrapping key. | Yes | No | 
| wrap-with-trusted | Default: `False` | Yes | Yes | 

# Check value in CloudHSM CLI
<a name="chsm-cli-key-attribute-details"></a>

The *check value* in CloudHSM CLI is a 3-byte hash or checksum of a key that is generated when the HSM imports or generates a key. You can also calculate a check value outside of the HSM, such as after you export a key. You can then compare the check value values to confirm the identity and integrity of the key. To get the check value of a key, use [key list](cloudhsm_cli-key-list.md) with the verbose flag.

AWS CloudHSM uses the following standard methods to generate a check value:
+ **Symmetric keys**: First 3 bytes of the result of encrypting a zero-block with the key.
+ **Asymmetric key pairs**: First 3 bytes of the SHA-1 hash of the public key.
+ **HMAC keys**: KCV for HMAC keys is not supported at this time.

# Related topics for CloudHSM CLI
<a name="chsm_cli-key-attributes-seealso"></a>

See the following topics for more information about CloudHSM CLI.
+ [The key category in CloudHSM CLI](cloudhsm_cli-key.md)
+ [Reference for CloudHSM CLI commands](cloudhsm_cli-reference.md)

# Advanced configurations for CloudHSM CLI
<a name="cloudhsm_cli-configs"></a>

The AWS CloudHSM Command Line Interface (CLI) includes the following advanced configuration, which is not part of the general configurations most customers utilize. These configurations provide additional capabilities.
+ [Connecting to multiple clusters](cloudhsm_cli-configs-multi-cluster.md)

# Connecting to multiple clusters with CloudHSM CLI
<a name="cloudhsm_cli-configs-multi-cluster"></a>

 With AWS CloudHSM Client SDK 5, you can configure CloudHSM CLI to allow connections to multiple CloudHSM clusters from a single CLI instance. 

The following topics describe how to use the CloudHSM CLI multi-cluster functionality to connect with multiple clusters.

**Topics**
+ [Prerequisites](cloudhsm_cli-multi-cluster-prereqs.md)
+ [Configure multi-cluster functionality](cloudhsm_cli-multi-cluster-config-run.md)
+ [Add a cluster](cloudhsm_cli-multi-cluster-add-cluster.md)
+ [Remove a cluster](cloudhsm_cli-multi-cluster-remove-cluster.md)
+ [Interact with clusters](cloudhsm_cli-multi-cluster-usage.md)

# Multi-cluster prerequisites for AWS CloudHSM
<a name="cloudhsm_cli-multi-cluster-prereqs"></a>

Before configuring your cluster in AWS CloudHSM to connect to multiple clusters, you must meet the following prerequisites: 
+ Two or more AWS CloudHSM clusters to which you’d like to connect to, along with their cluster certificates.
+ An EC2 instance with Security Groups correctly configured to connect to all of the clusters above. For more information about how to set up a cluster and the client instance, refer to [Getting started with AWS CloudHSM](getting-started.md).
+ To set up multi-cluster functionality, you must have already downloaded and installed the CloudHSM CLI. If you have not already done this, refer to the instructions in [Getting started with AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli-getting-started.md).
+  You will not be able to access a cluster configured with `./configure-cli[.exe] -a` since it will not be associated with a `cluster-id`. You can reconfigure it by following `config-cli add-cluster` as described in this guide. 

# Configure the CloudHSM CLI for multi-cluster functionality
<a name="cloudhsm_cli-multi-cluster-config-run"></a>

To configure your CloudHSM CLI for multi-cluster functionality, follow these steps:

1. Identify the clusters you want to connect to.

1. Add these clusters to your CloudHSM CLI configuration using the [configure-cli](configure-sdk-5.md) subcommand `add-cluster` as described below.

1. Restart any CloudHSM CLI processes in order for the new configuration to take effect.

# Add a cluster to your AWS CloudHSM configuration
<a name="cloudhsm_cli-multi-cluster-add-cluster"></a>

When connecting to multiple clusters, use the `configure-cli add-cluster` command to add a cluster to your configuration.

## Syntax
<a name="cloudhsm_cli-multi-cluster-add-cluster-syntax"></a>

```
configure-cli add-cluster [OPTIONS]
        --cluster-id <CLUSTER ID> 
        [--region <REGION>]
        [--endpoint <ENDPOINT>]
        [--hsm-ca-cert <HSM CA CERTIFICATE FILE>]
        [--client-cert-hsm-tls-file <CLIENT CERTIFICATE FILE>]
        [--client-key-hsm-tls-file <CLIENT KEY FILE>]
        [-h, --help]
```

## Examples
<a name="cloudhsm_cli-multi-cluster-add-cluster-examples"></a>

### Add a cluster using the `cluster-id` parameter
<a name="w2aac23c15c19b7c13b7b3b1"></a>

**Example**  
 Use the `configure-cli add-cluster` along with the `cluster-id` parameter to add a cluster (with the ID of `cluster-1234567`) to your configuration.   

```
$ sudo /opt/cloudhsm/bin/configure-cli add-cluster --cluster-id <cluster-1234567>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" add-cluster --cluster-id <cluster-1234567>
```

**Tip**  
If using `configure-cli add-cluster` with the `cluster-id` parameter doesn't result in the cluster being added, refer to the following example for a longer version of this command that also requires `--region` and `--endpoint` parameters to identify the cluster being added. If, for example, the region of the cluster is different than the one configured as your AWS CLI default, you should use the `--region` parameter to use the correct region. Additionally, you have the ability to specify the AWS CloudHSM API endpoint to use for the call, which may be necessary for various network setups, such as using VPC interface endpoints that don’t use the default DNS hostname for AWS CloudHSM.

### Add a cluster using `cluster-id`, `endpoint`, and `region` parameters
<a name="w2aac23c15c19b7c13b7b3b3"></a>

**Example**  
 Use the `configure-cli add-cluster` along with the `cluster-id`, `endpoint`, and `region` parameters to add a cluster (with the ID of `cluster-1234567`) to your configuration.   

```
$ sudo /opt/cloudhsm/bin/configure-cli add-cluster --cluster-id <cluster-1234567> --region <us-east-1> --endpoint <https://cloudhsmv2.us-east-1.amazonaws.com>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" add-cluster --cluster-id <cluster-1234567> --region <us-east-1> --endpoint <https://cloudhsmv2.us-east-1.amazonaws.com>
```

For more information about the `--cluster-id`, `--region`, and `--endpoint` parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md).

## Parameters
<a name="cloudhsm_cli-multi-cluster-add-cluster-parameters"></a>

**--cluster-id *<Cluster ID>***  
 Makes a `DescribeClusters` call to find all of the HSM elastic network interface (ENI) IP addresses in the cluster associated with the cluster ID. The system adds the ENI IP addresses to the AWS CloudHSM configuration files.  
If you use the `--cluster-id` parameter from an EC2 instance within a VPC that does not have access to the public internet, then you must create an interface VPC endpoint to connect with AWS CloudHSM. For more information about VPC endpoints, see [AWS CloudHSM and VPC endpoints](cloudhsm-vpc-endpoint.md).
Required: Yes

**--endpoint *<Endpoint>***  
Specify the AWS CloudHSM API endpoint used for making the `DescribeClusters` call. You must set this option in combination with `--cluster-id`.   
Required: No

**--hsm-ca-cert *<HsmCA Certificate Filepath>***  
Specifies the filepath to the HSM CA certificate.  
Required: No

**--region *<Region>***  
Specify the region of your cluster. You must set this option in combination with `--cluster-id`.  
If you don’t supply the `--region` parameter, the system chooses the region by attempting to read the `AWS_DEFAULT_REGION` or `AWS_REGION` environment variables. If those variables aren’t set, then the system checks the region associated with your profile in your AWS config file (typically `~/.aws/config`) unless you specified a different file in the `AWS_CONFIG_FILE` environment variable. If none of the above are set, the system defaults to the `us-east-1` region.  
Required: No

**--client-cert-hsm-tls-file *<client certificate hsm tls path>***  
 Path to the client certificate used for TLS client-HSM mutual authentication.   
 Only use this option if you have registered at least one trust anchor onto HSM with CloudHSM CLI. You must set this option in combination with `--client-key-hsm-tls-file`.   
Required: No

**--client-key-hsm-tls-file *<client key hsm tls path>***  
 Path to the client key used for TLS client-HSM mutual authentication.   
 Only use this option if you have registered at least one trust anchor onto HSM with CloudHSM CLI. You must set this option in combination with `--client-cert-hsm-tls-file`.   
Required: No

# Remove a cluster from your AWS CloudHSM configuration
<a name="cloudhsm_cli-multi-cluster-remove-cluster"></a>

When connecting to multiple clusters with CloudHSM CLI, use the `configure-cli remove-cluster` command to remove a cluster from your configuration.

## Syntax
<a name="cloudhsm_cli-multi-cluster-remove-cluster-syntax"></a>

```
configure-cli remove-cluster [OPTIONS]
        --cluster-id <CLUSTER ID>
        [-h, --help]
```

## Examples
<a name="cloudhsm_cli-multi-cluster-remove-cluster-examples"></a>

### Remove a cluster using the `cluster-id` parameter
<a name="w2aac23c15c19b7c15b7b3b1"></a>

**Example**  
 Use the `configure-cli remove-cluster` along with the `cluster-id` parameter to remove a cluster (with the ID of `cluster-1234567`) from your configuration.   

```
$ sudo /opt/cloudhsm/bin/configure-cli remove-cluster --cluster-id <cluster-1234567>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" remove-cluster --cluster-id <cluster-1234567>
```

For more information about the `--cluster-id` parameter, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md).

## Parameter
<a name="cloudhsm_cli-multi-cluster-remove-cluster-parameters"></a>

**--cluster-id *<Cluster ID>***  
The ID of the cluster to remove from the configuration.  
Required: Yes

# Interact with multiple clusters in AWS CloudHSM
<a name="cloudhsm_cli-multi-cluster-usage"></a>

After configuring multiple clusters with CloudHSM CLI, use the `cloudhsm-cli` command to interact with them.

## Examples
<a name="cloudhsm_cli-multi-cluster-cluster-usage-examples"></a>

### Setting a default `cluster-id` when using interactive mode
<a name="w2aac23c15c19b7c17b5b3b1"></a>

**Example**  
 Use the [Interactive mode](cloudhsm_cli-modes.md#cloudhsm_cli-mode-interactive) along with the `cluster-id` parameter to set a default cluster (with the ID of `cluster-1234567`) from your configuration.   

```
$ cloudhsm-cli interactive --cluster-id <cluster-1234567>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive --cluster-id <cluster-1234567>
```

### Setting the `cluster-id` when running a single command
<a name="w2aac23c15c19b7c17b5b5b1"></a>

**Example**  
 Use the `cluster-id` parameter to set the cluster (with the ID of `cluster-1234567`) to get [List HSMs with CloudHSM CLI](cloudhsm_cli-cluster-hsm-info.md) from.   

```
$ cloudhsm-cli cluster hsm-info --cluster-id <cluster-1234567>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" cluster hsm-info --cluster-id <cluster-1234567>
```

# Reference for CloudHSM CLI commands
<a name="cloudhsm_cli-reference"></a>

CloudHSM CLI helps admins manage users in their AWS CloudHSM cluster. CloudHSM CLI can be run in two modes: Interactive Mode and Single Command Mode. For a quick start, see [Getting started with AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli-getting-started.md). 

To run most CloudHSM CLI commands, you must start the CloudHSM CLI and log in to the HSM. If you add or delete HSMs, update the configuration files for CloudHSM CLI. Otherwise, the changes that you make might not be effective for all HSMs in the cluster.

The following topics describe commands in CloudHSM CLI: 


| Command | Description | User Type | 
| --- | --- | --- | 
| [activate](cloudhsm_cli-cluster-activate.md) | Activates an CloudHSM cluster and provides confirmation the cluster is new. This must be done before any other operations can be performed. | Unactivated admin | 
| [hsm-info](cloudhsm_cli-cluster-hsm-info.md) | List the HSMs in your cluster. | All [1](#cli-ref-1), including unauthenticated users. Login is not required. | 
| [ecdsa](cloudhsm_cli-crypto-sign-ecdsa.md) | Generates a signature using an EC private key and the ECDSA signing mechanism.  | Crypto users (CU) | 
| [ed25519ph](cloudhsm_cli-crypto-sign-ed25519ph.md) | Generates a signature using an Ed25519 private key and the HashEdDSA signing mechanism.  | CU | 
| [rsa-pkcs](cloudhsm_cli-crypto-sign-rsa-pkcs.md) | Generates a signature using an RSA private key and the RSA-PKCS signing mechanism. | CU | 
| [rsa-pkcs-pss](cloudhsm_cli-crypto-sign-rsa-pkcs-pss.md) | Generates a signature using an RSA private key and the RSA-PKCS-PSS signing mechanism. | CU | 
| [ecdsa](cloudhsm_cli-crypto-verify-ecdsa.md) | Confirms a file has been signed in the HSM by a given public key. Verifies the signature was generated using the ECDSA signing mechanism. Compares a signed file against a source file and determine whether the two are cryptographically related based on a given ecdsa public key and signing mechanism.  | CU | 
| [ed25519ph](cloudhsm_cli-crypto-verify-ed25519ph.md) | Verifies HashEdDSA signatures using an Ed25519 public key. | CU | 
| [rsa-pkcs](cloudhsm_cli-crypto-verify-rsa-pkcs.md) | Confirms a file has been signed in the HSM by a given public key. Verifies the signature was generated using the RSA-PKCS signing mechanism. Compares a signed file against a source file and determines whether the two are cryptographically related based on a given rsa public key and signing mechanism. | CU | 
| [rsa-pkcs-pss](cloudhsm_cli-crypto-verify-rsa-pkcs-pss.md) | Confirms a file has been signed in the HSM by a given public key. Verifies the signature was generated using the RSA-PKCS-PSS signing mechanism. Compares a signed file against a source file and determines whether the two are cryptographically related based on a given rsa public key and signing mechanism. | CU | 
| [key delete](cloudhsm_cli-key-delete.md) | Deletes a key from your AWS CloudHSM cluster. | CU | 
| [key generate-file](cloudhsm_cli-key-generate-file.md) | Generates a key file in your AWS CloudHSM cluster. | CU | 
| [key generate-asymmetric-pair rsa](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md) | Generates an asymmetric RSA key pair in your AWS CloudHSM cluster. | CU | 
| [key generate-asymmetric-pair ec](cloudhsm_cli-key-generate-asymmetric-pair-ec.md) | Generates an asymmetric Elliptic-curve (EC) key pair in your AWS CloudHSM cluster. | CU | 
| [key generate-symmetric aes](cloudhsm_cli-key-generate-symmetric-aes.md) | Generates a symmetric AES key in your AWS CloudHSM cluster. | CU | 
| [key generate-symmetric generic-secret](cloudhsm_cli-key-generate-symmetric-generic-secret.md) | Generates a symmetric Generic Secret key in your AWS CloudHSM cluster. | CU | 
| [key import pem](cloudhsm_cli-key-import-pem.md) | Imports a PEM format key into an HSM. You can use it to import public keys that were generated outside of the HSM. | CU | 
| [key list](cloudhsm_cli-key-list.md) | Finds all keys for the current user present in your AWS CloudHSM cluster. | CU | 
| [key replicate](cloudhsm_cli-key-replicate.md) | Replicate a key from a source cluster to a cloned destination cluster. | CU | 
| [key set-attribute](cloudhsm_cli-key-set-attribute.md) | Sets the attributes of keys in your AWS CloudHSM cluster. | CUs can run this command, admins can set the trusted attribute. | 
| [key share](cloudhsm_cli-key-share.md) | Shares a key with other CUs in your AWS CloudHSM cluster. | CU | 
| [key unshare](cloudhsm_cli-key-unshare.md) | Unshares a key with other CUs in your AWS CloudHSM cluster. | CU | 
| [aes-gcm](cloudhsm_cli-key-unwrap-aes-gcm.md) | Unwraps a payload key into the cluster using the AES wrapping key and the AES-GCM unwrapping mechanism. | CU | 
| [aes-no-pad](cloudhsm_cli-key-unwrap-aes-no-pad.md) | Unwraps a payload key into the cluster using the AES wrapping key and the AES-NO-PAD unwrapping mechanism. | CU | 
| [aes-pkcs5-pad](cloudhsm_cli-key-unwrap-aes-pkcs5-pad.md) | Unwraps a payload key using the AES wrapping key and the AES-PKCS5-PAD unwrapping mechanism. | CU | 
| [aes-zero-pad](cloudhsm_cli-key-unwrap-aes-zero-pad.md) | Unwraps a payload key into the cluster using the AES wrapping key and the AES-ZERO-PAD unwrapping mechanism. | CU | 
| [cloudhsm-aes-gcm](cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm.md) | Unwraps a payload key into the cluster using the AES wrapping key and the CLOUDHSM-AES-GCM unwrapping mechanism. | CU | 
| [rsa-aes](cloudhsm_cli-key-unwrap-rsa-aes.md) | Unwraps a payload key using an RSA private key and the RSA-AES unwrapping mechanism. | CU | 
| [rsa-oaep](cloudhsm_cli-key-unwrap-rsa-oaep.md) | Unwraps a payload key using the RSA private key and the RSA-OAEP unwrapping mechanism. | CU | 
| [rsa-pkcs](cloudhsm_cli-key-unwrap-rsa-pkcs.md) | Unwraps a payload key using the RSA private key and the RSA-PKCS unwrapping mechanism. | CU | 
| [aes-gcm](cloudhsm_cli-key-wrap-aes-gcm.md) | Wraps a payload key using an AES key on the HSM and the AES-GCM wrapping mechanism. | CU | 
| [aes-no-pad](cloudhsm_cli-key-wrap-aes-no-pad.md) | Wraps a payload key using an AES key on the HSM and the AES-NO-PAD wrapping mechanism. | CU | 
| [aes-pkcs5-pad](cloudhsm_cli-key-wrap-aes-pkcs5-pad.md) | Wraps a payload key using an AES key on the HSM and the AES-PKCS5-PAD wrapping mechanism. | CU | 
| [aes-zero-pad](cloudhsm_cli-key-wrap-aes-zero-pad.md) | Wraps a payload key using an AES key on the HSM and the AES-ZERO-PAD wrapping mechanism. | CU | 
| [cloudhsm-aes-gcm](cloudhsm_cli-key-wrap-cloudhsm-aes-gcm.md) | Wraps a payload key using an AES key on the HSM and the CLOUDHSM-AES-GCM wrapping mechanism. | CUs | 
| [rsa-aes](cloudhsm_cli-key-wrap-rsa-aes.md) | Wraps a payload key using an RSA public key on the HSM and the RSA-AES wrapping mechanism. | CU | 
| [rsa-oaep](cloudhsm_cli-key-wrap-rsa-oaep.md) | Wraps a payload key using an RSA public key on the HSM and the RSA-OAEP wrapping mechanism. | CU | 
| [ Wrap a key with RSA-PKCS using CloudHSM CLIrsa-pkcs  The **key wrap rsa-pkcs** command wraps a payload key using an RSA public key on the HSM and the `RSA-PKCS` wrapping mechanism.   Use the **key wrap rsa-pkcs** command in CloudHSM CLI to wrap a payload key using an RSA public key on the hardware security module (HSM) and the `RSA-PKCS` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`. Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations. To use the **key wrap rsa-pkcs** command, you must first have an RSA key in your AWS CloudHSM cluster. You can generate an RSA key pair using the [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md) command and the `wrap` attribute set to `true`.  User type  The following types of users can run this command.   Crypto users (CUs)     Requirements    To run this command, you must be logged in as a CU.     Syntax  

```
aws-cloudhsm > help key wrap rsa-pkcs
Usage: key wrap rsa-pkcs [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```   Example  This example shows how to use the **key wrap rsa-pkcs** command using an RSA public key. 

**Example**  

```
aws-cloudhsm > key wrap rsa-pkcs --payload-filter attr.label=payload-key --wrapping-filter attr.label=rsa-public-key-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000007008da",
    "wrapped_key_data": "am0Nc7+YE8FWs+5HvU7sIBcXVb24QA0l65nbNAD+1bK+e18BpSfnaI3P+r8Dp+pLu1ofoUy/vtzRjZoCiDofcz4EqCFnGl4GdcJ1/3W/5WRvMatCa2d7cx02swaeZcjKsermPXYRO1lGlfq6NskwMeeTkV8R7Rx9artFrs1y0DdIgIKVaiFHwnBIUMnlQrR2zRmMkfwU1jxMYmOYyD031F5VbnjSrhfMwkww2la7uf/c3XdFJ2+0Bo94c6og/yfPcpOOobJlITCoXhtMRepSdO4OggYq/6nUDuHCtJ86pPGnNahyr7+sAaSI3a5ECQLUjwaIARUCyoRh7EFK3qPXcg=="
  }
```   Arguments   

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) 

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes 

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No 

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes 

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1. 

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.    Related topics    [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)   [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)    ](cloudhsm_cli-key-wrap-rsa-pkcs.md) | Wraps a payload key using an RSA public key on the HSM and the RSA-PKCS wrapping mechanism. | CU | 
| [login](cloudhsm_cli-login.md) | Log in to your AWS CloudHSM cluster. | Admin, crypto user (CU), and appliance user (AU) | 
| [logout](cloudhsm_cli-logout.md) | Log out of your AWS CloudHSM cluster. | Admin, CU, and appliance user (AU) | 
| [quorum token-sign delete](cloudhsm_cli-qm-token-del.md) | Deletes one or more tokens for a quorum authorized service. | Admin | 
| [quorum token-sign generate](cloudhsm_cli-qm-token-gen.md) | Generates a token for a quorum authorized service. | Admin | 
| [quorum token-sign list](cloudhsm_cli-qm-token-list.md) | Lists all token-sign quorum tokens present in your CloudHSM cluster. | All [1](#cli-ref-1), including unauthenticated users. Login is not required. | 
| [quorum token-sign list-quorum-values](cloudhsm_cli-qm-token-list-qm.md) | Lists the quorum values set in your CloudHSM cluster. | All [1](#cli-ref-1), including unauthenticated users. Login is not required. | 
| [quorum token-sign set-quorum-value](cloudhsm_cli-qm-token-set-qm.md) | Sets a new quorum value for a quorum authorized service. | Admin | 
| [user change-mfa](cloudhsm_cli-user-change-mfa.md) | Changes a user's multi-factor authentication (MFA) strategy. | Admin, CU | 
| [user change-password](cloudhsm_cli-user-change-password.md) | Changes the passwords of users on the HSMs. Any user can change their own password. Admins can change anyone's password. | Admin, CU | 
| [user create](cloudhsm_cli-user-create.md) | Creates a user in your AWS CloudHSM cluster. | Admin | 
| [user delete](cloudhsm_cli-user-delete.md) | Deletes a user in your AWS CloudHSM cluster. | Admin | 
| [user list](cloudhsm_cli-user-list.md) | Lists the users in your AWS CloudHSM cluster. | All [1](#cli-ref-1), including unauthenticated users. Login is not required. | 
| [user change-quorum token-sign register](cloudhsm_cli-user-chqm-token-reg.md) | Registers the quorum token-sign quorum strategy for a user. | Admin | 

**Annotations**
+ [1] All users includes all listed roles and users not logged in.

# The cluster category in CloudHSM CLI
<a name="cloudhsm_cli-cluster"></a>

In the CloudHSM CLI, **cluster** is a parent category for a group of commands that, when combined with the parent category, create a command specific to clusters. Currently, the cluster category consists of the following commands:

**Topics**
+ [activate](cloudhsm_cli-cluster-activate.md)
+ [hsm-info](cloudhsm_cli-cluster-hsm-info.md)
+ [mtls](cloudhsm_cli-cluster-mtls.md)

# Activate a cluster with CloudHSM CLI
<a name="cloudhsm_cli-cluster-activate"></a>

Use the **cluster activate** command in CloudHSM CLI to [activate a new cluster](activate-cluster.md) in AWS CloudHSM. This command must be run before the cluster can be used to perform cryptographic operations.

## User type
<a name="cluster-activate-userType"></a>

The following types of users can run this command.
+ Unactivated admin

## Syntax
<a name="chsm-cli-cluster-activate-syntax"></a>

This command has no parameters.

```
aws-cloudhsm > help cluster activate
Activate a cluster

This command will set the initial Admin password. This process will cause your CloudHSM cluster to
move into the ACTIVE state.

USAGE:
    cloudhsm-cli cluster activate [OPTIONS] [--password <PASSWORD>]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --password <PASSWORD>
          Optional: Plaintext activation password If you do not include this argument you will be prompted for it

  -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="chsm-cli-cluster-activate-examples"></a>

This command activates your cluster by setting the initial password for you admin user.

```
aws-cloudhsm > cluster activate
Enter password:
Confirm password:
{
  "error_code": 0,
  "data": "Cluster activation successful"
}
```

## Related topics
<a name="chsm-cluster-activate-seealso"></a>
+ [user create](cloudhsm_cli-user-create.md)
+ [user delete](cloudhsm_cli-user-delete.md)
+ [user change-password](cloudhsm_cli-user-change-password.md)

# List HSMs with CloudHSM CLI
<a name="cloudhsm_cli-cluster-hsm-info"></a>

Use the **cluster hsm-info** command in CloudHSM CLI to list the hardware security modules (HSMs) in your AWS CloudHSM cluster. You do not need to be logged in to CloudHSM CLI to run this command.

**Note**  
If you add or delete HSMs, update the configuration files that the AWS CloudHSM client and the command line tools use. Otherwise, the changes that you make might not be effective on all HSMs in the cluster.

## User type
<a name="chsm-cluster-hsm-info-userType"></a>

The following types of users can run this command.
+ All users. You do not need to be logged in to run this command.

## Syntax
<a name="chsm-cluster-hsm-info-syntax"></a>

```
aws-cloudhsm > help cluster hsm-info
List info about each HSM in the cluster

Usage: cloudhsm-cli cluster hsm-info [OPTIONS]

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
  -h, --help                     Print help
```

## Example
<a name="chsm-cluster-hsm-info-examples"></a>

This command lists the HSMs present in your AWS CloudHSM cluster.

```
aws-cloudhsm > cluster hsm-info
{
  "error_code": 0,
  "data": {
    "hsms": [
      {
        "vendor": "Marvell Semiconductors, Inc.",
        "model": "NITROX-III CNN35XX-NFBE",
        "serial-number": "5.3G1941-ICM000590",
        "hardware-version-major": "5",
        "hardware-version-minor": "3",
        "firmware-version-major": "2",
        "firmware-version-minor": "6",
        "firmware-build-number": "16",
        "firmware-id": "CNN35XX-NFBE-FW-2.06-16"
        "fips-state": "2 [FIPS mode with single factor authentication]"
      },
      {
        "vendor": "Marvell Semiconductors, Inc.",
        "model": "NITROX-III CNN35XX-NFBE",
        "serial-number": "5.3G1941-ICM000625",
        "hardware-version-major": "5",
        "hardware-version-minor": "3",
        "firmware-version-major": "2",
        "firmware-version-minor": "6",
        "firmware-build-number": "16",
        "firmware-id": "CNN35XX-NFBE-FW-2.06-16"
        "fips-state": "2 [FIPS mode with single factor authentication]"
      },
      {
        "vendor": "Marvell Semiconductors, Inc.",
        "model": "NITROX-III CNN35XX-NFBE",
        "serial-number": "5.3G1941-ICM000663",
        "hardware-version-major": "5",
        "hardware-version-minor": "3",
        "firmware-version-major": "2",
        "firmware-version-minor": "6",
        "firmware-build-number": "16",
        "firmware-id": "CNN35XX-NFBE-FW-2.06-16"
        "fips-state": "2 [FIPS mode with single factor authentication]"
      }
    ]
  }
}
```

The output has the following attributes:
+ **Vendor**: The vendor name of the HSM. 
+ **Model**: The model number of the HSM.
+ **Serial-number**: The serial number of the HSM. This may change due to replacements.
+ **Hardware-version-major**: The major hardware version.
+ **Hardware-version-minor**: The minor hardware version.
+ **Firmware-version-major**: The major firmware version.
+ **Firmware-version-minor**: The minor firmware version.
+ **Firmware-build-number**: The firmware build number.
+ **Firmware-id**: The firmware ID, which includes the major and minor versions along with the build.
+ **FIPS-state**: The FIPS mode the cluster and the HSMs in it. If in FIPS mode, the output is "2 [FIPS mode with single factor authentication]." If in non-FIPS mode, the output is "0 [non-FIPS mode with single factor authentication]".

## Related topics
<a name="chsm-cluster-hsm-info-seealso"></a>
+ [Activate a cluster with CloudHSM CLI](cloudhsm_cli-cluster-activate.md)

# The cluster mtls category in CloudHSM CLI
<a name="cloudhsm_cli-cluster-mtls"></a>

In CloudHSM CLI, **cluster mtls** is a parent category for a group of commands that, when combined with the parent category, create a command specific to AWS CloudHSM clusters. Currently, this category consists of the following commands:

**Topics**
+ [deregister-trust-anchor](cloudhsm_cli-cluster-mtls-deregister-trust-anchor.md)
+ [get-enforcement](cloudhsm_cli-cluster-mtls-get-enforcement.md)
+ [list-trust-anchors](cloudhsm_cli-cluster-mtls-list-trust-anchors.md)
+ [register-trust-anchor](cloudhsm_cli-cluster-mtls-register-trust-anchor.md)
+ [set-enforcement](cloudhsm_cli-cluster-mtls-set-enforcement.md)

# Deregister a trust anchor with CloudHSM CLI
<a name="cloudhsm_cli-cluster-mtls-deregister-trust-anchor"></a>

Use the **cluster mtls deregister-trust-anchor** command in CloudHSM CLI to deregister a trust anchor for mutual TLS between client and AWS CloudHSM.

## User type
<a name="cluster-mtls-deregister-trust-anchor-userType"></a>

The following users can run this command.
+ Admin

## Requirements
<a name="cluster-mtls-deregister-trust-anchor-requirements"></a>
+ To run this command, you must be logged in as a admin user.

## Syntax
<a name="cluster-mtls-deregister-trust-anchor-syntax"></a>

```
aws-cloudhsm > help cluster mtls deregister-trust-anchor
            
Deregister a trust anchor for mtls

Usage: cluster mtls deregister-trust-anchor [OPTIONS] --certificate-reference [<CERTIFICATE_REFERENCE>...]

Options:
      --certificate-reference <CERTIFICATE_REFERENCE>  A hexadecimal or decimal certificate reference
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --approval <APPROVAL>  Filepath of signed quorum token file to approve operation
  -h, --help                     Print help
```

## Example
<a name="cluster-mtls-deregister-trust-anchor-examples"></a>

**Example**  
In the following example, this command removes a trust anchor from the HSM.  

```
aws-cloudhsm > cluster mtls deregister-trust-anchor --certificate-reference 0x01
                
{
  "error_code": 0,
  "data": {
    "message": "Trust anchor with reference 0x01 deregistered successfully"
  }
}
```
You can then run the **list-trust-anchors** command to confirm that trust anchor has been deregistered from the AWS CloudHSM:  

```
aws-cloudhsm > cluster mtls list-trust-anchors
                
{
  "error_code": 0,
  "data": {
    "trust_anchors": []
  }
}
```

## Arguments
<a name="cluster-mtls-deregister-trust-anchor-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

** *<CERTIFICATE\$1REFERENCE>* **  
A hexadecimal or decimal certificate reference.  
 **Required**: Yes  
After you deregister a trust anchor in the cluster, all existing mTLS connections using the client certificate signed by that trust anchor will be dropped.

** *<APPROVAL>* **  
Specifies the file path to a signed quorum token file to approve operation. Only required if quorum cluster service quorum value is greater than 1.

## Related topics
<a name="cluster-mtls-deregister-trust-anchor-seealso"></a>
+  [cluster mtls reregister-trust-anchor](cloudhsm_cli-cluster-mtls-register-trust-anchor.md) 
+  [cluster mtls list-trust-anchors](cloudhsm_cli-cluster-mtls-list-trust-anchors.md) 
+  [Setup mTLS (recommended)](getting-started-setup-mtls.md) 

# Get the mTLS enforcement level with CloudHSM CLI
<a name="cloudhsm_cli-cluster-mtls-get-enforcement"></a>

Use the **cluster mtls get-enforcement** command in CloudHSM CLI to get the enforcement level of the usage of mutual TLS between client and AWS CloudHSM.

## User type
<a name="cluster-mtls-get-enforcement-userType"></a>

The following users can run this command.
+ Admin
+ Crypto users (CUs)

## Requirements
<a name="cluster-mtls-get-enforcement-requirements"></a>
+ To run this command, you must be logged in as a admin user or crypto user (CUs).

## Syntax
<a name="cluster-mtls-get-enforcement-syntax"></a>

```
aws-cloudhsm > help cluster mtls get-enforcement
            
Get the status of mtls enforcement in the cluster

Usage: cluster mtls get-enforcement [OPTIONS]

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
  -h, --help                     Print help
```

## Example
<a name="cluster-mtls-get-enforcement-examples"></a>

**Example**  
In the following example, this command lists the mtls enforcement level of the AWS CloudHSM.  

```
aws-cloudhsm > cluster mtls get-enforcement
                
{
  "error_code": 0,
  "data": {
    "mtls-enforcement-level": "none"
  }
}
```

## Arguments
<a name="cluster-mtls-get-enforcement-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

## Related topics
<a name="cluster-mtls-get-enforcement-seealso"></a>
+  [cluster mtls set-enforcement](cloudhsm_cli-cluster-mtls-set-enforcement.md) 
+  [Setup mTLS (recommended)](getting-started-setup-mtls.md) 

# List trust anchors with CloudHSM CLI
<a name="cloudhsm_cli-cluster-mtls-list-trust-anchors"></a>

Use the **cluster mtls list-trust-anchors** command in CloudHSM CLI to list all the trust anchors which can be used for mutual TLS between client and AWS CloudHSM.

## User type
<a name="cluster-mtls-list-trust-anchors-userType"></a>

The following users can run this command.
+ All users. You do not need to be logged in to run this command.

## Syntax
<a name="cluster-mtls-list-trust-anchors-syntax"></a>

```
aws-cloudhsm > help cluster mtls list-trust-anchors
            
List all trust anchors for mtls

Usage: cluster mtls list-trust-anchors [OPTIONS]

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
  -h, --help                     Print help
```

## Example
<a name="cluster-mtls-list-trust-anchors-examples"></a>

**Example**  
In the following example, this command lists all the registered trust anchors from the AWS CloudHSM.  

```
aws-cloudhsm > cluster mtls list-trust-anchors
                
{
  "error_code": 0,
  "data": {
    "trust_anchors": [
      {
        "certificate-reference": "0x01",
        "certificate": "<PEM Encoded Certificate 1>",
        "cluster-coverage": "full"
      },
      {
        "certificate-reference": "0x02",
        "certificate": "<PEM Encoded Certificate 2>",
        "cluster-coverage": "full"
      }
    ]
  }
}
```

## Arguments
<a name="cluster-mtls-list-trust-anchors-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

## Related topics
<a name="cluster-mtls-register-trust-anchor-seealso"></a>
+  [cluster mtls reregister-trust-anchor](cloudhsm_cli-cluster-mtls-register-trust-anchor.md) 
+  [cluster mtls deregister-trust-anchor](cloudhsm_cli-cluster-mtls-deregister-trust-anchor.md) 
+  [Setup mTLS (recommended)](getting-started-setup-mtls.md) 

# Register a trust anchor with CloudHSM CLI
<a name="cloudhsm_cli-cluster-mtls-register-trust-anchor"></a>

Use the **cluster mtls register-trust-anchor** command in CloudHSM CLI to register a trust anchor for mutual TLS between client and AWS CloudHSM.

## User type
<a name="cluster-mtls-register-trust-anchor-userType"></a>

The following users can run this command.
+ Admin

## Requirements
<a name="cluster-mtls-register-trust-anchor-requirements"></a>

The AWS CloudHSM accepts trust anchors with the following key types:


****  

| Key Type | Description | 
| --- | --- | 
| EC |  secp256r1 (P-256), secp384r1 (P-384), and secp521r1 (P-521) curves.  | 
| RSA |  2048-bit, 3072-bit, and 4096-bit RSA keys.  | 

## Syntax
<a name="cluster-mtls-register-trust-anchor-syntax"></a>

```
aws-cloudhsm > help cluster mtls register-trust-anchor
            
Register a trust anchor for mtls

Usage: cluster mtls register-trust-anchor [OPTIONS] --path [<PATH>...]

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --path <PATH>  Filepath of the trust anchor to register
      --approval <APPROVAL>  Filepath of signed quorum token file to approve operation
  -h, --help                     Print help
```

## Example
<a name="cluster-mtls-register-trust-anchor-examples"></a>

**Example**  
In the following example, this command registers a trust anchor onto the HSM. The maximum number of trust anchors can be registered is two (2).  

```
aws-cloudhsm > cluster mtls register-trust-anchor --path /home/rootCA
                
{
  "error_code": 0,
  "data": {
    "trust_anchor": {
      "certificate-reference": "0x01",
      "certificate": "<PEM Encoded Certificate>",
      "cluster-coverage": "full"
    }
  }
}
```
You can then run the **list-trust-anchors** command to confirm that trust anchor has been registered onto the AWS CloudHSM:  

```
aws-cloudhsm > cluster mtls list-trust-anchors
                
{
  "error_code": 0,
  "data": {
    "trust_anchors": [
      {
        "certificate-reference": "0x01",
        "certificate": "<PEM Encoded Certificate>",
        "cluster-coverage": "full"
      }
    ]
  }
}
```

## Arguments
<a name="cluster-mtls-register-trust-anchor-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

** *<PATH>* **  
Filepath of the trust anchor to register.  
 **Required**: Yes  
AWS CloudHSM supports registering intermediate certificates as trust anchor. In such cases, the entire PEM-encoded certificate chain file needs to be registered onto the HSM, with the certificates in hierarchical order.   
 AWS CloudHSM supports a certificate chain of 6980 bytes.

** *<APPROVAL>* **  
Specifies the file path to a signed quorum token file to approve operation. Only required if quorum cluster service quorum value is greater than 1.

## Related topics
<a name="cluster-mtls-register-trust-anchor-seealso"></a>
+  [cluster mtls deregister-trust-anchor](cloudhsm_cli-cluster-mtls-deregister-trust-anchor.md) 
+  [cluster mtls list-trust-anchors](cloudhsm_cli-cluster-mtls-list-trust-anchors.md) 
+  [Setup mTLS (recommended)](getting-started-setup-mtls.md) 

# Set the mTLS enforcement level with CloudHSM CLI
<a name="cloudhsm_cli-cluster-mtls-set-enforcement"></a>

Use the **cluster mtls set-enforcement** command in CloudHSM CLI to set the enforcement level of the usage of mutual TLS between client and AWS CloudHSM.

## User type
<a name="cluster-mtls-set-enforcement-userType"></a>

The following users can run this command.
+ Admin with username as admin

## Requirements
<a name="cluster-mtls-set-enforcement-requirements"></a>

To run this command:
+ At least one trust anchor has been successfully registered onto the AWS CloudHSM.
+ Configure the CloudHSM CLI with the right private key and client certificate, and start CloudHSM CLI under a mutual TLS connection.
+ You must be logged in as the default admin with username "admin". Any other admin user will not be able to run this command.

## Syntax
<a name="cluster-mtls-set-enforcement-syntax"></a>

```
aws-cloudhsm > help cluster mtls set-enforcement
            
Set mtls enforcement policy in the cluster

Usage: cluster mtls set-enforcement [OPTIONS] --level [<LEVEL>...]

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --level <LEVEL>  Level to be set for mtls in the cluster [possible values: none, cluster]
      --approval <APPROVAL>  Filepath of signed quorum token file to approve operation
  -h, --help                     Print help
```

## Example
<a name="cluster-mtls-set-enforcement-examples"></a>

**Example**  
In the following example, this command set the mtls enforcement level of the AWS CloudHSM to be cluster. The set-enforcement command can only be performed in a mutual TLS connection and logged in as the admin user with username as admin, see [set the mTLS enforcement for AWS CloudHSM](getting-started-setup-mtls.md#getting-start-setup-mtls-enforcement).  

```
aws-cloudhsm > cluster mtls set-enforcement --level cluster
                
{
  "error_code": 0,
  "data": {
    "message": "Mtls enforcement level set to Cluster successfully"
  }
}
```
You can then run the **get-enforcement** command to confirm that enforcement level has been set to cluster:  

```
aws-cloudhsm > cluster mtls get-enforcement
                
{
  "error_code": 0,
  "data": {
    "mtls-enforcement-level": "cluster"
  }
}
```

## Arguments
<a name="cluster-mtls-set-enforcement-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

** *<LEVEL>* **  
Level to be set for mtls in the cluster.   
 **Valid values**   
+  **cluster**: Enforce the usage of mutual TLS between client and AWS CloudHSM in the cluster.
+  **none**: Do not enforce the usage of mutual TLS between client and AWS CloudHSM in the cluster.
 **Required**: Yes  
After you enforce mTLS usage in the cluster, all existing non-mTLS connections will be dropped and you can only connect to the cluster with mTLS certificates.

** *<APPROVAL>* **  
Specifies the file path to a signed quorum token file to approve operation. Only required if quorum cluster service quorum value is greater than 1.

## Related topics
<a name="cluster-mtls-set-enforcement-seealso"></a>
+  [cluster mtls get-enforcement](cloudhsm_cli-cluster-mtls-get-enforcement.md) 
+  [Setup mTLS (recommended)](getting-started-setup-mtls.md) 

# The crypto category in CloudHSM CLI
<a name="cloudhsm_cli-crypto"></a>

In the CloudHSM CLI, **crypto** is a parent category for a group of commands that, when combined with the parent category, create a command specific to cryptographic operations. Currently, this category consists of the following commands: 
+ [sign](cloudhsm_cli-crypto-sign.md)
  + [ecdsa](cloudhsm_cli-crypto-sign-ecdsa.md)
  + [ed25519ph](cloudhsm_cli-crypto-sign-ed25519ph.md)
  + [rsa-pkcs](cloudhsm_cli-crypto-sign-rsa-pkcs.md)
  + [rsa-pkcs-pss](cloudhsm_cli-crypto-sign-rsa-pkcs-pss.md)
+ [verify](cloudhsm_cli-crypto-verify.md)
  + [ecdsa](cloudhsm_cli-crypto-verify-ecdsa.md)
  + [ed25519ph](cloudhsm_cli-crypto-verify-ed25519ph.md)
  + [rsa-pkcs](cloudhsm_cli-crypto-verify-rsa-pkcs.md)
  + [rsa-pkcs-pss](cloudhsm_cli-crypto-verify-rsa-pkcs-pss.md)

# The crypto sign category in CloudHSM CLI
<a name="cloudhsm_cli-crypto-sign"></a>

In the CloudHSM CLI, **crypto sign** is a parent category for a group of commands that, when combined with the parent category, uses a chosen private key in your AWS CloudHSM cluster to generate a signature. **crypto sign** has the following subcommands:
+ [Generate a signature with the ECDSA mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-ecdsa.md)
+ [Generate a signature with the HashEdDSA mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-ed25519ph.md)
+ [Generate a signature with the RSA-PKCS mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-rsa-pkcs.md)
+ [Generate a signature with the RSA-PKCS-PSS mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-rsa-pkcs-pss.md)

To use **crypto sign**, you must have a private key in your HSM. You can generate a private key with the following commands:
+ [key generate-asymmetric-pair ec](cloudhsm_cli-key-generate-asymmetric-pair-ec.md)
+ [key generate-asymmetric-pair rsa](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md)

# Generate a signature with the ECDSA mechanism in CloudHSM CLI
<a name="cloudhsm_cli-crypto-sign-ecdsa"></a>

Use the **crypto sign ecdsa** command in CloudHSM CLI to generate a signature using an EC private key and the ECDSA signing mechanism. 

To use the **crypto sign ecdsa** command, you must first have an EC private key in your AWS CloudHSM cluster. You can generate an EC private key using the [Generate an asymmetric EC key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-ec.md) command with the `sign` attribute set to `true`.

The resulting ECDSA signature is generated in the format `r||s`, where the r and s components are concatenated as raw binary data and returned in base64 encoded format.

**Note**  
Signatures can be verified in AWS CloudHSM with [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) subcommands.

## User type
<a name="cloudhsm_cli-crypto-sign-ecdsa-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-crypto-sign-ecdsa-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-crypto-sign-ecdsa-syntax"></a>

```
aws-cloudhsm > help crypto sign ecdsa
Sign with the ECDSA mechanism

Usage: crypto sign ecdsa --key-filter [<KEY_FILTER>>...] --hash-function <HASH_FUNCTION> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --key-filter [<KEY_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key
      --hash-function <HASH_FUNCTION>
          [possible values: sha1, sha224, sha256, sha384, sha512]
      --data-path <DATA_PATH>
          The path to the file containing the data to be signed
      --data <DATA>
          Base64 Encoded data to be signed
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
      --data-type <DATA_TYPE>
          The type of data passed in, either raw or digest [possible values: raw, digest]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-crypto-sign-ecdsa-examples"></a>

These examples show how to use **crypto sign ecdsa** to generate a signature using the ECDSA signing mechanism and `SHA256` hash function. This command uses a private key in the HSM.

**Example: Generate a signature for base 64 encoded data**  

```
aws-cloudhsm > crypto sign ecdsa --key-filter attr.label=ec-private --hash-function sha256 --data YWJjMTIz
{
  "error_code": 0,
  "data": {
    "key-reference": "0x00000000007808dd",
    "signature": "4zki+FzjhP7Z/KqoQvh4ueMAxQQVp7FQguZ2wOS3Q5bzk+Hc5irV5iTkuxQbropPttVFZ8V6FgR2fz+sPegwCw=="
  }
}
```

**Example: Generate a signature for a data file**  

```
aws-cloudhsm > crypto sign ecdsa --key-filter attr.label=ec-private --hash-function sha256 --data-path data.txt
{
  "error_code": 0,
  "data": {
    "key-reference": "0x00000000007808dd",
    "signature": "4zki+FzjhP7Z/KqoQvh4ueMAxQQVp7FQguZ2wOS3Q5bzk+Hc5irV5iTkuxQbropPttVFZ8V6FgR2fz+sPegwCw=="
  }
}
```

## Arguments
<a name="cloudhsm_cli-crypto-sign-ecdsa-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<DATA>***  
Base64 encoded data to be signed.  
Required: Yes (unless provided through data path)

***<DATA\$1PATH>***  
Specifies the location of the data to be signed.  
Required: Yes (unless provided through data path)

***<HASH\$1FUNCTION>***  
Specifies the hash function.   
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<KEY\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of attr.KEY\$1ATTRIBUTE\$1NAME=KEY\$1ATTRIBUTE\$1VALUE to select a matching key.  
For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI.  
Required: Yes

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key usage service quorum value of the private key is greater than 1.

***<DATA\$1TYPE>***  
 Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed.   
Valid values:  
+ raw
+ digest

## Related topics
<a name="cloudhsm_cli-crypto-sign-ecdsa-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# Generate a signature with the HashEdDSA mechanism in CloudHSM CLI
<a name="cloudhsm_cli-crypto-sign-ed25519ph"></a>

**Important**  
HashEdDSA signing operations are only supported on hsm2m.medium instances in non-FIPS mode.

Use the **crypto sign ed25519ph** command in CloudHSM CLI to generate a signature using an Ed25519 private key and the HashEdDSA signing mechanism. For additional information on HashEdDSA, see [NIST SP 186-5, Section 7.8](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf).

To use the **crypto sign ed25519ph** command, you must first have an Ed25519 private key in your AWS CloudHSM cluster. You can generate an Ed25519 private key using the [Generate an asymmetric EC key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-ec.md) command with the `curve` parameter set to `ed25519` and the `sign` attribute set to `true`.

**Note**  
Signatures can be verified in AWS CloudHSM with [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) subcommands.

## User type
<a name="cloudhsm_cli-crypto-sign-ed25519ph-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-crypto-sign-ed25519ph-requirements"></a>
+ To run this command, you must be logged in as a CU.
+ HashEdDSA signing operations are only supported on hsm2m.medium instances in non-FIPS mode.

## Syntax
<a name="cloudhsm_cli-crypto-sign-ed25519ph-syntax"></a>

```
aws-cloudhsm > help crypto sign ed25519ph
Sign with the Ed25519ph mechanism

Usage: crypto sign ed25519ph [OPTIONS] --key-filter [<KEY_FILTER>...] --data-type <DATA_TYPE> --hash-function <HASH_FUNCTION> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --key-filter [<KEY_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key
      --data-path <DATA_PATH>
          The path to the file containing the data to be signed
      --data <DATA>
          Base64 Encoded data to be signed
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
      --data-type <DATA_TYPE>
          The type of data passed in, either raw or digest [possible values: raw, digest]
      --hash-function <HASH_FUNCTION>
          Hash function [possible values: sha512]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-crypto-sign-ed25519ph-examples"></a>

These examples show how to use **crypto sign ed25519ph** to generate a signature using the Ed25519ph signing mechanism and `sha512` hash function. This command uses a private key in the HSM.

**Example: Generate a signature for base 64 encoded data**  

```
aws-cloudhsm > crypto sign ed25519ph \
    --key-filter attr.label=ed25519-private \
    --data-type raw \
    --hash-function sha512 \
    --data YWJj
{
  "error_code": 0,
  "data": {
    "key-reference": "0x0000000000401cdf",
    "signature": "mKcCIvC4Ehqp0w+BPWg/gJ5GK0acf/h2OUmbuU5trkEx+FBCRjwqNVogA9BirfWqoQuMYeY2Biqq0RwqJgg0Bg=="
  }
}
```

**Example: Generate a signature for a data file**  

```
aws-cloudhsm > crypto sign ed25519ph \
    --key-filter attr.label=ed25519-private \
    --data-type raw \
    --hash-function sha512 \
    --data-path data.txt
{
  "error_code": 0,
  "data": {
    "key-reference": "0x0000000000401cdf",
    "signature": "mKcCIvC4Ehqp0w+BPWg/gJ5GK0acf/h2OUmbuU5trkEx+FBCRjwqNVogA9BirfWqoQuMYeY2Biqq0RwqJgg0Bg=="
  }
}
```

## Arguments
<a name="cloudhsm_cli-crypto-sign-ed25519ph-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<DATA>***  
Base64 encoded data to be signed.  
Required: Yes (unless provided through data path)

***<DATA\$1PATH>***  
Specifies the location of the data to be signed.  
Required: Yes (unless provided through data parameter)

***<HASH\$1FUNCTION>***  
Specifies the hash function. Ed25519ph only supports SHA512.   
Valid values:  
+ sha512
Required: Yes

***<KEY\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of attr.KEY\$1ATTRIBUTE\$1NAME=KEY\$1ATTRIBUTE\$1VALUE to select a matching key.  
For a list of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: Yes

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key usage service quorum value of the private key is greater than 1.

***<DATA\$1TYPE>***  
 Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed.   
Valid values:  
+ raw
+ digest
Required: Yes

## Related topics
<a name="cloudhsm_cli-crypto-sign-ed25519ph-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# Generate a signature with the RSA-PKCS mechanism in CloudHSM CLI
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs"></a>

Use the **crypto sign rsa-pkcs** command in CloudHSM CLI to generate a signature using an RSA private key and the RSA-PKCS signing mechanism.

To use the **crypto sign rsa-pkcs** command, you must first have a RSA private key in your AWS CloudHSM cluster. You can generate an RSA private key using the [Generate an asymmetric RSA key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md) command with the `sign` attribute set to `true`.

**Note**  
Signatures can be verified in AWS CloudHSM with [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) subcommands.

## User type
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-syntax"></a>

```
aws-cloudhsm > help crypto sign rsa-pkcs
Sign with the RSA-PKCS mechanism

Usage: crypto sign rsa-pkcs --key-filter [<KEY_FILTER>>...] --hash-function <HASH_FUNCTION> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --key-filter [<KEY_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key
      --hash-function <HASH_FUNCTION>
          [possible values: sha1, sha224, sha256, sha384, sha512]
      --data-path <DATA_PATH>
          The path to the file containing the data to be signed
      --data <DATA>
          Base64 Encoded data to be signed
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
      --data-type <DATA_TYPE>
          The type of data passed in, either raw or digest [possible values: raw, digest]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-examples"></a>

These examples show how to use **crypto sign rsa-pkcs** to generate a signature using the RSA-PKCS signing mechanism and `SHA256` hash function. This command uses a private key in the HSM.

**Example: Generate a signature for base 64 encoded data**  

```
aws-cloudhsm > crypto sign rsa-pkcs --key-filter attr.label=rsa-private --hash-function sha256 --data YWJjMTIz
{
  "error_code": 0,
  "data": {
    "key-reference": "0x00000000007008db",
    "signature": "XJ7mRyHnDRYrDWTQuuNb+5mhoXx7VTsPMjgOQW4iMN7E42eNHj2Q0oovMmBdHUEH0F4HYG8FBJOBhvGuM8J/z6y41GbowVpUT6WzjnIQs79K9i7i6oR1TYjLnIS3r/zkimuXcS8/ZxyDzru+GO9BUT9FFU/of9cvu4Oyn6a5+IXuCbKNQs19uASuFARUTZ0a0Ny1CB1MulxUpqGTmI91J6evlP7k/2khwDmJ5E8FEar5/Cvbn9t21p3Uj561ngTXrYbIZ2KHpef9jQh/cEIvFLG61sexJjQi8EdTxeDA+I3ITO0qrvvESvA9+Sj7kdG2ceIicFS8/8LwyxiIC31UHQ=="
  }
}
```

**Example: Generate a signature for a data file**  

```
aws-cloudhsm > crypto sign rsa-pkcs --key-filter attr.label=rsa-private --hash-function sha256 --data-path data.txt
{
  "error_code": 0,
  "data": {
    "key-reference": "0x00000000007008db",
    "signature": "XJ7mRyHnDRYrDWTQuuNb+5mhoXx7VTsPMjgOQW4iMN7E42eNHj2Q0oovMmBdHUEH0F4HYG8FBJOBhvGuM8J/z6y41GbowVpUT6WzjnIQs79K9i7i6oR1TYjLnIS3r/zkimuXcS8/ZxyDzru+GO9BUT9FFU/of9cvu4Oyn6a5+IXuCbKNQs19uASuFARUTZ0a0Ny1CB1MulxUpqGTmI91J6evlP7k/2khwDmJ5E8FEar5/Cvbn9t21p3Uj561ngTXrYbIZ2KHpef9jQh/cEIvFLG61sexJjQi8EdTxeDA+I3ITO0qrvvESvA9+Sj7kdG2ceIicFS8/8LwyxiIC31UHQ=="
  }
}
```

## Arguments
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<DATA>***  
Base64 encoded data to be signed.  
Required: Yes (unless provided through data path)

***<DATA\$1PATH>***  
Specifies the location of the data to be signed.  
Required: Yes (unless provided through data)

***<HASH\$1FUNCTION>***  
Specifies the hash function.   
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<KEY\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key.  
For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI.  
Required: Yes

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key usage service quorum value of the private key is greater than 1.

***<DATA\$1TYPE>***  
 Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed.   
For RSA-PKCS, the data must be passed in DER encoded format as specified in [RFC 8017, Section 9.2](https://www.rfc-editor.org/rfc/rfc8017#section-9.2)  
Valid values:  
+ raw
+ digest

## Related topics
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# Generate a signature with the RSA-PKCS-PSS mechanism in CloudHSM CLI
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-pss"></a>

Use the **crypto sign rsa-pkcs-pss** command in CloudHSM CLI to generate a signature using an RSA private key and the `RSA-PKCS-PSS` signing mechanism.

To use the **crypto sign rsa-pkcs-pss** command, you must first have a RSA private key in your AWS CloudHSM cluster. You can generate an RSA private key using the [Generate an asymmetric RSA key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md) command with the `sign` attribute set to `true`.

**Note**  
Signatures can be verified in AWS CloudHSM with [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) subcommands.

## User type
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-syntax"></a>

```
aws-cloudhsm > help crypto sign rsa-pkcs-pss
Sign with the RSA-PKCS-PSS mechanism

Usage: crypto sign rsa-pkcs-pss [OPTIONS] --key-filter [<KEY_FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF> --salt-length <SALT_LENGTH> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>        Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --key-filter [<KEY_FILTER>...]   Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key
      --hash-function <HASH_FUNCTION>  [possible values: sha1, sha224, sha256, sha384, sha512]
      --data-path <DATA_PATH>          The path to the file containing the data to be signed
      --data <DATA>                    Base64 Encoded data to be signed
      --mgf <MGF>                      The mask generation function [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
      --salt-length <SALT_LENGTH>      The salt length
      --approval <APPROVAL>            Filepath of signed quorum token file to approve operation
      --data-type <DATA_TYPE>          The type of data passed in, either raw or digest [possible values: raw, digest]
  -h, --help                           Print help
```

## Example
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-examples"></a>

These examples show how to use **crypto sign rsa-pkcs-pss** to generate a signature using the `RSA-PKCS-PSS` signing mechanism and `SHA256` hash function. This command uses a private key in the HSM.

**Example: Generate a signature for base 64 encoded data**  

```
aws-cloudhsm > crypto sign rsa-pkcs-pss --key-filter attr.label=rsa-private --hash-function sha256 --data YWJjMTIz --salt-length 10 --mgf mgf1-sha256
{
  "error_code": 0,
  "data": {
    "key-reference": "0x00000000007008db",
    "signature": "H/z1rYVMzNAa31K4amE5MTiwGxDdCTgQXCJXRBKVOVm7ZuyI0fGE4sT/BUN+977mQEV2TqtWpTsiF2IpwGM1VfSBRt7h/g4o6YERm1tTQLl7q+AJ7uGGK37zCsWQrAo7Vy8NzPShxekePo/ZegrB1aHWN1fE8H3IPUKqLuMDI9o1Jq6kM986ExS7YmeOIclcZkyykTWqHLQVL2C3+A2bHJZBqRcM5XoIpk8HkPypjpN+m4FNUds30GAemoOMl6asSrEJSthaZWV53OBsDOqzA8Rt8JdhXS+GZp3vNLdL1OTBELDPweXVgAu4dBX0FOvpw/gg6sNvuaDK4YOBv2fqKg=="
  }
}
```

**Example: Generate a signature for a data file**  

```
aws-cloudhsm > crypto sign rsa-pkcs-pss --key-filter attr.label=rsa-private --hash-function sha256 --data-path data.txt --salt-length 10 --mgf mgf1-sha256
{
  "error_code": 0,
  "data": {
    "key-reference": "0x00000000007008db",
    "signature": "H/z1rYVMzNAa31K4amE5MTiwGxDdCTgQXCJXRBKVOVm7ZuyI0fGE4sT/BUN+977mQEV2TqtWpTsiF2IpwGM1VfSBRt7h/g4o6YERm1tTQLl7q+AJ7uGGK37zCsWQrAo7Vy8NzPShxekePo/ZegrB1aHWN1fE8H3IPUKqLuMDI9o1Jq6kM986ExS7YmeOIclcZkyykTWqHLQVL2C3+A2bHJZBqRcM5XoIpk8HkPypjpN+m4FNUds30GAemoOMl6asSrEJSthaZWV53OBsDOqzA8Rt8JdhXS+GZp3vNLdL1OTBELDPweXVgAu4dBX0FOvpw/gg6sNvuaDK4YOBv2fqKg=="
  }
}
```

## Arguments
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<DATA>***  
Base64 encoded data to be signed.  
Required: Yes (unless provided through data path)

***<DATA\$1PATH>***  
Specifies the location of the data to be signed.  
Required: Yes (unless provided through data)

***<HASH\$1FUNCTION>***  
Specifies the hash function.   
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<KEY\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key.  
For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI.  
Required: Yes

***<MGF>***  
Specifies the mask generation function.  
The mask generation function hash function must match the signing mechanism hash function.
Valid values:  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
Required: Yes

***<SALT\$1LENGTH>***  
Specifies the salt length.  
Required: Yes

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key usage service quorum value of the private key is greater than 1.

***<DATA\$1TYPE>***  
 Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed.   
Valid values:  
+ raw
+ digest

## Related topics
<a name="cloudhsm_cli-crypto-sign-rsa-pkcs-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

## Related topics
<a name="cloudhsm_cli-crypto-sign-seealso"></a>
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# The crypto verify category in CloudHSM CLI
<a name="cloudhsm_cli-crypto-verify"></a>

In the CloudHSM CLI, **crypto verify** is a parent category for a group of commands that, when combined with the parent category, confirms whether a file has been signed by a given key. **crypto verify** has the following subcommands: 
+ [crypto verify ecdsa](cloudhsm_cli-crypto-verify-ecdsa.md)
+ [crypto verify ed25519ph](cloudhsm_cli-crypto-verify-ed25519ph.md)
+ [crypto verify rsa-pkcs](cloudhsm_cli-crypto-verify-rsa-pkcs.md)
+ [crypto verify rsa-pkcs-pss](cloudhsm_cli-crypto-verify-rsa-pkcs-pss.md)

The **crypto verify** command compares a signed file against a source file and analyzes whether they are cryptographically related based on a given public key and signing mechanism.

**Note**  
Files can be signed in AWS CloudHSM with the [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) operation.

# Verify a signature signed with the ECDSA mechanism in CloudHSM CLI
<a name="cloudhsm_cli-crypto-verify-ecdsa"></a>

Use the **crypto verify ecdsa** command in CloudHSM CLI to complete the following operations:
+ Confirm a file has been signed in the HSM by a given public key.
+ Verify the signature was generated using the ECDSA signing mechanism.
+ Compare a signed file against a source file and determine whether the two are cryptographically related based on a given ecdsa public key and signing mechanism. 
+  The ECDSA verification function expects the signature in the format `r||s`, where the r and s components are concatenated as raw binary data. 

To use the **crypto verify ecdsa** command, you must first have an EC public key in your AWS CloudHSM cluster. You can import an EC public key using the [Import a PEM format key with CloudHSM CLI](cloudhsm_cli-key-import-pem.md) command with the `verify` attribute set to `true`.

**Note**  
You can generate a signature in CloudHSM CLI with [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) subcommands.

## User type
<a name="cloudhsm_cli-crypto-verify-ecdsa-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-crypto-verify-ecdsa-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-crypto-verify-ecdsa-syntax"></a>

```
aws-cloudhsm > help crypto verify ecdsa
Verify with the ECDSA mechanism

Usage: crypto verify ecdsa --key-filter [<KEY_FILTER>...] --hash-function <HASH_FUNCTION> <--data-path <DATA_PATH>|--data <DATA>> <--signature-path <SIGNATURE_PATH>|--signature <SIGNATURE>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --key-filter [<KEY_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key
      --hash-function <HASH_FUNCTION>
          [possible values: sha1, sha224, sha256, sha384, sha512]
      --data-path <DATA_PATH>
          The path to the file containing the data to be verified
      --data <DATA>
          Base64 encoded data to be verified
      --signature-path <SIGNATURE_PATH>
          The path to where the signature is located
      --signature <SIGNATURE>
          Base64 encoded signature to be verified
      --data-type <DATA_TYPE>
          The type of data passed in, either raw or digest [possible values: raw, digest]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-crypto-verify-ecdsa-examples"></a>

These examples show how to use **crypto verify ecdsa** to verify a signature that was generated using the ECDSA signing mechanism and `SHA256` hash function. This command uses a public key in the HSM.

**Example: Verify a Base64 encoded signature with Base64 encoded data**  

```
aws-cloudhsm > crypto verify ecdsa --hash-function sha256 --key-filter attr.label=ec-public --data YWJjMTIz --signature 4zki+FzjhP7Z/KqoQvh4ueMAxQQVp7FQguZ2wOS3Q5bzk+Hc5irV5iTkuxQbropPttVFZ8V6FgR2fz+sPegwCw==
{
  "error_code": 0,
  "data": {
    "message": "Signature verified successfully"
  }
}
```

**Example: Verify a signature file with a data file**  

```
aws-cloudhsm > crypto verify ecdsa --hash-function sha256 --key-filter attr.label=ec-public --data-path data.txt --signature-path signature-file
{
   "error_code": 0,
  "data": {
    "message": "Signature verified successfully"
  }
}
```

**Example: Prove false signing relationship**  
This command verifies whether the data located at `/home/data` was signed by a public key with the label `ecdsa-public` using the ECDSA signing mechanism to produce the signature located in `/home/signature`. Because the given arguments do not make up a true signing relationship, the command returns an error message.  

```
aws-cloudhsm > crypto verify ecdsa --hash-function sha256 --key-filter attr.label=ec-public --data aW52YWxpZA== --signature +ogk7M7S3iTqFg3SndJfd91dZFr5Qo6YixJl8JwcvqqVgsVuO6o+VKvTRjz0/V05kf3JJbBLr87Q+wLWcMAJfA==
{
  "error_code": 1,
  "data": "Signature verification failed"
}
```

## Arguments
<a name="cloudhsm_cli-crypto-verify-ecdsa-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<DATA>***  
Base64 encoded data to be signed.  
Required: Yes (unless provided through data path)

***<DATA\$1PATH>***  
Specifies the location of the data to be signed.  
Required: Yes (unless provided through data path)

***<HASH\$1FUNCTION>***  
Specifies the hash function.   
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<KEY\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key.  
For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI.  
Required: Yes

***<SIGNATURE>***  
Base64 encoded signature.  
Required: Yes (unless provided through signature path)

***<SIGNATURE\$1PATH>***  
Specifies the location of the signature.  
Required: Yes (unless provided through signature path)

***<DATA\$1TYPE>***  
 Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed.   
Valid values:  
+ raw
+ digest

## Related topics
<a name="cloudhsm_cli-crypto-verify-ecdsa-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# Verify a signature signed with the HashEdDSA mechanism in CloudHSM CLI
<a name="cloudhsm_cli-crypto-verify-ed25519ph"></a>

**Important**  
HashEdDSA signature verification operations are only supported on hsm2m.medium instances in non-FIPS mode.

Use the **crypto verify ed25519ph** command in CloudHSM CLI to complete the following operations:
+ Verify signatures of data or files using a given Ed25519 public key.
+ Confirm the signature was generated using the HashEdDSA signing mechanism. For additional information on HashEdDSA, see [NIST SP 186-5, Section 7.8](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf).

To use the **crypto verify ed25519ph** command, you must first have an Ed25519 public key in your AWS CloudHSM cluster. You can generate an Ed25519 key pair using the [Generate an asymmetric EC key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-ec.md) command with the `curve` parameter set to `ed25519` and the `verify` attribute set to `true`, or import an Ed25519 public key using the [Import a PEM format key with CloudHSM CLI](cloudhsm_cli-key-import-pem.md) command with the `verify` attribute set to `true`.

**Note**  
You can generate a signature in CloudHSM CLI with [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) subcommands.

## User type
<a name="cloudhsm_cli-crypto-verify-ed25519ph-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-crypto-verify-ed25519ph-requirements"></a>
+ To run this command, you must be logged in as a CU.
+ HashEdDSA signature verification operations are only supported on hsm2m.medium instances in non-FIPS mode.

## Syntax
<a name="cloudhsm_cli-crypto-verify-ed25519ph-syntax"></a>

```
aws-cloudhsm > help crypto verify ed25519ph
Verify with the Ed25519ph mechanism

Usage: crypto verify ed25519ph [OPTIONS] --key-filter [<KEY_FILTER>...] --data-type <DATA_TYPE> --hash-function <HASH_FUNCTION> <--data-path <DATA_PATH>|--data <DATA>> <--signature-path <SIGNATURE_PATH>|--signature <SIGNATURE>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --key-filter [<KEY_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key
      --data-path <DATA_PATH>
          The path to the file containing the data to be verified
      --data <DATA>
          Base64 encoded data to be verified
      --signature-path <SIGNATURE_PATH>
          The path to where the signature is located
      --signature <SIGNATURE>
          Base64 encoded signature to be verified
      --data-type <DATA_TYPE>
          The type of data passed in, either raw or digest [possible values: raw, digest]
      --hash-function <HASH_FUNCTION>
          Hash function [possible values: sha512]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-crypto-verify-ed25519ph-examples"></a>

These examples show how to use **crypto verify ed25519ph** to verify a signature that was generated using the Ed25519ph signing mechanism and `sha512` hash function. This command uses an Ed25519 public key in the HSM.

**Example: Verify a Base64 encoded signature with Base64 encoded data**  

```
aws-cloudhsm > crypto verify ed25519ph \
    --hash-function sha512 \
    --key-filter attr.label=ed25519-public \
    --data-type raw \
    --data YWJj \
    --signature mKcCIvC4Ehqp0w+BPWg/gJ5GK0acf/h2OUmbuU5trkEx+FBCRjwqNVogA9BirfWqoQuMYeY2Biqq0RwqJgg0Bg==
{
  "error_code": 0,
  "data": {
    "message": "Signature verified successfully"
  }
}
```

**Example: Verify a signature file with a data file**  

```
aws-cloudhsm > crypto verify ed25519ph \
    --hash-function sha512 \
    --key-filter attr.label=ed25519-public \
    --data-type raw \
    --data-path data.txt \
    --signature-path signature-file
{
  "error_code": 0,
  "data": {
    "message": "Signature verified successfully"
  }
}
```

## Arguments
<a name="cloudhsm_cli-crypto-verify-ed25519ph-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<DATA>***  
Base64 encoded data to be verified.  
Required: Yes (unless provided through data path)

***<DATA\$1PATH>***  
Specifies the location of the data to be verified.  
Required: Yes (unless provided through data parameter)

***<HASH\$1FUNCTION>***  
Specifies the hash function. Ed25519ph only supports SHA512.   
Valid values:  
+ sha512
Required: Yes

***<KEY\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: Yes

***<SIGNATURE>***  
Base64 encoded signature.  
Required: Yes (unless provided through signature path)

***<SIGNATURE\$1PATH>***  
Specifies the location of the signature.  
Required: Yes (unless provided through signature parameter)

***<DATA\$1TYPE>***  
 Specifies whether the value of the data parameter should be hashed as part of the verification algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed.   
Valid values:  
+ raw
+ digest
Required: Yes

## Related topics
<a name="cloudhsm_cli-crypto-verify-ed25519ph-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)
+ [Generate a signature with the HashEdDSA mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-ed25519ph.md)

# Verify a signature signed with the RSA-PKCS mechanism in CloudHSM CLI
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs"></a>

Use the **crypto verify rsa-pkcs** command in CloudHSM CLI complete the following operations:
+ Confirm a file has been signed in the HSM by a given public key.
+ Verify the signature was generated using the `RSA-PKCS` signing mechanism.
+ Compare a signed file against a source file and determines whether the two are cryptographically related based on a given rsa public key and signing mechanism.

To use the **crypto verify rsa-pkcs** command, you must first have an RSA public key in your AWS CloudHSM cluster.

**Note**  
You can generate a signature using the CloudHSM CLI with the [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) subcommands.

## User type
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-syntax"></a>

```
aws-cloudhsm > help crypto verify rsa-pkcs
Verify with the RSA-PKCS mechanism

Usage: crypto verify rsa-pkcs --key-filter [<KEY_FILTER>...] --hash-function <HASH_FUNCTION> <--data-path <DATA_PATH>|--data <DATA>> <--signature-path <SIGNATURE_PATH>|--signature <SIGNATURE>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --key-filter [<KEY_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key
      --hash-function <HASH_FUNCTION>
          [possible values: sha1, sha224, sha256, sha384, sha512]
      --data-path <DATA_PATH>
          The path to the file containing the data to be verified
      --data <DATA>
          Base64 encoded data to be verified
      --signature-path <SIGNATURE_PATH>
          The path to where the signature is located
      --signature <SIGNATURE>
          Base64 encoded signature to be verified
      --data-type <DATA_TYPE>
          The type of data passed in, either raw or digest [possible values: raw, digest]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-examples"></a>

These examples show how to use **crypto verify rsa-pkcs** to verify a signature that was generated using the RSA-PKCS signing mechanism and `SHA256` hash function. This command uses a public key in the HSM.

**Example: Verify a Base64 encoded signature with Base64 encoded data**  

```
aws-cloudhsm > crypto verify rsa-pkcs --hash-function sha256 --key-filter attr.label=rsa-public --data YWJjMTIz --signature XJ7mRyHnDRYrDWTQuuNb+5mhoXx7VTsPMjgOQW4iMN7E42eNHj2Q0oovMmBdHUEH0F4HYG8FBJOBhvGuM8J/z6y41GbowVpUT6WzjnIQs79K9i7i6oR1TYjLnIS3r/zkimuXcS8/ZxyDzru+GO9BUT9FFU/of9cvu4Oyn6a5+IXuCbKNQs19uASuFARUTZ0a0Ny1CB1MulxUpqGTmI91J6evlP7k/2khwDmJ5E8FEar5/Cvbn9t21p3Uj561ngTXrYbIZ2KHpef9jQh/cEIvFLG61sexJjQi8EdTxeDA+I3ITO0qrvvESvA9+Sj7kdG2ceIicFS8/8LwyxiIC31UHQ==
{
  "error_code": 0,
  "data": {
    "message": "Signature verified successfully"
  }
}
```

**Example: Verify a signature file with a data file**  

```
aws-cloudhsm > crypto verify rsa-pkcs --hash-function sha256 --key-filter attr.label=rsa-public --data-path data.txt --signature-path signature-file
{
  "error_code": 0,
  "data": {
    "message": "Signature verified successfully"
  }
}
```

**Example: Prove false signing relationship**  
This command verifies whether the invalid data was signed by a public key with the label `rsa-public` using the RSAPKCS signing mechanism to produce the signature located in `/home/signature`. Because the given arguments do not make up a true signing relationship, the command returns an error message.  

```
aws-cloudhsm > crypto verify rsa-pkcs --hash-function sha256 --key-filter attr.label=rsa-public --data aW52YWxpZA== --signature XJ7mRyHnDRYrDWTQuuNb+5mhoXx7VTsPMjgOQW4iMN7E42eNHj2Q0oovMmBdHUEH0F4HYG8FBJOBhvGuM8J/z6y41GbowVpUT6WzjnIQs79K9i7i6oR1TYjLnIS3r/zkimuXcS8/ZxyDzru+GO9BUT9FFU/of9cvu4Oyn6a5+IXuCbKNQs19uASuFARUTZ0a0Ny1CB1MulxUpqGTmI91J6evlP7k/2khwDmJ5E8FEar5/Cvbn9t21p3Uj561ngTXrYbIZ2KHpef9jQh/cEIvFLG61sexJjQi8EdTxeDA+I3ITO0qrvvESvA9+Sj7kdG2ceIicFS8/8LwyxiIC31UHQ==
{
  "error_code": 1,
  "data": "Signature verification failed"
}
```

## Arguments
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<DATA>***  
Base64 encoded data to be signed.  
Required: Yes (unless provided through data path)

***<DATA\$1PATH>***  
Specifies the location of the data to be signed.  
Required: Yes (unless provided through data path)

***<HASH\$1FUNCTION>***  
Specifies the hash function.   
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<KEY\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key.  
For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI.  
Required: Yes

***<SIGNATURE>***  
Base64 encoded signature.  
Required: Yes (unless provided through signature path)

***<SIGNATURE\$1PATH>***  
Specifies the location of the signature.  
Required: Yes (unless provided through signature path)

***<DATA\$1TYPE>***  
 Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed.   
For RSA-PKCS, the data must be passed in DER encoded format as specified in [RFC 8017, Section 9.2](https://www.rfc-editor.org/rfc/rfc8017#section-9.2)  
Valid values:  
+ raw
+ digest

## Related topics
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# Verify a signature signed with the RSA-PKCS-PSS mechanism in CloudHSM CLI
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-pss"></a>

Use the **crypto sign rsa-pkcs-pss** command in CloudHSM CLI to complete the following operations.
+ Confirm a file has been signed in the HSM by a given public key.
+ Verify the signature was generated using the RSA-PKCS-PSS signing mechanism.
+ Compare a signed file against a source file and determines whether the two are cryptographically related based on a given rsa public key and signing mechanism.

To use the **crypto verify rsa-pkcs-pss** command, you must first have an RSA public key in your AWS CloudHSM cluster. You can import an RSA public key using the key import pem command ADD UNWRAP LINK HERE) with the `verify` attribute set to `true`.

**Note**  
You can generate a signature using the CloudHSM CLI with the [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) subcommands.

## User type
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-pss-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-pss-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-pss-syntax"></a>

```
aws-cloudhsm > help crypto verify rsa-pkcs-pss
Verify with the RSA-PKCS-PSS mechanism

Usage: crypto verify rsa-pkcs-pss --key-filter [<KEY_FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF> --salt-length >SALT_LENGTH< <--data-path <DATA_PATH>|--data <DATA> <--signature-path <SIGNATURE_PATH>|--signature <SIGNATURE>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --key-filter [<KEY_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key
      --hash-function <HASH_FUNCTION>
          [possible values: sha1, sha224, sha256, sha384, sha512]
      --data-path <DATA_PATH>
          The path to the file containing the data to be verified
      --data <DATA>
          Base64 encoded data to be verified
      --signature-path <SIGNATURE_PATH>
          The path to where the signature is located
      --signature <SIGNATURE>
          Base64 encoded signature to be verified
      --data-type <DATA_TYPE>
          The type of data passed in, either raw or digest [possible values: raw, digest]
      --mgf <MGF>
          The mask generation function [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
      --salt-length <SALT_LENGTH>
          The salt length
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-pss-examples"></a>

These examples show how to use **crypto verify rsa-pkcs-pss** to verify a signature that was generated using the RSA-PKCS-PSS signing mechanism and `SHA256` hash function. This command uses a public key in the HSM.

**Example: Verify a Base64 encoded signature with Base64 encoded data**  

```
aws-cloudhsm > crypto verify rsa-pkcs-pss --key-filter attr.label=rsa-public --hash-function sha256 --data YWJjMTIz --salt-length 10 --mgf mgf1-sha256 --signature H/z1rYVMzNAa31K4amE5MTiwGxDdCTgQXCJXRBKVOVm7ZuyI0fGE4sT/BUN+977mQEV2TqtWpTsiF2IpwGM1VfSBRt7h/g4o6YERm1tTQLl7q+AJ7uGGK37zCsWQrAo7Vy8NzPShxekePo/ZegrB1aHWN1fE8H3IPUKqLuMDI9o1Jq6kM986ExS7YmeOIclcZkyykTWqHLQVL2C3+A2bHJZBqRcM5XoIpk8HkPypjpN+m4FNUds30GAemoOMl6asSrEJSthaZWV53OBsDOqzA8Rt8JdhXS+GZp3vNLdL1OTBELDPweXVgAu4dBX0FOvpw/gg6sNvuaDK4YOBv2fqKg==
{
  "error_code": 0,
  "data": {
    "message": "Signature verified successfully"
  }
}
```

**Example: Verify a signature file with a data file**  

```
aws-cloudhsm > crypto verify rsa-pkcs-pss --key-filter attr.label=rsa-public --hash-function sha256 --data-path data.txt --salt-length 10 --mgf mgf1-sha256 --signature signature-file
{
  "error_code": 0,
  "data": {
    "message": "Signature verified successfully"
  }
}
```

**Example: Prove false signing relationship**  
This command verifies whether the invalid data was signed by a public key with the label `rsa-public` using the RSAPKCSPSS signing mechanism to produce the signature located in `/home/signature`. Because the given arguments do not make up a true signing relationship, the command returns an error message.  

```
aws-cloudhsm > crypto verify rsa-pkcs-pss --key-filter attr.label=rsa-public --hash-function sha256 --data aW52YWxpZA== --salt-length 10 --mgf mgf1-sha256 --signature H/z1rYVMzNAa31K4amE5MTiwGxDdCTgQXCJXRBKVOVm7ZuyI0fGE4sT/BUN+977mQEV2TqtWpTsiF2IpwGM1VfSBRt7h/g4o6YERm1tTQLl7q+AJ7uGGK37zCsWQrAo7Vy8NzPShxekePo/ZegrB1aHWN1fE8H3IPUKqLuMDI9o1Jq6kM986ExS7YmeOIclcZkyykTWqHLQVL2C3+A2bHJZBqRcM5XoIpk8HkPypjpN+m4FNUds30GAemoOMl6asSrEJSthaZWV53OBsDOqzA8Rt8JdhXS+GZp3vNLdL1OTBELDPweXVgAu4dBX0FOvpw/gg6sNvuaDK4YOBv2fqKg==
{
  "error_code": 1,
  "data": "Signature verification failed"
}
```

## Arguments
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-pss-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<DATA>***  
Base64 encoded data to be signed.  
Required: Yes (unless provided through data path)

***<DATA\$1PATH>***  
Specifies the location of the data to be signed.  
Required: Yes (unless provided through data path)

***<HASH\$1FUNCTION>***  
Specifies the hash function.   
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<KEY\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key.  
For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI.  
Required: Yes

***<MFG>***  
Specifies the mask generation function.  
The mask generation function hash function must match the signing mechanism hash function.
Valid values:  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
Required: Yes

***<SIGNATURE>***  
Base64 encoded signature.  
Required: Yes (unless provided through signature path)

***<SIGNATURE\$1PATH>***  
Specifies the location of the signature.  
Required: Yes (unless provided through signature path)

***<DATA\$1TYPE>***  
 Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed.   
Valid values:  
+ raw
+ digest

## Related topics
<a name="cloudhsm_cli-crypto-verify-rsa-pkcs-pss-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# The key category in CloudHSM CLI
<a name="cloudhsm_cli-key"></a>

In the CloudHSM CLI, **key** is a parent category for a group of commands that, when combined with the parent category, create a command specific to keys. Currently, this category consists of the following commands:
+ [delete](cloudhsm_cli-key-delete.md)
+ [generate-file](cloudhsm_cli-key-generate-file.md)
+ [key generate-asymmetric-pair](cloudhsm_cli-key-generate-asymmetric-pair.md)
  + [key generate-asymmetric-pair rsa](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md)
  + [key generate-asymmetric-pair ec](cloudhsm_cli-key-generate-asymmetric-pair-ec.md)
+ [key generate-symmetric](cloudhsm_cli-key-generate-symmetric.md)
  + [key generate-symmetric aes](cloudhsm_cli-key-generate-symmetric-aes.md)
  + [key generate-symmetric generic-secret](cloudhsm_cli-key-generate-symmetric-generic-secret.md)
+ [import pem](cloudhsm_cli-key-import-pem.md)
+ [list](cloudhsm_cli-key-list.md)
+ [replicate](cloudhsm_cli-key-replicate.md)
+ [set-attribute](cloudhsm_cli-key-set-attribute.md)
+ [share](cloudhsm_cli-key-share.md)
+ [unshare](cloudhsm_cli-key-unshare.md)
+ [unwrap](cloudhsm_cli-key-unwrap.md)
+ [wrap](cloudhsm_cli-key-wrap.md)

# Delete a key with CloudHSM CLI
<a name="cloudhsm_cli-key-delete"></a>

Use the **key delete** command in CloudHSM CLI to delete a key from an AWS CloudHSM cluster. You can only delete one key at a time. Deleting one key in a key pair has no effect on the other key in the pair. 

Only the CU who created the key and consequently owns it can delete the key. Users who share the key, but do not own it, can use the key in cryptographic operations, but can not delete it.

## User type
<a name="key-delete-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-delete-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="key-delete-syntax"></a>

```
aws-cloudhsm > help key delete
Delete a key in the HSM cluster

Usage: key delete [OPTIONS] --filter [<FILTER>...]

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]     Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key for deletion
  -h, --help                     Print help
```

## Example
<a name="key-delete-examples"></a>

```
aws-cloudhsm > key delete --filter attr.label="ec-test-public-key"
{
  "error_code": 0,
  "data": {
    "message": "Key deleted successfully"
  }
}
```

## Arguments
<a name="key-delete-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key for deletion.  
For a list of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: Yes

## Related topics
<a name="key-delete-seealso"></a>
+ [List keys for a user with CloudHSM CLI](cloudhsm_cli-key-list.md)
+ [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md)
+ [Unshare a key using CloudHSM CLI](cloudhsm_cli-key-unshare.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Export an asymmetric key with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-file"></a>

Use the **key generate-file** command in CloudHSM CLI to export an asymmetric key from the hardware security module (HSM). If the target is a private key, then the reference to the private key will be exported in fake PEM format. If the target is a public key, then the public key bytes will be exported in PEM format.

The fake PEM file, which does not contain the actual private key material but instead references the private key in the HSM, can be used to establish SSL/TLS offloading from your web server to AWS CloudHSM. For more information, see [SSL/TLS offloading](ssl-offload.md).

## User type
<a name="key-generate-file-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-file-requirements"></a>

To run this command, you must be logged in as a CU.

## Syntax
<a name="key-generate-file-syntax"></a>

```
aws-cloudhsm > help key generate-file
Generate a key file from a key in the HSM cluster. This command does not export any private key data from the HSM

Usage: key generate-file --encoding <ENCODING> --path <PATH> --filter [<FILTER>...]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --encoding <ENCODING>
          Encoding format for the key file

          Possible values:
          - reference-pem: PEM formatted key reference (supports private keys)
          - pem:           PEM format (supports public keys)

      --path <PATH>
          Filepath where the key file will be written

      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key for file generation

  -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="key-generate-file-examples"></a>

This example shows how to use **key generate-file** to generate a key file in your AWS CloudHSM cluster.

**Example**  

```
aws-cloudhsm > key generate-file --encoding reference-pem --path /tmp/ec-private-key.pem --filter attr.label="ec-test-private-key"
{
  "error_code": 0,
  "data": {
    "message": "Successfully generated key file"
  }
}
```

## Arguments
<a name="key-generate-file-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key for deletion.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: No

***<ENCODING>***  
Specifies the encoding format for the key file  
Required: Yes

***<PATH>***  
Specifies the file path where the key file will be written  
Required: Yes

## Generating KSP key references (Windows)
<a name="key-generate-ksp-key-reference"></a>

**Note**  
This feature is only in SDK version 5.16.0 and later.

### Prerequisites
<a name="key-generate-ksp-key-reference-requirements"></a>
+ You can generate KSP key references only on Windows platforms.
+ You must sign in as a crypto user (CU).

### File location
<a name="key-generate-ksp-key-reference-options"></a>

By default, AWS CloudHSM stores generated files in: `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`

To specify a different location, use the `--path` parameter.

### Syntax
<a name="key-generate-ksp-key-reference-syntax"></a>

```
aws-cloudhsm > help key generate-file --encoding ksp-key-reference 
Generate a key file from a key in the HSM cluster. This command does not export any private key data from the HSM

Usage: key generate-file --encoding <ENCODING> --path <PATH> --filter [<FILTER>...]

Options:
      --encoding <ENCODING>
        Encoding format for the key file

        Possible values:
        - reference-pem:     PEM formatted key reference (supports private keys)
        - pem:               PEM format (supports public keys)
        - ksp-key-reference: KSP key reference format

      --cluster-id <CLUSTER_ID>
        Unique Id to choose which of the clusters in the config file to run the operation against. If not provided with multiple clusters configured, will error

      --path <PATH>
        Directory path where the key file will be written

      --filter [<FILTER>...]
        Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key for file generation

      --all
        Generate ksp key reference for all available key pairs in HSM

  -h, --help
        Print help (see a summary with '-h')
```

### Example – Generate a KSP key reference using an attribute filter of a private key
<a name="key-generate-ksp-key-reference-example1"></a>

The following example generates a KSP key reference for a private key with a specific label.

**Example**  

```
aws-cloudhsm > key generate-file --encoding ksp-key-reference --path  --filter attr.label="ec-test-private-key"
{
  "error_code": 0,
  "data": {
    "message": "Successfully generated key file"
  }
}
```

### Example – Generate KSP key references for all key pairs
<a name="key-generate-ksp-key-reference-example2"></a>

The following example generates KSP key references for all key pairs in your cluster.

**Example**  

```
aws-cloudhsm > key generate-file --encoding ksp-key-reference --all
{
  "error_code": 0,
  "data": {
    "message": "Successfully generated key file"
  }
}
```

## Related topics
<a name="key-generate-file-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)
+ [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md)
+ [The generate-symmetric category in CloudHSM CLI](cloudhsm_cli-key-generate-symmetric.md)

# The generate-asymmetric-pair category in CloudHSM CLI
<a name="cloudhsm_cli-key-generate-asymmetric-pair"></a>

In the CloudHSM CLI, **key generate-asymmetric-pair** is a parent category for a group of commands that, when combined with the parent category, create a command that generates asymmetric key pairs. Currently, this category consists of the following commands:
+ [key generate-asymmetric-pair ec](cloudhsm_cli-key-generate-asymmetric-pair-ec.md)
+ [key generate-asymmetric-pair rsa](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md)

# Generate an asymmetric EC key pair with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-asymmetric-pair-ec"></a>

Use the **key asymmetric-pair ec** command in CloudHSM CLI to generate an asymmetric Elliptic-curve (EC) key pair in your AWS CloudHSM cluster.

## User type
<a name="key-generate-asymmetric-pair-ec-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-asymmetric-pair-ec-requirements"></a>

To run this command, you must be logged in as a CU.

## Syntax
<a name="key-generate-asymmetric-pair-ec-syntax"></a>

```
aws-cloudhsm > help key generate-asymmetric-pair ec
Generate an Elliptic-Curve Cryptography (ECC) key pair

Usage: key generate-asymmetric-pair ec [OPTIONS] --public-label <PUBLIC_LABEL> --private-label <PRIVATE_LABEL> --curve <CURVE>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --public-label <PUBLIC_LABEL>
          Label for the public key
      --private-label <PRIVATE_LABEL>
          Label for the private key
      --session
          Creates a session key pair that exists only in the current session. The key cannot be recovered after the session ends
      --curve <CURVE>
          Elliptic curve used to generate the key pair [possible values: prime256v1, secp256r1, secp224r1, secp384r1, secp256k1, secp521r1, ed25519]
      --public-attributes [<PUBLIC_KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated EC public key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --private-attributes [<PRIVATE_KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated EC private key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --share-crypto-users [<SHARE_CRYPTO_USERS>...]
          Space separated list of Crypto User usernames to share the EC private key with
      --manage-private-key-quorum-value <MANAGE_PRIVATE_KEY_QUORUM_VALUE>
          The quorum value for key management operations for the private key
      --use-private-key-quorum-value <USE_PRIVATE_KEY_QUORUM_VALUE>
          The quorum value for key usage operations for the private key
  -h, --help
          Print help
```

## Examples
<a name="key-generate-asymmetric-pair-ec-examples"></a>

These examples show how to use the **key generate-asymmetric-pair ec** command to create an EC key pair.

**Example: Create an EC key pair**  

```
aws-cloudhsm > key generate-asymmetric-pair ec \
    --curve secp224r1 \
    --public-label ec-public-key-example \
    --private-label ec-private-key-example
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x000000000012000b",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "ec",
        "label": "ec-public-key-example",
        "id": "",
        "check-value": "0xd7c1a7",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 57,
        "ec-point": "0x047096513df542250a6b228fd9cb67fd0c903abc93488467681974d6f371083fce1d79da8ad1e9ede745fb9f38ac8622a1b3ebe9270556000c",
        "curve": "secp224r1"
      }
    },
"private_key": {
      "key-reference": "0x000000000012000c",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "ec",
        "label": "ec-private-key-example",
        "id": "",
        "check-value": "0xd7c1a7",
        "class": "private-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 122,
        "ec-point": "0x047096513df542250a6b228fd9cb67fd0c903abc93488467681974d6f371083fce1d79da8ad1e9ede745fb9f38ac8622a1b3ebe9270556000c",
        "curve": "secp224r1"
      }
    }
  }
}
```

**Example: Create an EC key pair with optional attributes**  

```
aws-cloudhsm > key generate-asymmetric-pair ec \
    --curve secp224r1 \
    --public-label ec-public-key-example \
    --private-label ec-private-key-example \
    --public-attributes encrypt=true \
    --private-attributes decrypt=true
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x00000000002806eb",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "ec",
        "label": "ec-public-key-example",
        "id": "",
        "check-value": "0xedef86",
        "class": "public-key",
        "encrypt": true,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 57,
        "ec-point": "0x0487af31882189ec29eddf17a48e8b9cebb075b7b5afc5522fe9c83a029a450cc68592889a1ebf45f32240da5140d58729ffd7b2d44262ddb8",
        "curve": "secp224r1"
      }
    },
    "private_key": {
      "key-reference": "0x0000000000280c82",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "ec",
        "label": "ec-private-key-example",
        "id": "",
        "check-value": "0xedef86",
        "class": "private-key",
        "encrypt": false,
        "decrypt": true,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 122,
        "ec-point": "0x0487af31882189ec29eddf17a48e8b9cebb075b7b5afc5522fe9c83a029a450cc68592889a1ebf45f32240da5140d58729ffd7b2d44262ddb8",
        "curve": "secp224r1"
      }
    }
  }
}
```

**Example: Create an EC key pair with quorum values**  
When generating a key with quorum controls, the key must be associated with a minimum number of users equal to the largest key quorum value. Associated users include the key owner and Crypto Users with whom the key is shared with. To determine the number of minimum users to share the key with, get the largest quorum value between the key usage quorum value and the key management quorum value and subtract 1 to account for the key owner, who is by default associated with the key. To share the key with more users, use the **[Share a key using CloudHSM CLI](cloudhsm_cli-key-share.md)** command.  

```
aws-cloudhsm > key generate-asymmetric-pair ec \
    --curve secp224r1 \
    --public-label ec-public-key-example \
    --private-label ec-private-key-example \
    --public-attributes verify=true \
    --private-attributes sign=true
    --share-crypto-users cu2 cu3 cu4 \
    --manage-private-key-quorum-value 4 \
    --use-private-key-quorum-value 2
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x00000000002806eb",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "ec",
        "label": "ec-public-key-example",
        "id": "",
        "check-value": "0xedef86",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 57,
        "ec-point": "0x0487af31882189ec29eddf17a48e8b9cebb075b7b5afc5522fe9c83a029a450cc68592889a1ebf45f32240da5140d58729ffd7b2d44262ddb8",
        "curve": "secp224r1"
      }
    },
    "private_key": {
      "key-reference": "0x0000000000280c82",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [
          {
            "username": "cu2",
            "key-coverage": "full"
          },
          {
            "username": "cu3",
            "key-coverage": "full"
          },
          {
            "username": "cu4",
            "key-coverage": "full"
          },
        ],
        "key-quorum-values": {
          "manage-key-quorum-value": 4,
          "use-key-quorum-value": 2
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "ec",
        "label": "ec-private-key-example",
        "id": "",
        "check-value": "0xedef86",
        "class": "private-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 122,
        "ec-point": "0x0487af31882189ec29eddf17a48e8b9cebb075b7b5afc5522fe9c83a029a450cc68592889a1ebf45f32240da5140d58729ffd7b2d44262ddb8",
        "curve": "secp224r1"
      }
    }
  }
}
```

## Arguments
<a name="key-generate-asymmetric-pair-ec-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<CURVE>***  
Specifies the identifier for the elliptic curve.  
+ prime256v1
+ secp256r1
+ secp224r1
+ secp384r1
+ secp256k1
+ secp521r1
+ ed25519 (only supported on hsm2m.medium instances in non-FIPS mode)
Required: Yes

***<PUBLIC\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated EC public key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `verify=true`)  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<PUBLIC\$1LABEL>***  
Specifies a user defined label for the public-key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<PRIVATE\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated EC private key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`)  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<PRIVATE\$1LABEL>***  
Specifies a user defined label for the private-key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<SESSION>***  
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.  
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.  
By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.  
Required: No

***<SHARE\$1CRYPTO\$1USERS>***  
Specifies a space separated list of Crypto User usernames to share the EC private key with  
Required: No

***<MANAGE\$1PRIVATE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for the private key's key management operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

***<USE\$1PRIVATE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for private key's key usage operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

## Related topics
<a name="key-generate-asymmetric-pair-ec-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Generate an asymmetric RSA key pair with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-asymmetric-pair-rsa"></a>

Use the **key generate-asymmetric-pair rsa** command in CloudHSM CLI to generate an asymmetric RSA key pair in your AWS CloudHSM cluster.

## User type
<a name="key-generate-asymmetric-pair-rsa-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-asymmetric-pair-rsa-requirements"></a>

To run this command, you must be logged in as a CU.

## Syntax
<a name="key-generate-asymmetric-pair-rsa-syntax"></a>

```
aws-cloudhsm > help key generate-asymmetric-pair rsa
Generate an RSA key pair

Usage: key generate-asymmetric-pair rsa [OPTIONS] --public-label <PUBLIC_LABEL> --private-label <PRIVATE_LABEL> --modulus-size-bits <MODULUS_SIZE_BITS> --public-exponent <PUBLIC_EXPONENT>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --public-label <PUBLIC_LABEL>
          Label for the public key
      --private-label <PRIVATE_LABEL>
          Label for the private key
      --session
          Creates a session key pair that exists only in the current session. The key cannot be recovered after the session ends
      --modulus-size-bits <MODULUS_SIZE_BITS>
          Modulus size in bits used to generate the RSA key pair
      --public-exponent <PUBLIC_EXPONENT>
          Public exponent used to generate the RSA key pair
      --public-attributes [<PUBLIC_KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated RSA public key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --private-attributes [<PRIVATE_KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated RSA private key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --share-crypto-users [<SHARE_CRYPTO_USERS>...]
          Space separated list of Crypto User usernames to share the RSA key with
      --manage-private-key-quorum-value <MANAGE_PRIVATE_KEY_QUORUM_VALUE>
          The quorum value for key management operations for the private key
      --use-private-key-quorum-value <USE_PRIVATE_KEY_QUORUM_VALUE>
          The quorum value for key usage operations for the private key
  -h, --help
          Print help
```

## Examples
<a name="key-generate-asymmetric-pair-rsa-examples"></a>

These examples show how to use `key generate-asymmetric-pair rsa` to create a RSA key pair.

**Example: Create an RSA key pair**  

```
aws-cloudhsm > key generate-asymmetric-pair rsa \
--public-exponent 65537 \
--modulus-size-bits 2048 \
--public-label rsa-public-key-example \
--private-label rsa-private-key-example
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x0000000000160010",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "rsa-public-key-example",
        "id": "",
        "check-value": "0x498e1f",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0xdfca0669dc8288ed3bad99509bd21c7e6192661407021b3f4cdf4a593d939dd24f4d641af8e4e73b04c847731c6dbdff3385818e08dd6efcbedd6e5b130344968c
e89a065e7d1a46ced96b46b909db2ab6be871ee700fd0a448b6e975bb64cae77c49008749212463e37a577baa57ce3e574cb057e9db131e119badf50c938f26e8a5975c61a8ba7ffe7a1115a
bcebb7d20bd6df1948ae336ae23b52d73b7f3b6acc2543edb6358e08d326d280ce489571f4d34e316a2ea1904d513ca12fa04075fc09ad005c81b7345d7804ff24c45117f0a1020dca7794df037a10aadec8653473b2088711f7b7d8b58431654e14e31af0e00511da641058fb7475ffdbe60f",
        "modulus-size-bits": 2048
      }
    },
"private_key": {
      "key-reference": "0x0000000000160011",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "rsa-private-key-example",
        "id": "",
        "check-value": "0x498e1f",
        "class": "private-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 1217,
        "public-exponent": "0x010001",
        "modulus": "0xdfca0669dc8288ed3bad99509bd21c7e6192661407021b3f4cdf4a593d939dd24f4d641af8e4e73b04c847731c6dbdff3385818e08dd6efcbedd6e5b130344968ce89a065e7d1a46ced96b46b909db2ab6be871ee700fd0a448b6e975bb64cae77c49008749212463e37a577baa57ce3e574cb057e9db131e119badf50c938f26e8a5975c61a8ba7ffe7a1115abcebb7d20bd6df1948ae336ae23b52d73b7f3b6acc2543edb6358e08d326d280ce489571f4d34e316a2ea1904d513ca12fa04075fc09ad005c81b7345d7804ff24c45117f0a1020dca7794df037a10aadec8653473b2088711f7b7d8b58431654e14e31af0e00511da641058fb7475ffdbe60f",
        "modulus-size-bits": 2048
      }
    }
  }
}
```

**Example: Create an RSA key pair with optional attributes**  

```
aws-cloudhsm > key generate-asymmetric-pair rsa \
--public-exponent 65537 \
--modulus-size-bits 2048 \
--public-label rsa-public-key-example \
--private-label rsa-private-key-example \
--public-attributes encrypt=true \
--private-attributes decrypt=true
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x0000000000280cc8",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "rsa-public-key-example",
        "id": "",
        "check-value": "0x01fe6e",
        "class": "public-key",
        "encrypt": true,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0xb1d27e857a876f4e9fd5de748a763c539b359f937eb4b4260e30d1435485a732c878cdad9c72538e2215351b1d41358c9bf80b599c
73a80fdb457aa7b20cd61e486c326e2cfd5e124a7f6a996437437812b542e3caf85928aa866f0298580f7967ee6aa01440297d7308fdd9b76b70d1b67f12634d
f6e6296d6c116d5744c6d60d14d3bf3cb978fe6b75ac67b7089bafd50d8687213b31abc7dc1bad422780d29c851d5102b56f932551eaf52a9591fd8c43d81ecc
133022653225bd129f8491101725e9ea33e1ded83fb57af35f847e532eb30cd7e726f23910d2671c6364092e834697ec3cef72cc23615a1ba7c5e100156ae0ac
ac3160f0ca9725d38318b7",
        "modulus-size-bits": 2048
      }
    },
    "private_key": {
      "key-reference": "0x0000000000280cc7",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "rsa-private-key-example",
        "id": "",
        "check-value": "0x01fe6e",
        "class": "private-key",
        "encrypt": false,
        "decrypt": true,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 1217,
        "public-exponent": "0x010001",
        "modulus": "0xb1d27e857a876f4e9fd5de748a763c539b359f937eb4b4260e30d1435485a732c878cdad9c72538e2215351b1d41358c9bf80b599c73a80fdb457aa7b20cd61e486c326e2cfd5e124a7f6a996437437812b542e3caf85928aa866f0298580f7967ee6aa01440297d7308fdd9b76b70d1b67f12634df6e6296d6c116d5744c6d60d14d3bf3cb978fe6b75ac67b7089bafd50d8687213b31abc7dc1bad422780d29c851d5102b56f932551eaf52a9591fd8c43d81ecc133022653225bd129f8491101725e9ea33e1ded83fb57af35f847e532eb30cd7e726f23910d2671c6364092e834697ec3cef72cc23615a1ba7c5e100156ae0acac3160f0ca9725d38318b7",
        "modulus-size-bits": 2048
      }
    }
  }
}
```

**Example: Create an RSA key pair with quorum values**  
When generating a key with quorum controls, the key must be associated with a minimum number of users equal to the largest key quorum value. Associated users include the key owner and Crypto Users with whom the key is shared with. To determine the number of minimum users to share the key with, get the largest quorum value between the key usage quorum value and the key management quorum value and subtract 1 to account for the key owner, who is by default associated with the key. To share the key with more users, use the **[Share a key using CloudHSM CLI](cloudhsm_cli-key-share.md)** command.  

```
aws-cloudhsm > key generate-asymmetric-pair rsa \
--public-exponent 65537 \
--modulus-size-bits 2048 \
--public-label rsa-public-key-example \
--private-label rsa-private-key-example \
--public-attributes verify=true \
--private-attributes sign=true
--share-crypto-users cu2 cu3 cu4 \
--manage-private-key-quorum-value 4 \
--use-private-key-quorum-value 2
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x0000000000280cc8",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "rsa-public-key-example",
        "id": "",
        "check-value": "0x01fe6e",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0xb1d27e857a876f4e9fd5de748a763c539b359f937eb4b4260e30d1435485a732c878cdad9c72538e2215351b1d41358c9bf80b599c
73a80fdb457aa7b20cd61e486c326e2cfd5e124a7f6a996437437812b542e3caf85928aa866f0298580f7967ee6aa01440297d7308fdd9b76b70d1b67f12634d
f6e6296d6c116d5744c6d60d14d3bf3cb978fe6b75ac67b7089bafd50d8687213b31abc7dc1bad422780d29c851d5102b56f932551eaf52a9591fd8c43d81ecc
133022653225bd129f8491101725e9ea33e1ded83fb57af35f847e532eb30cd7e726f23910d2671c6364092e834697ec3cef72cc23615a1ba7c5e100156ae0ac
ac3160f0ca9725d38318b7",
        "modulus-size-bits": 2048
      }
    },
    "private_key": {
      "key-reference": "0x0000000000280cc7",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [
          {
            "username": "cu2",
            "key-coverage": "full"
          },
          {
            "username": "cu3",
            "key-coverage": "full"
          },
          {
            "username": "cu4",
            "key-coverage": "full"
          },
        ],
        "key-quorum-values": {
          "manage-key-quorum-value": 4,
          "use-key-quorum-value": 2
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "rsa-private-key-example",
        "id": "",
        "check-value": "0x01fe6e",
        "class": "private-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 1217,
        "public-exponent": "0x010001",
        "modulus": "0xb1d27e857a876f4e9fd5de748a763c539b359f937eb4b4260e30d1435485a732c878cdad9c72538e2215351b1d41358c9bf80b599c73a80fdb457aa7b20cd61e486c326e2cfd5e124a7f6a996437437812b542e3caf85928aa866f0298580f7967ee6aa01440297d7308fdd9b76b70d1b67f12634df6e6296d6c116d5744c6d60d14d3bf3cb978fe6b75ac67b7089bafd50d8687213b31abc7dc1bad422780d29c851d5102b56f932551eaf52a9591fd8c43d81ecc133022653225bd129f8491101725e9ea33e1ded83fb57af35f847e532eb30cd7e726f23910d2671c6364092e834697ec3cef72cc23615a1ba7c5e100156ae0acac3160f0ca9725d38318b7",
        "modulus-size-bits": 2048
      }
    }
  }
}
```

## Arguments
<a name="key-generate-asymmetric-pair-rsa-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<MODULUS\$1SIZE\$1BITS>***  
 Specifies the length of the modulus in bits. The minimum value is 2048.   
Required: Yes

***<PRIVATE\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated RSA private key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`)  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<PRIVATE\$1LABEL>***  
 Specifies a user defined label for the private-key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<PUBLIC\$1EXPONENT>***  
Specifies the public exponent. The value must be an odd number greater than or equal to 65537.  
Required: Yes

***<PUBLIC\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated RSA public key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `verify=true`)  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<PUBLIC\$1LABEL>***  
 Specifies a user defined label for the public-key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<SESSION>***  
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.  
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.  
By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.  
Required: No

***<SHARE\$1CRYPTO\$1USERS>***  
Specifies a space separated list of Crypto User usernames to share the RSA private key with  
Required: No

***<MANAGE\$1PRIVATE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for the private key's key management operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

***<USE\$1PRIVATE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for private key's key usage operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

## Related topics
<a name="key-generate-asymmetric-pair-rsa-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# The generate-symmetric category in CloudHSM CLI
<a name="cloudhsm_cli-key-generate-symmetric"></a>

In the CloudHSM CLI, **key generate-symmetric** is a parent category for a group of commands that, when combined with the parent category, create a command that generates symmetric keys. Currently, this category consists of the following commands:
+ [key generate-symmetric aes](cloudhsm_cli-key-generate-symmetric-aes.md)
+ [key generate-symmetric generic-secret](cloudhsm_cli-key-generate-symmetric-generic-secret.md)

# Generate a symmetric AES key with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-symmetric-aes"></a>

Use the **key generate-symmetric aes** command in CloudHSM CLI to generate a symmetric AES key in your AWS CloudHSM cluster.

## User type
<a name="key-generate-symmetric-aes-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-symmetric-aes-requirements"></a>

To run this command, you must be logged in as a CU.

## Syntax
<a name="key-generate-symmetric-aes-syntax"></a>

```
aws-cloudhsm > help key generate-symmetric aes
Generate an AES key

Usage: key generate-symmetric aes [OPTIONS] --label <LABEL> --key-length-bytes <KEY_LENGTH_BYTES>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --label <LABEL>
          Label for the key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --key-length-bytes <KEY_LENGTH_BYTES>
          Key length in bytes
      --attributes [<KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated AES key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --share-crypto-users [<SHARE_CRYPTO_USERS>...]
          Space separated list of Crypto User usernames to share the AES key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE>
          The quorum value for key management operations
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE>
          The quorum value for key usage operations
  -h, --help
          Print help
```

## Examples
<a name="key-generate-symmetric-aes-examples"></a>

These examples show how to use the **key generate-symmetric aes** command to create an AES key.

**Example: Create an AES key**  

```
aws-cloudhsm > key generate-symmetric aes \
--label example-aes \
--key-length-bytes 24
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e06bf",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "example-aes",
        "id": "",
        "check-value": "0x9b94bd",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 24
      }
    }
  }
}
```

**Example: Create an AES key with optional attributes**  

```
aws-cloudhsm > key generate-symmetric aes \
--label example-aes \
--key-length-bytes 24 \
--attributes decrypt=true encrypt=true
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e06bf",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "example-aes",
        "id": "",
        "check-value": "0x9b94bd",
        "class": "secret-key",
        "encrypt": true,
        "decrypt": true,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 24
      }
    }
  }
}
```

**Example: Create an AES key with quorum values**  
When generating a key with quorum controls, the key must be associated with a minimum number of users equal to the largest key quorum value. Associated users include the key owner and Crypto Users with whom the key is shared with. To determine the number of minimum users to share the key with, get the largest quorum value between the key usage quorum value and the key management quorum value and subtract 1 to account for the key owner, who is by default associated with the key. To share the key with more users, use the **[Share a key using CloudHSM CLI](cloudhsm_cli-key-share.md)** command.  

```
aws-cloudhsm > key generate-symmetric aes \
--label example-aes \
--key-length-bytes 24 \
--attributes decrypt=true encrypt=true
--share-crypto-users cu2 cu3 cu4 \
--manage-key-quorum-value 4 \
--use-key-quorum-value 2
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e06bf",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [
          {
            "username": "cu2",
            "key-coverage": "full"
          },
          {
            "username": "cu3",
            "key-coverage": "full"
          },
          {
            "username": "cu4",
            "key-coverage": "full"
          },
        ],
        "key-quorum-values": {
          "manage-key-quorum-value": 4,
          "use-key-quorum-value": 2
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "example-aes",
        "id": "",
        "check-value": "0x9b94bd",
        "class": "secret-key",
        "encrypt": true,
        "decrypt": true,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 24
      }
    }
  }
}
```

## Arguments
<a name="key-generate-symmetric-aes-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated AES key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`).  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<KEY-LENGTH-BYTES>***  
Specifies the key length in bytes.  

Valid values:
+ 16, 24, and 32
Required: Yes

***<LABEL>***  
Specifies a user defined label for the AES key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<SESSION>***  
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.  
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.  
By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.  
Required: No

***<SHARE\$1CRYPTO\$1USERS>***  
Specifies a space separated list of Crypto User usernames to share the AES key with  
Required: No

***<MANAGE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for key management operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

***<USE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for key usage operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

## Related topics
<a name="key-generate-symmetric-aes-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Generate a symmetric Generic Secret key with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-symmetric-generic-secret"></a>

Use the **key generate-symmetric generic-secret** command in CloudHSM CLI to generate a symmetric Generic Secret key in your AWS CloudHSM cluster.

## User type
<a name="key-generate-symmetric-generic-secret-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-symmetric-generic-secret-requirements"></a>

To run this command, you must be logged in as a CU.

## Syntax
<a name="key-generate-symmetric-generic-secret-syntax"></a>

```
aws-cloudhsm > key help generate-symmetric generic-secret
Generate a generic secret key

Usage: key generate-symmetric generic-secret [OPTIONS] --label <LABEL> --key-length-bytes <KEY_LENGTH_BYTES>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --label <LABEL>
          Label for the key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --key-length-bytes <KEY_LENGTH_BYTES>
          Key length in bytes
      --attributes [<KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated generic secret key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --share-crypto-users [<SHARE_CRYPTO_USERS>...]
          Space separated list of Crypto User usernames to share the generic secret key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE>
          The quorum value for key management operations
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE>
          The quorum value for key usage operations
  -h, --help
          Print help
```

## Examples
<a name="key-generate-symmetric-generic-secret-examples"></a>

These examples show how to use the **key generate-symmetric generic-secret** command to create a generic secret key.

**Example: Create a generic secret key**  

```
aws-cloudhsm > key generate-symmetric generic-secret \
--label example-generic-secret \
--key-length-bytes 256
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e08fd",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "generic-secret",
        "label": "example-generic-secret",
        "id": "",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 256
      }
    }
  }
}
```

**Example: Create a generic secret key with optional attributes**  

```
aws-cloudhsm > key generate-symmetric generic-secret \
--label example-generic-secret \
--key-length-bytes 256 \
--attributes encrypt=true
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e08fd",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "generic-secret",
        "label": "example-generic-secret",
        "id": "",
        "class": "secret-key",
        "encrypt": true,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 256
      }
    }
  }
}
```

**Example: Create a generic secret key with quorum values**  
When generating a key with quorum controls, the key must be associated with a minimum number of users equal to the largest key quorum value. Associated users include the key owner and Crypto Users with whom the key is shared with. To determine the number of minimum users to share the key with, get the largest quorum value between the key usage quorum value and the key management quorum value and subtract 1 to account for the key owner, who is by default associated with the key. To share the key with more users, use the **[Share a key using CloudHSM CLI](cloudhsm_cli-key-share.md)** command.  

```
aws-cloudhsm > key generate-symmetric generic-secret \
--label example-generic-secret \
--key-length-bytes 256 \
--attributes encrypt=true
--share-crypto-users cu2 cu3 cu4 \
--manage-key-quorum-value 4 \
--use-key-quorum-value 2
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e08fd",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [
          {
            "username": "cu2",
            "key-coverage": "full"
          },
          {
            "username": "cu3",
            "key-coverage": "full"
          },
          {
            "username": "cu4",
            "key-coverage": "full"
          },
        ],
        "key-quorum-values": {
          "manage-key-quorum-value": 4,
          "use-key-quorum-value": 2
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "generic-secret",
        "label": "example-generic-secret",
        "id": "",
        "class": "secret-key",
        "encrypt": true,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 256
      }
    }
  }
}
```

## Arguments
<a name="key-generate-symmetric-generic-secret-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated AES key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`).  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<KEY-LENGTH-BYTES>***  
Specifies the key length in bytes.  

Valid values:
+ 1 to 800
Required: Yes

***<LABEL>***  
Specifies a user defined label for the generic secret key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<SESSION>***  
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.  
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.  
By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.  
Required: No

***<SHARE\$1CRYPTO\$1USERS>***  
Space separated list of Crypto User usernames to share the generic secret key with  
Required: No

***<MANAGE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for key management operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

***<USE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for key usage operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

## Related topics
<a name="key-generate-symmetric-generic-secret-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Import a PEM format key with CloudHSM CLI
<a name="cloudhsm_cli-key-import-pem"></a>

Use the **key import pem** command in AWS CloudHSM to import a PEM format key into a hardware security module (HSM). You can use it to import public keys that were generated outside of the HSM.

**Note**  
Use the [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md) command to create a standard PEM file from a public key or to create a reference PEM file from a private key.

## User type
<a name="cloudhsm_cli-key-import-pem-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-import-pem-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-import-pem-syntax"></a>

```
aws-cloudhsm > help key import pem
Import key from a PEM file

Usage: key import pem [OPTIONS] --path <PATH> --label <LABEL> --key-type-class <KEY_TYPE_CLASS>
Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --path <PATH>
          Path where the key is located in PEM format
      --label <LABEL>
          Label for the imported key
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of the imported key [possible values: ec-public, rsa-public]
      --attributes [<IMPORT_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the imported key
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-import-pem-examples"></a>

These example shows how to use the **key import pem** command to import an RSA public key from a file in PEM format.

**Example: Import an RSA public key**  

```
aws-cloudhsm > key import pem --path /home/example --label example-imported-key --key-type-class rsa-public
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001e08e3",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",                                   
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "example-imported-key",
        "id": "0x",
        "check-value": "0x99fe93",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0x8e9c172c37aa22ed1ce25f7c3a7c936dadc532201400128b044ebb4b96│··3e4930ab910df5a2896eaeb8853cfea0e341227654a8337a7864cc8a87d136f006cfba9e68d0b329│··746c1ad60941668b18699fc8169ff1ec363d0d18292845b2454d6a0b8c5d111b79c047619d460cdf│··be59debbacb66b7abeaf3f3d35dd2b9cfa6b6b7b1258b6866cb4085ac749e9d8552b3a4509e1b86c│··828cc794e22767b4f6b5bc6ff5c96f4b7e60eab305d669cfa2197e85379cb35c659bb58fcd246d48│··d9f6a7f36063b42da025459275aa8e3abedad775387086bd6c198ded868403f4b87ffda5a2d455ac│··aa6cbd00003c31d8d2f51d10cd272b31cf0c4037791f48ad51fb35",
        "modulus-size-bits": 2048
      }
    },
    "message": "Successfully imported key"
  }
}
```

**Example: Import an RSA public key with optional attributes**  

```
aws-cloudhsm > key import pem --path /home/example --label example-imported-key-with-attributes --key-type-class rsa-public --attributes verify=true
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001e08e3",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",                                      
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "example-imported-key-with-attributes",
        "id": "0x",
        "check-value": "0x99fe93",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0x8e9c172c37aa22ed1ce25f7c3a7c936dadc532201400128b044ebb4b96│··3e4930ab910df5a2896eaeb8853cfea0e341227654a8337a7864cc8a87d136f006cfba9e68d0b329│··746c1ad60941668b18699fc8169ff1ec363d0d18292845b2454d6a0b8c5d111b79c047619d460cdf│··be59debbacb66b7abeaf3f3d35dd2b9cfa6b6b7b1258b6866cb4085ac749e9d8552b3a4509e1b86c│··828cc794e22767b4f6b5bc6ff5c96f4b7e60eab305d669cfa2197e85379cb35c659bb58fcd246d48│··d9f6a7f36063b42da025459275aa8e3abedad775387086bd6c198ded868403f4b87ffda5a2d455ac│··aa6cbd00003c31d8d2f51d10cd272b31cf0c4037791f48ad51fb35",
        "modulus-size-bits": 2048
      }
    },
    "message": "Successfully imported key"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-import-pem-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PATH>***  
Specifies the file path where the key file is located.  
Required: Yes

***<LABEL>***  
Specifies a user defined label for the imported key. The maximum size allowable for `label` is 126 characters.  
Required: Yes

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key.  
Possible values:  
+ ec-public
+ rsa-public
Required: Yes

***<IMPORT\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the imported key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`). For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

## Related topics
<a name="cloudhsm_cli-key-import-pem-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# List keys for a user with CloudHSM CLI
<a name="cloudhsm_cli-key-list"></a>

Use the **key list** command in CloudHSM CLI to find all keys for the current user present in your AWS CloudHSM cluster. The output includes keys that the user owns and shares, as well as all public keys in the CloudHSM cluster.

## User type
<a name="chsm-cli-key-list-user-type"></a>

The following types of users can run this command.
+ Admins (COs)
+ Crypto users (CUs)

## Syntax
<a name="chsm-cli-key-list-syntax"></a>

```
aws-cloudhsm > help key list
List the keys the current user owns, shares, and all public keys in the HSM cluster

Usage: key list [OPTIONS]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select matching key(s) to list
      --max-items <MAX_ITEMS>
          The total number of items to return in the command's output. If the total number of items available is more than the value specified, a next-token is provided in the command's output. To resume pagination, provide the next-token value in the starting-token argument of a subsequent command [default: 10]
      --starting-token <STARTING_TOKEN>
          A token to specify where to start paginating. This is the next-token from a previously truncated response
  -v, --verbose
          If included, prints all attributes and key information for each matched key. By default each matched key only displays its key-reference and label attribute. This flag when used by Admins has no effect
  -h, --help
          Print help
```

## Examples
<a name="chsm-cli-key-list-examples"></a>

The following examples show the different ways you run the **key list** command. The following examples show the outputs as a crypto user.

**Example: Find all keys – default**  
This command lists the keys of the logged in user present in the AWS CloudHSM cluster.  
By default, only 10 keys of the currently logged in user are displayed, and only the `key-reference` and `label` are displayed as output. Use the appropriate pagination options to display more or less keys as output.

```
aws-cloudhsm > key list
{
  "error_code": 0,
  "data": {
    "matched_keys": [
      {
        "key-reference": "0x00000000000003d5",
        "attributes": {
          "label": "test_label_1"
        }
      },
      {
        "key-reference": "0x0000000000000626",
        "attributes": {
          "label": "test_label_2"
        }
      },.
      ...8 keys later...
    ],
    "total_key_count": 56,
    "returned_key_count": 10,
    "next_token": "10"
  }
}
```

**Example: Find all keys – verbose**  
The output includes keys that the user owns and shares, as well as all public keys in the HSMs.  
Note: By default, only 10 keys of the currently logged in user are displayed. Use the appropriate pagination options to display more or less keys as output.

```
aws-cloudhsm > key list --verbose
{
  "error_code": 0,
  "data": {
    "matched_keys": [
      {
        "key-reference": "0x000000000012000c",
        "key-info": {
          "key-owners": [
            {
              "username": "cu1",
              "key-coverage": "full"
            }
          ],
          "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
          "cluster-coverage": "full"
        },
        "attributes": {
          "key-type": "ec",
          "label": "ec-test-private-key",
          "id": "",
          "check-value": "0x2a737d",
          "class": "private-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": true,
          "sign": false,
          "trusted": false,
          "unwrap": false,
          "verify": false,
          "wrap": false,
          "wrap-with-trusted": false,
          "key-length-bytes": 122,
          "ec-point": "0x0442d53274a6c0ec1a23c165dcb9ccdd72c64e98ae1a9594bb5284e752c746280667e11f1e983493c1c605e0a8071ede47ca280f94c6b2aa33",
          "curve": "secp224r1"
        }
      },
      {
        "key-reference": "0x000000000012000d",
        "key-info": {
          "key-owners": [
            {
              "username": "cu1",
              "key-coverage": "full"
            }
          ],
          "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
          "cluster-coverage": "full"
        },
        "attributes": {
          "key-type": "ec",
          "label": "ec-test-public-key",
          "id": "",
          "check-value": "0x2a737d",
          "class": "public-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": false,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": false,
          "sign": false,
          "trusted": false,
          "unwrap": false,
          "verify": false,
          "wrap": false,
          "wrap-with-trusted": false,
          "key-length-bytes": 57,
          "ec-point": "0x0442d53274a6c0ec1a23c165dcb9ccdd72c64e98ae1a9594bb5284e752c746280667e11f1e983493c1c605e0a8071ede47ca280f94c6b2aa33",
          "curve": "secp224r1"
        }
      }
    ],
      ...8 keys later...
    "total_key_count": 1580,
    "returned_key_count": 10
  }
}
```

**Example: Paginated return**  
The following example displays a paginated subset of the keys which shows only two keys. The example then provides a subsequent call to display the next two keys.  

```
aws-cloudhsm > key list --verbose --max-items 2
{
  "error_code": 0,
  "data": {
    "matched_keys": [
      {
        "key-reference": "0x0000000000000030",
        "key-info": {
          "key-owners": [
            {
              "username": "cu1",
              "key-coverage": "full"
            }
          ],
          "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
          "cluster-coverage": "full"
        },
        "attributes": {
          "key-type": "aes",
          "label": "98a6688d1d964ed7b45b9cec5c4b1909",
          "id": "",
          "check-value": "0xb28a46",
          "class": "secret-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": true,
          "sign": true,
          "trusted": false,
          "unwrap": false,
          "verify": true,
          "wrap": false,
          "wrap-with-trusted": false,
          "key-length-bytes": 32
        }
      },
      {
        "key-reference": "0x0000000000000042",
        "key-info": {
          "key-owners": [
            {
              "username": "cu1",
              "key-coverage": "full"
            }
          ],
          "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
          "cluster-coverage": "full"
        },
        "attributes": {
          "key-type": "aes",
          "label": "4ad6cdcbc02044e09fa954143efde233",
          "id": "",
          "check-value": "0xc98104",
          "class": "secret-key",
          "encrypt": true,
          "decrypt": true,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": true,
          "sign": true,
          "trusted": false,
          "unwrap": true,
          "verify": true,
          "wrap": true,
          "wrap-with-trusted": false,
          "key-length-bytes": 16
        }
      }
    ],
    "total_key_count": 1580,
    "returned_key_count": 2,
    "next_token": "2"
  }
}
```
To display the next 2 keys, a subsequent call can be made:  

```
aws-cloudhsm > key list --verbose --max-items 2 --starting-token 2
{
  "error_code": 0,
  "data": {
    "matched_keys": [
      {
        "key-reference": "0x0000000000000081",
        "key-info": {
          "key-owners": [
            {
              "username": "cu1",
              "key-coverage": "full"
            }
          ],
          "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
          "cluster-coverage": "full"
        },
        "attributes": {
          "key-type": "aes",
          "label": "6793b8439d044046982e5b895791e47f",
          "id": "",
          "check-value": "0x3f986f",
          "class": "secret-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": true,
          "sign": true,
          "trusted": false,
          "unwrap": false,
          "verify": true,
          "wrap": false,
          "wrap-with-trusted": false,
          "key-length-bytes": 32
        }
      },
      {
        "key-reference": "0x0000000000000089",
        "key-info": {
          "key-owners": [
            {
              "username": "cu1",
              "key-coverage": "full"
            }
          ],
          "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
          "cluster-coverage": "full"
        },
        "attributes": {
          "key-type": "aes",
          "label": "56b30fa05c6741faab8f606d3b7fe105",
          "id": "",
          "check-value": "0xe9201a",
          "class": "secret-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": true,
          "sign": true,
          "trusted": false,
          "unwrap": false,
          "verify": true,
          "wrap": false,
          "wrap-with-trusted": false,
          "key-length-bytes": 32
        }
      }
    ],
    "total_key_count": 1580,
    "returned_key_count": 2,
    "next_token": "4"
  }
}
```
For more examples that demonstrate how the key filtration mechanism works in the CloudHSM CLI, see [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md).

## Arguments
<a name="key-list-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select matching key(s) to list.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: No

***<MAX\$1ITEMS>***  
The total number of items to return in the command's output. If the total number of items available is more than the value specified, a next-token is provided in the command's output. To resume pagination, provide the next-token value in the starting-token argument of a subsequent command.  
Required: No

***<STARTING\$1TOKEN>***  
A token to specify where to start paginating. This is the next-token from a previously truncated response.  
Required: No

***<VERBOSE>***  
If included, prints all attributes and key information for each matched key. By default each matched key only displays its key-reference and label attribute. This flag when used by Admins has no effect.  
Required: No

## Related topics
<a name="chsm-key-list-seealso"></a>
+ [Delete a key with CloudHSM CLI](cloudhsm_cli-key-delete.md)
+ [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md)
+ [Unshare a key using CloudHSM CLI](cloudhsm_cli-key-unshare.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Replicate a key with CloudHSM CLI
<a name="cloudhsm_cli-key-replicate"></a>

Use the **key replicate** command in CloudHSM CLI to replicate a key from a source AWS CloudHSM cluster to a destination AWS CloudHSM cluster.

## User type
<a name="chsm-cli-key-replicate-user-type"></a>

The following types of users can run this command.
+ Admins (COs)
+ Crypto users (CUs)
**Note**  
Crypto Users must own the key to use this command.

## Requirements
<a name="cloudhsm_cli-key-replicate-requirements"></a>
+ The source and destination clusters must be clones. This means one was created from a backup of the other, or they were both created from a common backup. See [Creating clusters from backups](create-cluster-from-backup.md) for more information.
+ The owner of the key must exist on the destination cluster. Additionally, if the key is shared with any users, those users must also exist on the destination cluster.
+ To run this command, you must be logged in as a crypto user or an admin on both the source and destination clusters.
  +  In single command mode, the command will use the CLOUDHSM\$1PIN and CLOUDHSM\$1ROLE environmental variables to authenticate on the source cluster. See [Single Command mode](cloudhsm_cli-modes.md#cloudhsm_cli-mode-single-command) for more information. To provide credentials for the destination cluster, you need to set two additional environmental variables: DESTINATION\$1CLOUDHSM\$1PIN and DESTINATION\$1CLOUDHSM\$1ROLE:

    ```
    $ export DESTINATION_CLOUDHSM_ROLE=<role>
    ```

    ```
    $ export DESTINATION_CLOUDHSM_PIN=<username:password>
    ```
  +  In interactive mode, users will need to explicitly log into both the source and destination clusters.

## Syntax
<a name="chsm-cli-key-replicate-syntax"></a>

```
aws-cloudhsm > help key replicate
Replicate a key from a source to a destination cluster

Usage: key replicate --filter [<FILTER>...] --source-cluster-id <SOURCE_CLUSTER_ID> --destination-cluster-id <DESTINATION_CLUSTER_ID>

Options:
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select matching key on the source cluster
      --source-cluster-id <SOURCE_CLUSTER_ID>
          Source cluster ID
      --destination-cluster-id <DESTINATION_CLUSTER_ID>
          Destination cluster ID
  -h, --help
          Print help
```

## Examples
<a name="chsm-cli-key-replicate-examples"></a>

**Example: Replicate key**  
This command replicates a key from a source cluster with to a cloned destination cluster. The example below demonstrates the output when logged in as a crypto user on both clusters.  

```
crypto-user-1@cluster-1234abcdefg > key replicate \
      --filter attr.label=example-key \
      --source-cluster-id cluster-1234abcdefg \
      --destination-cluster-id cluster-2345bcdefgh
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x0000000000300006",
      "key-info": {
        "key-owners": [
          {
            "username": "crypto-user-1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "example-key",
        "id": "0x",
        "check-value": "0x5e118e",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": true,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    },
    "message": "Successfully replicated key"
  }
}
```

## Arguments
<a name="key-replicate-arguments"></a>

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key on the source cluster.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: Yes

***<SOURCE\$1CLUSTER\$1ID>***  
The source cluster ID.  
Required: Yes

***<DESTINATION\$1CLUSTER\$1ID>***  
The destination cluster ID.  
Required: Yes

## Related topics
<a name="chsm-key-replicate-seealso"></a>
+ [Connecting to multiple clusters with CloudHSM CLI](cloudhsm_cli-configs-multi-cluster.md)

# Set the attributes of keys with CloudHSM CLI
<a name="cloudhsm_cli-key-set-attribute"></a>

Use the **key set-attribute** command in CloudHSM CLI to set the attributes of keys in your AWS CloudHSM cluster. Only the CU who created the key and consequently owns it can change the key's attributes.

For a list of key attributes that can be used in CloudHSM CLI, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).

## User type
<a name="chsm-cli-key-set-attribute-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs) can run this command.
+ Admins can set the trusted attribute.

## Requirements
<a name="chsm-cli-key-set-attribute-requirements"></a>

To run this command, you must be logged in as a CU. To set the trusted attribute, you must be logged in as an admin user.

## Syntax
<a name="chsm-cli-key-set-attribute-syntax"></a>

```
aws-cloudhsm > help key set-attribute
Set an attribute for a key in the HSM cluster

Usage: cloudhsm-cli key set-attribute [OPTIONS] --filter [<FILTER>...] --name <KEY_ATTRIBUTE> --value <KEY_ATTRIBUTE_VALUE>

Options:
      --cluster-id <CLUSTER_ID>         Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]            Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key to modify
      --name <KEY_ATTRIBUTE>            Name of attribute to be set
      --value <KEY_ATTRIBUTE_VALUE>...  Attribute value to be set
      --approval <APPROVAL>            Filepath of signed quorum token file to approve operation
  -h, --help                            Print help
```

## Example: Setting a key attribute
<a name="chsm-cli-key-set-attribute-examples"></a>

The following example shows how to use the **key set-attribute** command to set the label.

**Example**  

1. Use the key with the label `my_key`, as shown here:

   ```
   aws-cloudhsm > key set-attribute --filter attr.label=my_key --name encrypt --value false
   {
     "error_code": 0,
     "data": {
       "message": "Attribute set successfully"
     }
   }
   ```

1. Use the **key list** command to confirm the `encrypt` attribute has changed:

   ```
   aws-cloudhsm > key list --filter attr.label=my_key --verbose
   {
     "error_code": 0,
     "data": {
       "matched_keys": [
         {
           "key-reference": "0x00000000006400ec",
           "key-info": {
             "key-owners": [
               {
                 "username": "bob",
                 "key-coverage": "full"
               }
             ],
             "shared-users": [],
           "key-quorum-values": {
             "manage-key-quorum-value": 0,
             "use-key-quorum-value": 0
           },
             "cluster-coverage": "full"
           },
           "attributes": {
             "key-type": "aes",
             "label": "my_key",
             "id": "",
             "check-value": "0x6bd9f7",
             "class": "secret-key",
             "encrypt": false,
             "decrypt": true,
             "token": true,
             "always-sensitive": true,
             "derive": true,
             "destroyable": true,
             "extractable": true,
             "local": true,
             "modifiable": true,
             "never-extractable": false,
             "private": true,
             "sensitive": true,
             "sign": true,
             "trusted": true,
             "unwrap": true,
             "verify": true,
             "wrap": true,
             "wrap-with-trusted": false,
             "key-length-bytes": 32
           }
         }
       ],
       "total_key_count": 1,
       "returned_key_count": 1
     }
   }
   ```

## Arguments
<a name="chsm-cli-key-set-attribute-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<KEY\$1ATTRIBUTE>***  
Specifies the name of the key's attribute.  
Required: Yes

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key for deletion.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: No

***<KEY\$1ATTRIBUTE\$1VALUE>***  
Specifies the value of the key's attribute.  
Required: Yes

***<KEY\$1REFERENCE>***  
A hexadecimal or decimal representation of the key. (such as a key handle).  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the key is greater than 1.

## Related topics
<a name="chsm-cli-key-set-attribute-see-also"></a>
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)

# Share a key using CloudHSM CLI
<a name="cloudhsm_cli-key-share"></a>

Use the **key share** command in CloudHSM CLI to share a key with other CUs in your AWS CloudHSM cluster.

Only the CU who created the key and consequently owns it can share the key. Users with whom a key is shared can use the key in cryptographic operations, but they cannot delete, export, share, unshare, derive, or wrap the key. Additionally, these users cannot change [key attributes](cloudhsm_cli-key-attributes.md).

## User type
<a name="chsm-cli-key-share-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="chsm-cli-key-share-requirements"></a>

To run this command, you must be logged in as a CU.

## Syntax
<a name="chsm-cli-key-share-syntax"></a>

```
aws-cloudhsm > help key share
Share a key in the HSM cluster with another user

Usage: key share --filter [<FILTER>...] --username <USERNAME> --role <ROLE>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key for sharing

      --username <USERNAME>
          A username with which the key will be shared

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation

  -h, --help
          Print help (see a summary with '-h')
```

## Example: Share a key with another CU
<a name="chsm-cli-key-share-examples"></a>

The following example shows how to use the **key share** command to share a key with the CU `alice`.

**Example**  

1. Run the **key share** command to share the key with `alice`.

   ```
   aws-cloudhsm > key share --filter attr.label="rsa_key_to_share" attr.class=private-key --username alice --role crypto-user
   {
     "error_code": 0,
     "data": {
       "message": "Key shared successfully"
     }
   }
   ```

1. Run the **key list** command.

   ```
   aws-cloudhsm > key list --filter attr.label="rsa_key_to_share" attr.class=private-key --verbose
   {
     "error_code": 0,
     "data": {
       "matched_keys": [
         {
           "key-reference": "0x00000000001c0686",
           "key-info": {
             "key-owners": [
               {
                 "username": "cu3",
                 "key-coverage": "full"
               }
             ],
             "shared-users": [
               {
                 "username": "cu2",
                 "key-coverage": "full"
               },
               {
                 "username": "cu1",
                 "key-coverage": "full"
               },
               {
                 "username": "cu4",
                 "key-coverage": "full"
               },
               {
                 "username": "cu5",
                 "key-coverage": "full"
               },
               {
                 "username": "cu6",
                 "key-coverage": "full"
               },
               {
                 "username": "cu7",
                 "key-coverage": "full"
               },
               {
                 "username": "alice",
                 "key-coverage": "full"
               }
             ],
             "key-quorum-values": {
               "manage-key-quorum-value": 0,
               "use-key-quorum-value": 0
             },
             "cluster-coverage": "full"
           },
           "attributes": {
             "key-type": "rsa",
             "label": "rsa_key_to_share",
             "id": "",
             "check-value": "0xae8ff0",
             "class": "private-key",
             "encrypt": false,
             "decrypt": true,
             "token": true,
             "always-sensitive": true,
             "derive": false,
             "destroyable": true,
             "extractable": true,
             "local": true,
             "modifiable": true,
             "never-extractable": false,
             "private": true,
             "sensitive": true,
             "sign": true,
             "trusted": false,
             "unwrap": true,
             "verify": false,
             "wrap": false,
             "wrap-with-trusted": false,
             "key-length-bytes": 1219,
             "public-exponent": "0x010001",
             "modulus": "0xa8855cba933cec0c21a4df0450ec31675c024f3e65b2b215a53d2bda6dcd191f75729150b59b4d86df58254c8f518f7d000cc04d8e958e7502c7c33098e28da4d94378ef34fb57d1cc7e042d9119bd79be0df728421a980a397095157da24cf3cc2b6dab12225d33fdca11f0c6ed1a5127f12488cda9a556814b39b06cd8373ff5d371db2212887853621b8510faa7b0779fbdec447e1f1d19f343acb02b22526487a31f6c704f8f003cb4f7013136f90cc17c2c20e414dc1fc7bcfb392d59c767900319679fc3307388633485657ce2e1a3deab0f985b0747ef4ed339de78147d1985d14fdd8634219321e49e3f5715e79c298f18658504bab04086bfbdcd3b",
             "modulus-size-bits": 2048
           }
         }
       ],
       "total_key_count": 1,
       "returned_key_count": 1
     }
   }
   ```

1. In the above list, verify `alice` is in the list of `shared-users`

## Arguments
<a name="chsm-cli-key-share-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key for deletion.  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: Yes

***<USERNAME>***  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). The username is not case sensitive in this command, username is always displayed in lowercase.  
Required: Yes

***<ROLE>***  
Specifies the role assigned to this user. This parameter is required. To get the user’s role, use the user list command. For detailed information about the user types on an HSM, see [HSM user types for CloudHSM CLI](understanding-users.md).  
Required: Yes

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the key is greater than 1.

## Related topics
<a name="chsm-cli-key-share-see-also"></a>
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)

# Unshare a key using CloudHSM CLI
<a name="cloudhsm_cli-key-unshare"></a>

Use the **key unshare** command in CloudHSM CLI to unshare a key with other CUs in your AWS CloudHSM cluster.

Only the CU who created the key and consequently owns it can unshare the key. Users with whom a key is shared can use the key in cryptographic operations, but they cannot delete, export, share, or unshare the key. Additionally, these users cannot change [key attributes](cloudhsm_cli-key-attributes.md).

## User type
<a name="chsm-cli-key-unshare-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="chsm-cli-key-unshare-requirements"></a>

To run this command, you must be logged in as a CU.

## Syntax
<a name="chsm-cli-key-unshare-syntax"></a>

```
aws-cloudhsm > help key unshare
Unshare a key in the HSM cluster with another user

Usage: key unshare --filter [<FILTER>...] --username <USERNAME> --role <ROLE>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a matching key for unsharing

      --username <USERNAME>
          A username with which the key will be unshared

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation

  -h, --help
          Print help (see a summary with '-h')
```

## Example: Unshare a key with another CU
<a name="chsm-cli-key-share-examples"></a>

The following example shows how to use the **key unshare** command to unshare a key with the CU `alice`.

**Example**  

1. Run the **key list** command and filter by the specific key you want to unshare with `alice`.

   ```
   aws-cloudhsm > key list --filter attr.label="rsa_key_to_share" attr.class=private-key --verbose
   {
     "error_code": 0,
     "data": {
       "matched_keys": [
         {
           "key-reference": "0x00000000001c0686",
           "key-info": {
             "key-owners": [
               {
                 "username": "cu3",
                 "key-coverage": "full"
               }
             ],
             "shared-users": [
               {
                 "username": "cu2",
                 "key-coverage": "full"
               },
               {
                 "username": "cu1",
                 "key-coverage": "full"
               },
               {
                 "username": "cu4",
                 "key-coverage": "full"
               },
               {
                 "username": "cu5",
                 "key-coverage": "full"
               },
               {
                 "username": "cu6",
                 "key-coverage": "full"
               },
               {
                 "username": "cu7",
                 "key-coverage": "full"
               },
               {
                 "username": "alice",
                 "key-coverage": "full"
               }
             ],
             "key-quorum-values": {
               "manage-key-quorum-value": 0,
               "use-key-quorum-value": 0
             },
             "cluster-coverage": "full"
           },
           "attributes": {
             "key-type": "rsa",
             "label": "rsa_key_to_share",
             "id": "",
             "check-value": "0xae8ff0",
             "class": "private-key",
             "encrypt": false,
             "decrypt": true,
             "token": true,
             "always-sensitive": true,
             "derive": false,
             "destroyable": true,
             "extractable": true,
             "local": true,
             "modifiable": true,
             "never-extractable": false,
             "private": true,
             "sensitive": true,
             "sign": true,
             "trusted": false,
             "unwrap": true,
             "verify": false,
             "wrap": false,
             "wrap-with-trusted": false,
             "key-length-bytes": 1219,
             "public-exponent": "0x010001",
             "modulus": "0xa8855cba933cec0c21a4df0450ec31675c024f3e65b2b215a53d2bda6dcd191f75729150b59b4d86df58254c8f518f7d000cc04d8e958e7502c7c33098e28da4d94378ef34fb57d1cc7e042d9119bd79be0df728421a980a397095157da24cf3cc2b6dab12225d33fdca11f0c6ed1a5127f12488cda9a556814b39b06cd8373ff5d371db2212887853621b8510faa7b0779fbdec447e1f1d19f343acb02b22526487a31f6c704f8f003cb4f7013136f90cc17c2c20e414dc1fc7bcfb392d59c767900319679fc3307388633485657ce2e1a3deab0f985b0747ef4ed339de78147d1985d14fdd8634219321e49e3f5715e79c298f18658504bab04086bfbdcd3b",
             "modulus-size-bits": 2048
           }
         }
       ],
       "total_key_count": 1,
       "returned_key_count": 1
     }
   }
   ```

1. Confirm `alice` is in the `shared-users` output, and run the following **key unshare** command to unshare the key with `alice`.

   ```
   aws-cloudhsm > key unshare --filter attr.label="rsa_key_to_share" attr.class=private-key --username alice --role crypto-user
   {
     "error_code": 0,
     "data": {
       "message": "Key unshared successfully"
     }
   }
   ```

1. Run the `key list` command again to confirm that the key has been unshared with `alice`.

   ```
   aws-cloudhsm > key list --filter attr.label="rsa_key_to_share" attr.class=private-key --verbose
   {
     "error_code": 0,
     "data": {
       "matched_keys": [
         {
           "key-reference": "0x00000000001c0686",
           "key-info": {
             "key-owners": [
               {
                 "username": "cu3",
                 "key-coverage": "full"
               }
             ],
             "shared-users": [
               {
                 "username": "cu2",
                 "key-coverage": "full"
               },
               {
                 "username": "cu1",
                 "key-coverage": "full"
               },
               {
                 "username": "cu4",
                 "key-coverage": "full"
               },
               {
                 "username": "cu5",
                 "key-coverage": "full"
               },
               {
                 "username": "cu6",
                 "key-coverage": "full"
               },
               {
                 "username": "cu7",
                 "key-coverage": "full"
               },
             ],
             "key-quorum-values": {
               "manage-key-quorum-value": 0,
               "use-key-quorum-value": 0
             },
             "cluster-coverage": "full"
           },
           "attributes": {
             "key-type": "rsa",
             "label": "rsa_key_to_share",
             "id": "",
             "check-value": "0xae8ff0",
             "class": "private-key",
             "encrypt": false,
             "decrypt": true,
             "token": true,
             "always-sensitive": true,
             "derive": false,
             "destroyable": true,
             "extractable": true,
             "local": true,
             "modifiable": true,
             "never-extractable": false,
             "private": true,
             "sensitive": true,
             "sign": true,
             "trusted": false,
             "unwrap": true,
             "verify": false,
             "wrap": false,
             "wrap-with-trusted": false,
             "key-length-bytes": 1219,
             "public-exponent": "0x010001",
             "modulus": "0xa8855cba933cec0c21a4df0450ec31675c024f3e65b2b215a53d2bda6dcd191f75729150b59b4d86df58254c8f518f7d000cc04d8e958e7502c7c33098e28da4d94378ef34fb57d1cc7e042d9119bd79be0df728421a980a397095157da24cf3cc2b6dab12225d33fdca11f0c6ed1a5127f12488cda9a556814b39b06cd8373ff5d371db2212887853621b8510faa7b0779fbdec447e1f1d19f343acb02b22526487a31f6c704f8f003cb4f7013136f90cc17c2c20e414dc1fc7bcfb392d59c767900319679fc3307388633485657ce2e1a3deab0f985b0747ef4ed339de78147d1985d14fdd8634219321e49e3f5715e79c298f18658504bab04086bfbdcd3b",
             "modulus-size-bits": 2048
           }
         }
       ],
       "total_key_count": 1,
       "returned_key_count": 1
     }
   }
   ```

## Arguments
<a name="chsm-cli-key-unshare-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a matching key for deletion.  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: Yes

***<USERNAME>***  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). The username is not case sensitive in this command, username is always displayed in lowercase.  
Required: Yes

***<ROLE>***  
Specifies the role assigned to this user. This parameter is required. To get the user’s role, use the user list command. For detailed information about the user types on an HSM, see [HSM user types for CloudHSM CLI](understanding-users.md).  
Required: Yes

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the key is greater than 1.

## Related topics
<a name="chsm-cli-key-unshare-see-also"></a>
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)

# The key unwrap command in CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap"></a>

The **key unwrap** parent command in CloudHSM CLI imports an encrypted (wrapped) symmetric or asymmetric private key from a file and into the HSM. This command is designed to import encrypted keys that were wrapped by the [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) command, but it can also be used to unwrap keys that were wrapped with other tools. However, in those situations, we recommend using the PKCS\$111 or JCE software libraries to unwrap the key.
+ [aes-gcm](cloudhsm_cli-key-unwrap-aes-gcm.md)
+ [aes-no-pad](cloudhsm_cli-key-unwrap-aes-no-pad.md)
+ [aes-pkcs5-pad](cloudhsm_cli-key-unwrap-aes-pkcs5-pad.md)
+ [aes-zero-pad](cloudhsm_cli-key-unwrap-aes-zero-pad.md)
+ [cloudhsm-aes-gcm](cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm.md)
+ [rsa-aes](cloudhsm_cli-key-unwrap-rsa-aes.md)
+ [rsa-oaep](cloudhsm_cli-key-unwrap-rsa-oaep.md)
+ [rsa-pkcs](cloudhsm_cli-key-unwrap-rsa-pkcs.md)

# Unwrap a key with AES-GCM using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-aes-gcm"></a>

Use the **key unwrap aes-gcm** command in CloudHSM CLI to unwrap a payload key into the cluster using the AES wrapping key and the `AES-GCM` unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`.

To use the **key unwrap aes-gcm** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-aes-gcm-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-aes-gcm-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-aes-gcm-syntax"></a>

```
aws-cloudhsm > help key unwrap aes-gcm
Usage: key unwrap aes-gcm [OPTIONS] --filter [<FILTER>...] --tag-length-bits <TAG_LENGTH_BITS> --key-type-class <KEY_TYPE_CLASS> --label <LABEL> --iv <IV> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --aad <AAD>
          Aes GCM Additional Authenticated Data (AAD) value, in hex
      --tag-length-bits <TAG_LENGTH_BITS>
          Aes GCM tag length in bits
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --iv <IV>
          Initial value used to wrap the key, in hex
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-aes-gcm-examples"></a>

These examples show how to use the **key unwrap aes-gcm** command using an AES key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64  --aad 0x10 --iv 0xf90613bb8e337ec0339aad21 --data xvslgrtg8kHzrvekny97tLSIeokpPwV8
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e4",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

**Example: Unwrap a payload key provided through a data path**  

```
aws-cloudhsm > key unwrap aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64  --aad 0x10 --iv 0xf90613bb8e337ec0339aad21 --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e4",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-aes-gcm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with.  
Required: Yes

***<DATA\$1PATH>***  
Path to the binary file containing the wrapped key data.  
Required: Yes (unless provided through Base64 encoded data)

***<DATA>***  
Base64 encoded wrapped key data.  
Required: Yes (unless provided through data path)

***<ATTRIBUTES>***  
Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key.  
Required: No

***<AAD>***  
Aes GCM Additional Authenticated Data (AAD) value, in hex.  
Required: No

***<TAG\$1LENGTH\$1BITS>***  
Aes GCM tag length in bits.  
Required: Yes

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<LABEL>***  
Label for the unwrapped key.  
Required: Yes

***<SESSION>***  
Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.  
Required: No

***<IV>***  
Initial value used to wrap the key, in hex.  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-aes-gcm-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with AES-NO-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-aes-no-pad"></a>

Use the **key unwrap aes-no-pad** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `AES-NO-PAD` unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`.

To use the **key unwrap aes-no-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-syntax"></a>

```
aws-cloudhsm > help key unwrap aes-no-pad
Usage: key unwrap aes-no-pad [OPTIONS] --filter [<FILTER>...] --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-examples"></a>

These examples show how to use the **key unwrap aes-no-pad** command using an AES key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap aes-no-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data eXK3PMAOnKM9y3YX6brbhtMoC060EOH9
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08ec",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

**Example: Unwrap a payload key provided through a data path**  

```
aws-cloudhsm > key unwrap aes-no-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08ec",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with.  
Required: Yes

***<DATA\$1PATH>***  
Path to the binary file containing the wrapped key data.  
Required: Yes (unless provided through Base64 encoded data)

***<DATA>***  
Base64 encoded wrapped key data.  
Required: Yes (unless provided through data path)

***<ATTRIBUTES>***  
Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key.  
Required: No

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<LABEL>***  
Label for the unwrapped key.  
Required: Yes

***<SESSION>***  
Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with AES-PKCS5-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad"></a>

Use the **key unwrap aes-pkcs5-pad** command in CloudHSM CLI to unwrap a payload key using the AES wrapping key and the `AES-PKCS5-PAD` unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`.

To use the **key unwrap aes-pkcs5-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-syntax"></a>

```
aws-cloudhsm > help key unwrap aes-pkcs5-pad
Usage: key unwrap aes-pkcs5-pad [OPTIONS] --filter [<FILTER>...] --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-examples"></a>

These examples show how to use the **key unwrap aes-pkcs5-pad** command using an AES key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap aes-pkcs5-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data MbuYNresfOKyGNnxKWen88nSfX+uUE/0qmGofSisicY=
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08e3",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

**Example: Unwrap a payload key provided through a data path**  

```
aws-cloudhsm > key unwrap aes-pkcs5-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08e3",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with.  
Required: Yes

***<DATA\$1PATH>***  
Path to the binary file containing the wrapped key data.  
Required: Yes (unless provided through Base64 encoded data)

***<DATA>***  
Base64 encoded wrapped key data.  
Required: Yes (unless provided through data path)

***<ATTRIBUTES>***  
Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key.  
Required: No

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<LABEL>***  
Label for the unwrapped key.  
Required: Yes

***<SESSION>***  
Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with AES-ZERO-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad"></a>

Use the **key unwrap aes-zero-pad** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `AES-ZERO-PAD` unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`.

To use the **key unwrap aes-no-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-syntax"></a>

```
aws-cloudhsm > help key unwrap aes-zero-pad
Usage: key unwrap aes-zero-pad [OPTIONS] --filter [<FILTER>...] --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-examples"></a>

These examples show how to use the **key unwrap aes-zero-pad** command using an AES key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap aes-zero-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data L1wVlL/YeBNVAw6Mpk3owFJZXBzDLONt
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08e7",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

**Example: Unwrap a payload key provided through a data path**  

```
aws-cloudhsm > key unwrap aes-zero-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08e7",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with.  
Required: Yes

***<DATA\$1PATH>***  
Path to the binary file containing the wrapped key data.  
Required: Yes (unless provided through Base64 encoded data)

***<DATA>***  
Base64 encoded wrapped key data.  
Required: Yes (unless provided through data path)

***<ATTRIBUTES>***  
Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key.  
Required: No

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<LABEL>***  
Label for the unwrapped key.  
Required: Yes

***<SESSION>***  
Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with CLOUDHSM-AES-GCM using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm"></a>

Use the **key unwrap cloudhsm-aes-gcm** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `CLOUDHSM-AES-GCM` unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`.

To use the **key unwrap cloudhsm-aes-gcm** command, you must have the AES wrapping key in your AWS CloudHSM cluster and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-syntax"></a>

```
aws-cloudhsm > help key unwrap cloudhsm-aes-gcm
Usage: key unwrap cloudhsm-aes-gcm [OPTIONS] --filter [<FILTER>...] --tag-length-bits <TAG_LENGTH_BITS> --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --aad <AAD>
          Aes GCM Additional Authenticated Data (AAD) value, in hex
      --tag-length-bits <TAG_LENGTH_BITS>
          Aes GCM tag length in bits
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-examples"></a>

These examples show how to use the **key unwrap cloudhsm-aes-gcm** command using an AES key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap cloudhsm-aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64  --aad 0x10 --data 6Rn8nkjEriDYlnP3P8nPkYQ8hplOEJ899zsrF+aTB0i/fIlZ
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001408e8",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

**Example: Unwrap a payload key provided through a data path**  

```
aws-cloudhsm > key unwrap cloudhsm-aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64  --aad 0x10 --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001408e8",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with.  
Required: Yes

***<DATA\$1PATH>***  
Path to the binary file containing the wrapped key data.  
Required: Yes (unless provided through Base64 encoded data)

***<DATA>***  
Base64 encoded wrapped key data.  
Required: Yes (unless provided through data path)

***<ATTRIBUTES>***  
Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key.  
Required: No

***<AAD>***  
Aes GCM Additional Authenticated Data (AAD) value, in hex.  
Required: No

***<TAG\$1LENGTH\$1BITS>***  
Aes GCM tag length in bits.  
Required: Yes

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<LABEL>***  
Label for the unwrapped key.  
Required: Yes

***<SESSION>***  
Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with RSA-AES using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-rsa-aes"></a>

Use the **key unwrap rsa-aes** command in CloudHSM CLI to unwrap a payload key using an RSA private key and the `RSA-AES` unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`.

To use the **key unwrap rsa-aes**, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. 

**Note**  
This command is only available with CloudHSM CLI 5.11\$1.

## User type
<a name="cloudhsm_cli-key-unwrap-rsa-aes-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-rsa-aes-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-rsa-aes-syntax"></a>

```
aws-cloudhsm > help key unwrap rsa-aes
Usage: key unwrap rsa-aes [OPTIONS] --filter [<FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF> --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --hash-function <HASH_FUNCTION>
          Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512]
      --mgf <MGF>
          Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-unwrap-rsa-aes-examples"></a>

These examples show how to use the **key unwrap rsa-aes** command using the RSA private key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap rsa-aes --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --hash-function sha256 --mgf mgf1-sha256 --data HrSE1DEyLjIeyGdPa9R+ebiqB5TIJGyamPker31ZebPwRA+NcerbAJO8DJ1lXPygZcI21vIFSZJuWMEiWpe1R9D/5WSYgxLVKex30xCFqebtEzxbKuv4DOmU4meSofqREYvtb3EoIKwjyxCMRQFgoyUCuP4y0f0eSv0k6rSJh4NuCsHptXZbtgNeRcR4botN7LlzkEIUcq4fVHaatCwd0J1QGKHKyRhkol+RL5WGXKe4nAboAkC5GO7veI5yHL1SaKlssSJtTL/CFpbSLsAFuYbv/NUCWwMY5mwyVTCSlw+HlgKK+5TH1MzBaSi8fpfyepLT8sHy2Q/VRl6ifb49p6m0KQFbRVvz/OWUd6l4d97BdgtaEz6ueg==
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e2",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

**Example: Unwrap a payload key provided through a data path**  

```
aws-cloudhsm > key unwrap rsa-aes --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --hash-function sha256 --mgf mgf1-sha256 --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e2",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-rsa-aes-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with.  
Required: Yes

***<DATA\$1PATH>***  
Path to the binary file containing the wrapped key data.  
Required: Yes (unless provided through Base64 encoded data)

***<DATA>***  
Base64 encoded wrapped key data.  
Required: Yes (unless provided through data path)

***<ATTRIBUTES>***  
Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key.  
Required: No

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<HASH\$1FUNCTION>***  
Specifies the hash function.  
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<MGF>***  
Specifies the mask generation function.   
The mask generation function hash function must match the signing mechanism hash function.
Valid values:  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
Required: Yes

***<LABEL>***  
Label for the unwrapped key.  
Required: Yes

***<SESSION>***  
Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-rsa-aes-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with RSA-OAEP using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-rsa-oaep"></a>

Use the **key unwrap rsa-oaep** command in CloudHSM CLI to unwrap a payload key using the RSA private key and the `RSA-OAEP` unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`.

To use the **key unwrap rsa-oaep** command, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-syntax"></a>

```
aws-cloudhsm > help key unwrap rsa-oaep
Usage: key unwrap rsa-oaep [OPTIONS] --filter [<FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF> --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--data-path <DATA_PATH>|--data <DATA>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --hash-function <HASH_FUNCTION>
          Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512]
      --mgf <MGF>
          Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-examples"></a>

These examples show how to use the **key unwrap rsa-oaep** command using the RSA private key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap rsa-oaep --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-example-key --hash-function sha256 --mgf mgf1-sha256 --data OjJe4msobPLz9TuSAdULEu17T5rMDWtSlLyBSkLbaZnYzzpdrhsbGLbwZJCtB/jGkDNdB4qyTAOQwEpggGf6v+Yx6JcesNeKKNU8XZal/YBoHC8noTGUSDI2qr+u2tDc84NPv6d+F2KOONXsSxMhmxzzNG/gzTVIJhOuy/B1yHjGP4mOXoDZf5+7f5M1CjxBmz4Vva/wrWHGCSG0yOaWblEvOiHAIt3UBdyKmU+/My4xjfJv7WGGu3DFUUIZ06TihRtKQhUYU1M9u6NPf9riJJfHsk6QCuSZ9yWThDT9as6i7e3htnyDhIhGWaoK8JU855cN/YNKAUqkNpC4FPL3iw==
{
  "data": {
    "key": {
      "key-reference": "0x00000000001808e9",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

**Example: Unwrap a payload key provided through a data path**  

```
aws-cloudhsm > key unwrap rsa-oaep --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-example-key --hash-function sha256 --mgf mgf1-sha256 --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e9",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with.  
Required: Yes

***<DATA\$1PATH>***  
Path to the binary file containing the wrapped key data.  
Required: Yes (unless provided through Base64 encoded data)

***<DATA>***  
Base64 encoded wrapped key data.  
Required: Yes (unless provided through data path)

***<ATTRIBUTES>***  
Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key.  
Required: No

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<HASH\$1FUNCTION>***  
Specifies the hash function.  
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<MGF>***  
Specifies the mask generation function.   
The mask generation function hash function must match the signing mechanism hash function.
Valid values:  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
Required: Yes

***<LABEL>***  
Label for the unwrapped key.  
Required: Yes

***<SESSION>***  
Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with RSA-PKCS using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs"></a>

Use the **key unwrap rsa-pkcs** command in CloudHSM CLI to unwrap a payload key using the RSA private key and the `RSA-PKCS` unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`.

To use the key **unwrap rsa-pkcs** command, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-syntax"></a>

```
aws-cloudhsm > help key unwrap rsa-pkcs
Usage: key unwrap rsa-pkcs [OPTIONS] --filter [<FILTER>...] --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-examples"></a>

These examples show how to use the **key unwrap rsa-oaep** command using an AES key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap rsa-pkcs --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --data am0Nc7+YE8FWs+5HvU7sIBcXVb24QA0l65nbNAD+1bK+e18BpSfnaI3P+r8Dp+pLu1ofoUy/vtzRjZoCiDofcz4EqCFnGl4GdcJ1/3W/5WRvMatCa2d7cx02swaeZcjKsermPXYRO1lGlfq6NskwMeeTkV8R7Rx9artFrs1y0DdIgIKVaiFHwnBIUMnlQrR2zRmMkfwU1jxMYmOYyD031F5VbnjSrhfMwkww2la7uf/c3XdFJ2+0Bo94c6og/yfPcpOOobJlITCoXhtMRepSdO4OggYq/6nUDuHCtJ86pPGnNahyr7+sAaSI3a5ECQLUjwaIARUCyoRh7EFK3qPXcg==
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08ef",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

**Example: Unwrap a payload key provided through a data path**  

```
aws-cloudhsm > key unwrap rsa-pkcs --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08ef",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with.  
Required: Yes

***<DATA\$1PATH>***  
Path to the binary file containing the wrapped key data.  
Required: Yes (unless provided through Base64 encoded data)

***<DATA>***  
Base64 encoded wrapped key data.  
Required: Yes (unless provided through data path)

***<ATTRIBUTES>***  
Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key.  
Required: No

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<LABEL>***  
Label for the unwrapped key.  
Required: Yes

***<SESSION>***  
Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.  
Required: No

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# The key wrap command in CloudHSM CLI
<a name="cloudhsm_cli-key-wrap"></a>

The **key wrap** command in CloudHSM CLI exports an encrypted copy of a symmetric or asymmetric private key from the hardware security module (HSM) to a file. When you run **key wrap**, you specify two things: The key to export and the output file. The key to export is a key on the HSM that will encrypt (wrap) the key that you want to export.

The **key wrap** command 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. To import the encrypted key back into the HSM, use [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md). Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users with whom the key is shared can only use the key in cryptographic operations.

The **key wrap** command consists of the following subcommands:
+ [aes-gcm](cloudhsm_cli-key-wrap-aes-gcm.md)
+ [aes-no-pad](cloudhsm_cli-key-wrap-aes-no-pad.md)
+ [aes-pkcs5-pad](cloudhsm_cli-key-wrap-aes-pkcs5-pad.md)
+ [aes-zero-pad](cloudhsm_cli-key-wrap-aes-zero-pad.md)
+ [cloudhsm-aes-gcm](cloudhsm_cli-key-wrap-cloudhsm-aes-gcm.md)
+ [rsa-aes](cloudhsm_cli-key-wrap-rsa-aes.md)
+ [rsa-oaep](cloudhsm_cli-key-wrap-rsa-oaep.md)
+ [rsa-pkcs](cloudhsm_cli-key-wrap-rsa-pkcs.md)

# Wrap a key with AES-GCM using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-aes-gcm"></a>

Use the **key wrap aes-gcm** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module (HSM) and the `AES-GCM` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

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

To use the **key wrap aes-gcm** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping with the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-aes-gcm-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-aes-gcm-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-aes-gcm-syntax"></a>

```
aws-cloudhsm > help key wrap aes-gcm
Usage: key wrap aes-gcm [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...] --tag-length-bits <TAG_LENGTH_BITS>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
      --aad <AAD>
          Aes GCM Additional Authenticated Data (AAD) value, in hex
      --tag-length-bits <TAG_LENGTH_BITS>
          Aes GCM tag length in bits
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-aes-gcm-examples"></a>

This example shows how to use the **key wrap aes-gcm** command using an AES key.

**Example**  

```
aws-cloudhsm > key wrap aes-gcm --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example --tag-length-bits 64  --aad 0x10
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "iv": "0xf90613bb8e337ec0339aad21",
    "wrapped_key_data": "xvslgrtg8kHzrvekny97tLSIeokpPwV8"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-aes-gcm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes

***<AAD>***  
AES GCM Additional Authenticated Data (AAD) value, in hex.   
Required: No

***<TAG\$1LENGTH\$1BITS>***  
AES GCM tag length in bits.  
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-aes-gcm-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with AES-NO-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-aes-no-pad"></a>

Use the **key wrap aes-no-pad** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module (HSM) and the `AES-NO-PAD` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

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

To use the **key wrap aes-no-pad** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping using the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-aes-no-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-aes-no-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-aes-no-pad-syntax"></a>

```
aws-cloudhsm > help key wrap aes-no-pad
Usage: key wrap aes-no-pad [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-aes-no-pad-examples"></a>

This example shows how to use the **key wrap aes-no-pad** command using an AES key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap aes-no-pad --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "wrapped_key_data": "eXK3PMAOnKM9y3YX6brbhtMoC060EOH9"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-aes-no-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-aes-no-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with AES-PKCS5-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad"></a>

Use the **key wrap aes-pkcs5-pad** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module (HSM) and the `AES-PKCS5-PAD` wrapping mechanism. The payload key's `extractable` attribute must be set to `true`.

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

To use the **key wrap aes-pkcs5-pad** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping using the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-syntax"></a>

```
aws-cloudhsm > help key wrap aes-pkcs5-pad
Usage: key wrap aes-pkcs5-pad [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-examples"></a>

This example shows how to use the **key wrap aes-pkcs5-pad** command using an AES key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap aes-pkcs5-pad --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "wrapped_key_data": "MbuYNresfOKyGNnxKWen88nSfX+uUE/0qmGofSisicY="
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with AES-ZERO-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-aes-zero-pad"></a>

Use the **key wrap aes-zero-pad** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module HSM) and the `AES-ZERO-PAD` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

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

To use the **key wrap aes-zero-pad** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping using the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command with the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-syntax"></a>

```
aws-cloudhsm > help key wrap aes-zero-pad
Usage: key wrap aes-zero-pad [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-examples"></a>

This example shows how to use the **key wrap aes-zero-pad ** command using an AES key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap aes-zero-pad --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "wrapped_key_data": "L1wVlL/YeBNVAw6Mpk3owFJZXBzDLONt"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with CLOUDHSM-AES-GCM using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm"></a>

Use the **key wrap cloudhsm-aes-gcm** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module (HSM) and the `CLOUDHSM-AES-GCM` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

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

To use the **key wrap cloudhsm-aes-gcm** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping with the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-syntax"></a>

```
aws-cloudhsm > help key wrap cloudhsm-aes-gcm
Usage: key wrap cloudhsm-aes-gcm [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...] --tag-length-bits <TAG_LENGTH_BITS>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
      --aad <AAD>
          Aes GCM Additional Authenticated Data (AAD) value, in hex
      --tag-length-bits <TAG_LENGTH_BITS>
          Aes GCM tag length in bits
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-examples"></a>

This example shows how to use the **key wrap cloudhsm-aes-gcm** command using an AES key.

**Example**  

```
aws-cloudhsm > key wrap cloudhsm-aes-gcm --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example --tag-length-bits 64 --aad 0x10
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "wrapped_key_data": "6Rn8nkjEriDYlnP3P8nPkYQ8hplOEJ899zsrF+aTB0i/fIlZ"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes

***<AAD>***  
AES GCM Additional Authenticated Data (AAD) value, in hex.   
Required: No

***<TAG\$1LENGTH\$1BITS>***  
AES GCM tag length in bits.  
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with RSA-AES using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-rsa-aes"></a>

Use the **key wrap rsa-aes** command in CloudHSM CLI to wrap a payload key using an RSA public key on the hardware security module (HSM) and the RSA-AES wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

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

To use the **key wrap rsa-aes** command, you must first have an RSA key in your AWS CloudHSM cluster. You can generate an RSA key pair using the [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-rsa-aes-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-rsa-aes-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-rsa-aes-syntax"></a>

```
aws-cloudhsm > help key wrap rsa-aes
Usage: key wrap rsa-aes [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
      --hash-function <HASH_FUNCTION>
          Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512]
      --mgf <MGF>
          Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-rsa-aes-examples"></a>

This example shows how to use the **key wrap rsa-ae** command using an RSA public key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap rsa-aes --payload-filter attr.label=payload-key --wrapping-filter attr.label=rsa-public-key-example --hash-function sha256 --mgf mgf1-sha256
{
  "error_code": 0,
  "data": {
    "payload-key-reference": "0x00000000001c08f1",
    "wrapping-key-reference": "0x00000000007008da",
    "wrapped-key-data": "HrSE1DEyLjIeyGdPa9R+ebiqB5TIJGyamPker31ZebPwRA+NcerbAJO8DJ1lXPygZcI21vIFSZJuWMEiWpe1R9D/5WSYgxLVKex30xCFqebtEzxbKuv4DOmU4meSofqREYvtb3EoIKwjyxCMRQFgoyUCuP4y0f0eSv0k6rSJh4NuCsHptXZbtgNeRcR4botN7LlzkEIUcq4fVHaatCwd0J1QGKHKyRhkol+RL5WGXKe4nAboAkC5GO7veI5yHL1SaKlssSJtTL/CFpbSLsAFuYbv/NUCWwMY5mwyVTCSlw+HlgKK+5TH1MzBaSi8fpfyepLT8sHy2Q/VRl6ifb49p6m0KQFbRVvz/OWUd6l4d97BdgtaEz6ueg=="
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-rsa-aes-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes

***<MGF>***  
Specifies the mask generation function.  
The mask generation function hash function must match the signing mechanism hash function.
Valid values  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-rsa-aes-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with RSA-OAEP using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-rsa-oaep"></a>

Use the **key wrap rsa-oaep** command in CloudHSM CLI to wrap a payload key using an RSA public key on the hardware security module (HSM) and the `RSA-OAEP` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

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

To use the **key wrap rsa-oaep** command, you must first have an RSA key in your AWS CloudHSM cluster. You can generate an RSA key pair using the [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-rsa-aes-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-rsa-aes-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-rsa-aes-syntax"></a>

```
aws-cloudhsm > help key wrap rsa-oaep
Usage: key wrap rsa-oaep [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
      --hash-function <HASH_FUNCTION>
          Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512]
      --mgf <MGF>
          Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-unwrap-rsa-aes-examples"></a>

This example shows how to use the **key wrap rsa-oaep** command using an RSA public key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap rsa-oaep --payload-filter attr.label=payload-key --wrapping-filter attr.label=rsa-public-key-example --hash-function sha256 --mgf mgf1-sha256
{
  "error_code": 0,
  "data": {
    "payload-key-reference": "0x00000000001c08f1",
    "wrapping-key-reference": "0x00000000007008da",
    "wrapped-key-data": "OjJe4msobPLz9TuSAdULEu17T5rMDWtSlLyBSkLbaZnYzzpdrhsbGLbwZJCtB/jGkDNdB4qyTAOQwEpggGf6v+Yx6JcesNeKKNU8XZal/YBoHC8noTGUSDI2qr+u2tDc84NPv6d+F2KOONXsSxMhmxzzNG/gzTVIJhOuy/B1yHjGP4mOXoDZf5+7f5M1CjxBmz4Vva/wrWHGCSG0yOaWblEvOiHAIt3UBdyKmU+/My4xjfJv7WGGu3DFUUIZ06TihRtKQhUYU1M9u6NPf9riJJfHsk6QCuSZ9yWThDT9as6i7e3htnyDhIhGWaoK8JU855cN/YNKAUqkNpC4FPL3iw=="
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-rsa-aes-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes

***<MGF>***  
Specifies the mask generation function.  
The mask generation function hash function must match the signing mechanism hash function.
Valid values  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-rsa-aes-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with RSA-PKCS using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-rsa-pkcs"></a>

Use the **key wrap rsa-pkcs** command in CloudHSM CLI to wrap a payload key using an RSA public key on the hardware security module (HSM) and the `RSA-PKCS` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

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

To use the **key wrap rsa-pkcs** command, you must first have an RSA key in your AWS CloudHSM cluster. You can generate an RSA key pair using the [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-syntax"></a>

```
aws-cloudhsm > help key wrap rsa-pkcs
Usage: key wrap rsa-pkcs [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --payload-filter [<PAYLOAD_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a payload key
      --wrapping-filter [<WRAPPING_FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-examples"></a>

This example shows how to use the **key wrap rsa-pkcs** command using an RSA public key.

**Example**  

```
aws-cloudhsm > key wrap rsa-pkcs --payload-filter attr.label=payload-key --wrapping-filter attr.label=rsa-public-key-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000007008da",
    "wrapped_key_data": "am0Nc7+YE8FWs+5HvU7sIBcXVb24QA0l65nbNAD+1bK+e18BpSfnaI3P+r8Dp+pLu1ofoUy/vtzRjZoCiDofcz4EqCFnGl4GdcJ1/3W/5WRvMatCa2d7cx02swaeZcjKsermPXYRO1lGlfq6NskwMeeTkV8R7Rx9artFrs1y0DdIgIKVaiFHwnBIUMnlQrR2zRmMkfwU1jxMYmOYyD031F5VbnjSrhfMwkww2la7uf/c3XdFJ2+0Bo94c6og/yfPcpOOobJlITCoXhtMRepSdO4OggYq/6nUDuHCtJ86pPGnNahyr7+sAaSI3a5ECQLUjwaIARUCyoRh7EFK3qPXcg=="
  }
```

## Arguments
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a wrapping key.   
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Log in to an HSM using CloudHSM CLI
<a name="cloudhsm_cli-login"></a>

You can use the **login** command in CloudHSM CLI to log in and out of each hardware security (HSM) in a AWS CloudHSM cluster. This command has the following sub-command:
+ [mfa-token-sign](cloudhsm_cli-login-mfa-token-sign.md)

**Note**  
If you exceed five incorrect login attempts, your account is locked out. To unlock the account, an admin must reset your password using the [user change-password](cloudhsm_cli-user-change-password.md) command in cloudhsm\$1cli.

## To troubleshoot login and logout
<a name="troubleshoot-login-logout"></a>

If you have more than one HSM in your cluster, you may be allowed additional incorrect login attempts before your account is locked out. This is because the CloudHSM client balances load across various HSMs. Therefore, the login attempt may not begin on the same HSM each time. If you are testing this functionality, we recommend you do so on a cluster with only one active HSM. 

If you created your cluster before February 2018, your account is locked out after 20 incorrect login attempts. 

## User type
<a name="chsm-cli-login-logout-userType"></a>

The following users can run these commands.
+ Unactivated admin
+ Admin
+ Crypto user (CU)

## Syntax
<a name="chsm-cli-login-syntax"></a>

```
aws-cloudhsm > help login
Login to your cluster  
        
USAGE:
    cloudhsm-cli login [OPTIONS] --username <USERNAME> --role <ROLE> [COMMAND]
    
Commands:
  mfa-token-sign  Login with token-sign mfa
  help            Print this message or the help of the given subcommand(s)

OPTIONS:
        --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

        --username <USERNAME>
            Username to access the Cluster
        
        --role <ROLE>
            Role the user has in the Cluster
            
           Possible values:
           - crypto-user: A CryptoUser has the ability to manage and use keys
           - admin:       An Admin has the ability to manage user accounts

        --password <PASSWORD>
           Optional: Plaintext user's password. If you do not include this argument you will be prompted for it

  -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="chsm-cli-login-example"></a>

**Example**  
This command logs you in to all HSMs in a cluster with the credentials of an admin user named `admin1`.  

```
aws-cloudhsm > login --username admin1 --role admin
Enter password:
{
  "error_code": 0,
  "data": {
    "username": "admin1",
    "role": "admin"
  }
}
```

## Arguments
<a name="login-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<USERNAME>***  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). The username is not case sensitive in this command, username is always displayed in lowercase.  
Required: Yes

***<ROLE>***  
Specifies the role assigned to this user. Valid values are **admin**, **crypto-user**.  
To get the user's role, use the **user list** command. For detailed information about the user types on an HSM, see [Understanding HSM users](manage-hsm-users.md).  
Required: Yes

***<PASSWORD>***  
Specifies the password of the user who is logging in to the HSMs.  
Required: Customers must provide the password either via the `--password` command line argument or omit it to be prompted interactively.  
Using the `--password` argument on the command line may expose credentials in your shell history. Consider prompting the password interactively or clear your shell history after use.

## Related topics
<a name="login-seeAlso"></a>
+ [Getting Started with CloudHSM CLI](cloudhsm_cli-getting-started.md)
+ [Activate the Cluster](activate-cluster.md)

# Log in with MFA to an HSM using CloudHSM CLI
<a name="cloudhsm_cli-login-mfa-token-sign"></a>

Use the **login mfa-token-sign** command in AWS CloudHSM CloudHSM CLI to log in to a hardware security module (HSM) using multi-factor authentication (MFA). To use this command, you must first set up [MFA for CloudHSM CLI](login-mfa-token-sign.md).

## User type
<a name="cloudhsm_cli-login-mfa-token-userType"></a>

The following users can run these commands.
+ Admin
+ Crypto user (CU)

## Syntax
<a name="cloudhsm_cli-login-mfa-token-syntax"></a>

```
aws-cloudhsm > help login mfa-token-sign
Login with token-sign mfa

USAGE:
    login --username <username> --role <role> mfa-token-sign --token <token>

OPTIONS:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --token <TOKEN>            Filepath where the unsigned token file will be written
  -h, --help                     Print help
```

## Example
<a name="cloudhsm_cli-login-mfa-token-example"></a>

**Example**  

```
aws-cloudhsm > login --username test_user --role admin mfa-token-sign --token /home/valid.token
Enter password:
Enter signed token file path (press enter if same as the unsigned token file):
{
  "error_code": 0,
  "data": {
    "username": "test_user",
    "role": "admin"
  }
}
```

## Arguments
<a name="cloudhsm_cli-login-mfa-token-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<TOKEN>***  
Filepath where the unsigned token file will be written.  
Required: Yes

## Related topics
<a name="cloudhsm_cli-login-mfa-token-seeAlso"></a>
+ [Getting Started with CloudHSM CLI](cloudhsm_cli-getting-started.md)
+ [Activate the Cluster](activate-cluster.md)
+ [Using CloudHSM CLI to manage MFA](login-mfa-token-sign.md)

# Log out of an HSM using CloudHSM CLI
<a name="cloudhsm_cli-logout"></a>

Use the **logout** command in CloudHSM CLI to log out of each hardware security module (HSM) in an AWS CloudHSM cluster.

## User type
<a name="chsm-cli-logout-userType"></a>

The following users can run this command.
+ Admin
+ Crypto user (CU)

## Syntax
<a name="chsm-cli-logout-syntax"></a>

```
aws-cloudhsm > help logout
Logout of your cluster

USAGE:
    logout

OPTIONS:
        --cluster-id <CLUSTER_ID> Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
    -h, --help                    Print help information
    -V, --version                 Print version information
```

## Example
<a name="chsm-cli-logout-example"></a>

**Example**  
This command logs you out of all HSMs in a cluster.  

```
aws-cloudhsm > logout
{
  "error_code": 0,
  "data": "Logout successful"
}
```

## Related topics
<a name="logout-seeAlso"></a>
+ [Getting Started with CloudHSM CLI](cloudhsm_cli-getting-started.md)
+ [Activate the Cluster](activate-cluster.md)

# The user category in CloudHSM CLI
<a name="cloudhsm_cli-user"></a>

In the CloudHSM CLI, **user** is a parent category for a group of commands that, when combined with the parent category, create a command specific to users. Currently, the user category consists of the following commands:
+ [user change-mfa](cloudhsm_cli-user-change-mfa.md)
+ [user change-password](cloudhsm_cli-user-change-password.md)
+ [user create](cloudhsm_cli-user-create.md)
+ [user delete](cloudhsm_cli-user-delete.md)
+ [user list](cloudhsm_cli-user-list.md)
+ [user replicate](cloudhsm_cli-user-replicate.md)

# The user change-mfa category in CloudHSM CLI
<a name="cloudhsm_cli-user-change-mfa"></a>

In the CloudHSM CLI, **user change-mfa** is a parent category for a group of commands that, when combined with the parent category, create a command specific to changing multi-factor authentication (MFA) for users.

Currently, this category consists of the following sub-command:
+ [token-sign](cloudhsm_cli-user-change-mfa-token-sign.md)

# Change a user's MFA setup with CloudHSM CLI
<a name="cloudhsm_cli-user-change-mfa-token-sign"></a>

Use the **user change-mfa token-sign** command in CloudHSM CLI to update a user account's multi-factor authentication (MFA) setup. Any user account can run this command. Accounts with the Admin role can run this command for other users.

## User type
<a name="user-change-mfa-type"></a>

The following users can run this command.
+ Admin
+ Crypto user

## Syntax
<a name="user-change-mfa-syntax"></a>

Currently, there is only a single multi-factor strategy available for users: Token Sign.

```
aws-cloudhsm > help user change-mfa
Change a user's Mfa Strategy

Usage:
    user change-mfa <COMMAND>
  
Commands:
  token-sign  Register or Deregister a public key using token-sign mfa strategy
  help        Print this message or the help of the given subcommand(s)
```

The Token Sign strategy asks for a Token file to write unsigned tokens to.

```
aws-cloudhsm > help user change-mfa token-sign
Register or Deregister a public key using token-sign mfa strategy

Usage: user change-mfa token-sign [OPTIONS] --username <USERNAME> --role <ROLE> <--token <TOKEN>|--deregister>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --username <USERNAME>
          Username of the user that will be modified

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --change-password <CHANGE_PASSWORD>
          Optional: Plaintext user's password. If you do not include this argument you will be prompted for it

      --token <TOKEN>
          Filepath where the unsigned token file will be written. Required for enabling MFA for a user

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation

      --deregister
          Deregister the MFA public key, if present

      --change-quorum
          Change the Quorum public key along with the MFA key

  -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="user-change-mfa-examples"></a>

This command will write one unsigned token per HSM in your cluster to the file specified by `token`. When you are prompted, sign the tokens in the file.

**Example : Write one unsigned token per HSM in your cluster**  

```
aws-cloudhsm > user change-mfa token-sign --username cu1 --change-password password --role crypto-user --token /path/myfile
Enter signed token file path (press enter if same as the unsigned token file):
Enter public key PEM file path:/path/mypemfile
{
  "error_code": 0,
  "data": {
    "username": "test_user",
    "role": "admin"
  }
}
```

### Arguments
<a name="user-change-mfa-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<ROLE>***  
Specifies the role given to the user account. This parameter is required. For detailed information about the user types on an HSM, see [Understanding HSM users](manage-hsm-users.md).  
**Valid values**  
+ **Admin**: Admins can manage users, but they cannot manage keys.
+ **Crypto user**: Crypto users can create an manage keys and use keys in cryptographic operations.

***<USERNAME>***  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ).  
You cannot change the name of a user after it is created. In CloudHSM CLI commands, the role and password are case-sensitive, but the username is not.  
**Required**: Yes

***<CHANGE\$1PASSWORD>***  
Specifies the plaintext new password of the user whose MFA is being registered/deregistered.  
**Required**: Yes

***<TOKEN>***  
File path where the unsigned token file will be written.  
**Required**: Yes

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if quorum user service quorum value is greater than 1.

***<DEREGISTER>***  
Deregisters the MFA public key, if present.

***<CHANGE-QUORUM>***  
Changes the quorum public key along with the MFA key.

## Related topics
<a name="user-change-mfa-seealso"></a>
+ [Understanding 2FA for HSM users](login-mfa-token-sign.md)

# Change a user's password with CloudHSM CLI
<a name="cloudhsm_cli-user-change-password"></a>

Use the **user change-password** command in CloudHSM CLI to change the password of an existing user in your AWS CloudHSM cluster. To enable MFA for a user, use the `user change-mfa` command.

Any user can change their own password. In addition, users with the admin role can change the password of another user in the cluster. You do not need to enter the current password to make the change.

**Note**  
You cannot change the password of a user who is currently logged in to the cluster.

## User type
<a name="change-password-user-type"></a>

The following users can run this command.
+ Admin
+ Crypto user (CU)

## Syntax
<a name="change-password-syntax"></a>

**Note**  
 To enable multi-factor authentication (MFA) for a user, use the **user change-mfa** command.

```
aws-cloudhsm > help user change-password
Change a user's password

    Usage:
        cloudhsm-cli user change-password [OPTIONS] --username <USERNAME> --role <ROLE> [--password <PASSWORD>]
    
    Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --username <USERNAME>
          Username of the user that will be modified

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --password <PASSWORD>
          Optional: Plaintext user's password. If you do not include this argument you will be prompted for it

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
          
      --deregister-mfa <DEREGISTER-MFA>
          Deregister the user's mfa public key, if present
          
      --deregister-quorum <DEREGISTER-QUORUM>
          Deregister the user's quorum public key, if present
 -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="change-password-examples"></a>

The following examples show how to use **user change-password** to reset the password for the current user or any other user in your cluster.

**Example : Change your password**  
Any user in the cluster can use **user change-password** to change their own password.  
The following output shows that Bob is currently logged in as a crypto user(CU).  

```
aws-cloudhsm > user change-password --username bob --role crypto-user
Enter password:
Confirm password:
{
  "error_code": 0,
  "data": {
    "username": "bob",
    "role": "crypto-user"
  }
}
```

## Arguments
<a name="change-password-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if quorum user service quorum value is greater than 1.

***<DEREGISTER-MFA>***  
Deregisters the MFA public key, if present.

***<DEREGISTER-QUORUM>***  
Deregister the Quorum public key, if present.

***<PASSWORD>***  
Specifies the plaintext new password of the user. The following characters are not permitted ':'  
**Required**: Yes

***<ROLE>***  
Specifies the role given to the user account. This parameter is required. For detailed information about the user types on an HSM, see [Understanding HSM users](manage-hsm-users.md).  
**Valid values**  
+ **Admin**: Admins can manage users, but they cannot manage keys.
+ **Crypto user**: Crypto users can create an manage keys and use keys in cryptographic operations.

***<USERNAME>***  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ).  
You cannot change the name of a user after it is created. In CloudHSM CLI commands, the role and password are case-sensitive, but the username is not.  
**Required**: Yes

## Related topics
<a name="change-password-seealso"></a>
+ [user list](cloudhsm_cli-user-list.md)
+ [user create](cloudhsm_cli-user-create.md)
+ [user delete](cloudhsm_cli-user-delete.md)

# The user change-quorum category in CloudHSM CLI
<a name="cloudhsm_cli-user-chqm"></a>

In the CloudHSM CLI, **user change-quorum** is a parent category for a group of commands that, when combined with the parent category, create a command specific to changing quorum for users.

**user change-quorum** is used to register user quorum authentication using a specified quorum strategy. As of SDK 5.8.0, there is only a single quorum strategy available for users as shown below.

Currently, this category consists of the following category and sub-command:
+ [token-sign](cloudhsm_cli-user-chqm-token.md)
  + [register](cloudhsm_cli-user-chqm-token-reg.md)

# The user change-quorum token-sign category in CloudHSM CLI
<a name="cloudhsm_cli-user-chqm-token"></a>

In the CloudHSM CLI, **user change-quorum token-sign** is a parent category for commands that, when combined with this parent category, create a command specific to token-sign quorum operations.

Currently, the this category consists of the following commands:
+ [register](cloudhsm_cli-user-chqm-token-reg.md)

# Register a user's token-sign quorum strategy using CloudHSM CLI
<a name="cloudhsm_cli-user-chqm-token-reg"></a>

Use the **user change-quorum token-sign register** command in CloudHSM CLI to register the token-sign quorum strategy for an admin user.

## User type
<a name="token-register-user-type"></a>

The following users can run this command.
+ Admin

## Syntax
<a name="token-register-syntax"></a>

```
aws-cloudhsm > help user change-quorum token-sign register
Register a user for quorum authentication with a public key

Usage: user change-quorum token-sign register --public-key <PUBLIC_KEY> --signed-token <SIGNED_TOKEN>

Options:
      --cluster-id <CLUSTER_ID>      Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --public-key <PUBLIC_KEY>      Filepath to public key PEM file
      --signed-token <SIGNED_TOKEN>  Filepath with token signed by user private key
  -h, --help Print help (see a summary with '-h')
```

## Example
<a name="token-register-examples"></a>

**Example**  
To run this command you will need to be logged in as the user you wish to **register quorum token-sign** for.  

```
aws-cloudhsm > login --username admin1 --role admin
Enter password:
{
  "error_code": 0,
  "data": {
    "username": "admin1",
    "role": "admin"
  }
}
```
The **user change-quorum token-sign register** command will register your public key with the HSM. As a result, it will qualify you as a quorum approver for quorum-required operations that need a user to obtain quorum signatures to meet the necessary quorum value threshold.  

```
aws-cloudhsm > user change-quorum token-sign register \
    --public-key /home/mypemfile \
    --signed-token /home/mysignedtoken
{
  "error_code": 0,
  "data": {
    "username": "admin1",
    "role": "admin"
  }
}
```
You can now run the **user list** command and confirm that quorum token-sign has been registered for this user.  

```
aws-cloudhsm > user list
{
  "error_code": 0,
  "data": {
    "users": [
      {
        "username": "admin",
        "role": "admin",
        "locked": "false",
        "mfa": [],
        "quorum": [],
        "cluster-coverage": "full"
      },
      {
        "username": "admin1",
        "role": "admin",
        "locked": "false",
        "mfa": [],
        "quorum": [
          {        
            "strategy": "token-sign",
            "status": "enabled"
          }
        ],
        "cluster-coverage": "full"
      }
    ]
  }
}
```

## Arguments
<a name="token-register-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PUBLIC-KEY>***  
Filepath to the public key PEM file.  
**Required**: Yes

***<SIGNED-TOKEN>***  
Filepath with token signed by user private key.  
**Required**: Yes

## Related topics
<a name="token-register-seealso"></a>
+ [Using CloudHSM CLI to manage quorum authentication](quorum-auth-chsm-cli.md)
+ [Using quorum authentication for admins: first time setup](quorum-auth-chsm-cli-first-time.md)
+ [Change the quorum minimum value for admins](quorum-auth-chsm-cli-min-value.md)
+ [Service names and types that support quorum authentication](quorum-auth-chsm-cli-service-names.md)

# Create an AWS CloudHSM user with CloudHSM CLI
<a name="cloudhsm_cli-user-create"></a>

The **user create** command in CloudHSM CLI creates a user in your AWS CloudHSM cluster. Only user accounts with the admin role can run this command.

## User type
<a name="user-create-userType"></a>

The following types of users can run this command.
+ Admin

## Requirements
<a name="user-create-requirements"></a>

To run this command, you must be logged in as an admin user

## Syntax
<a name="user-create-syntax"></a>

```
aws-cloudhsm > help user create
Create a new user

Usage: cloudhsm-cli user create [OPTIONS] --username <USERNAME> --role <ROLE> [--password <PASSWORD>]

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --username <USERNAME>
          Username to access the HSM cluster

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --password <PASSWORD>
          Optional: Plaintext user's password. If you do not include this argument you will be prompted for it

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation

  -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="user-create-examples"></a>

These examples show how to use **user create** to create new users in your HSMs.

**Example : Create a crypto user**  
This example creates an account in your AWS CloudHSM cluster with the crypto user role.  

```
aws-cloudhsm > user create --username alice --role crypto-user
Enter password:
Confirm password:
{
  "error_code": 0,
  "data": {
    "username": "alice",
    "role": "crypto-user"
  }
}
```

## Arguments
<a name="user-create-arguments"></a>

*<CLUSTER\$1ID>*  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

*<USERNAME>*  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). The username is not case sensitive in this command, username is always displayed in lowercase.  
Required: Yes

*<ROLE>*  
Specifies the role assigned to this user. This parameter is required. Valid values are **admin**, **crypto-user**.  
To get the user’s role, use the **user list** command. For detailed information about the user types on an HSM, see [Understanding HSM users](manage-hsm-users.md).

*<PASSWORD>*  
Specifies the password of the user who is logging in to the HSMs. The following characters are not permitted ':'  
Required: Yes

*<APPROVAL>*  
Specifies the file path to a signed quorum token file to approve operation. Only required if quorum user service quorum value is greater than 1.

## Related topics
<a name="user-create-seealso"></a>
+ [user list](cloudhsm_cli-user-list.md)
+ [user delete](cloudhsm_cli-user-delete.md)
+ [user change-password](cloudhsm_cli-user-change-password.md)

# Delete an AWS CloudHSM user with CloudHSM CLI
<a name="cloudhsm_cli-user-delete"></a>

The **user delete** command in CloudHSM CLI deletes a user from your AWS CloudHSM cluster. Only user accounts with the admin role may run this command. You cannot delete a user who is currently logged into an HSM. 

## User type
<a name="user-delete-userType"></a>

The following types of users can run this command.
+ Admin

## Requirements
<a name="user-delete-requirements"></a>
+ You can't delete user accounts that own keys.
+ Your user account must have the admin role to run this command.

## Syntax
<a name="user-delete-syntax"></a>

Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram.

```
aws-cloudhsm > help user delete
Delete a user

Usage: user delete [OPTIONS] --username <USERNAME> --role <ROLE>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --username <USERNAME>
          Username to access the HSM cluster

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
```

## Example
<a name="user-delete-examples"></a>

```
aws-cloudhsm > user delete --username alice --role crypto-user
{
  "error_code": 0,
  "data": {
    "username": "alice",
    "role": "crypto-user"
  }
}
```

## Arguments
<a name="user-delete-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<USERNAME>***  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). The username is not case sensitive in this command, username is always displayed in lowercase.  
Required: Yes

***<ROLE>***  
Specifies the role assigned to this user. This parameter is required. Valid values are **admin**, **crypto-user**.  
To get the user’s role, use the **user list** command. For detailed information about the user types on an HSM, see [Understanding HSM users](manage-hsm-users.md).  
Required: Yes

***<APPROVAL>***  
Specifies the file path to a signed quorum token file to approve operation. Only required if quorum user service quorum value is greater than 1.  
Required: Yes

## Related topics
<a name="user-delete-seealso"></a>
+ [user list](cloudhsm_cli-user-list.md)
+ [user create](cloudhsm_cli-user-create.md)
+ [user change-password](cloudhsm_cli-user-change-password.md)

# List all AWS CloudHSM users with CloudHSM CLI
<a name="cloudhsm_cli-user-list"></a>

The **user list** command in the CloudHSM CLI lists the user accounts present in your AWS CloudHSM cluster. You do not need to be logged in to CloudHSM CLI to run this command.

**Note**  
If you add or delete HSMs, update the configuration files that the AWS CloudHSM client and the command line tools use. Otherwise, the changes that you make might not be effective on all HSMs in the cluster.

## User type
<a name="user-list-userType"></a>

The following types of users can run this command.
+ All users. You do not need to be logged in to run this command.

## Syntax
<a name="chsm-cli-user-list-syntax"></a>

```
aws-cloudhsm > help user list
List the users in your cluster

USAGE:
    user list

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
  -h, --help                     Print help
```

## Example
<a name="chsm-cli-user-list-examples"></a>

This command lists the users present in your CloudHSM cluster.

```
aws-cloudhsm > user list
{
  "error_code": 0,
  "data": {
    "users": [
      {
        "username": "admin",
        "role": "admin",
        "locked": "false",
        "mfa": [],
        "cluster-coverage": "full"
      },
      {
        "username": "test_user",
        "role": "admin",
        "locked": "false",
        "mfa": [
          {
            "strategy": "token-sign",
            "status": "enabled"
          }
        ],
        "cluster-coverage": "full"
      },
      {
        "username": "app_user",
        "role": "internal(APPLIANCE_USER)",
        "locked": "false",
        "mfa": [],
        "cluster-coverage": "full"
      }
    ]
  }
}
```

The output includes the following user attributes:
+ **Username**: Displays the user-defined friendly name for the user. Username is always displayed in lowercase. 
+ **Role**: Determines the operations that the user can perform on the HSM.
+ **Locked**: Indicates whether this user account has been locked out.
+ **MFA**: Indicates the supported multi-factor authentication mechanisms for this user account.
+ **Cluster coverage**: Indicates the cluster-wide availability of this user account.

## Related topics
<a name="chsm-user-list-seealso"></a>
+ [listUsers](key_mgmt_util-listUsers.md) in key\$1mgmt\$1util
+ [user create](cloudhsm_cli-user-create.md)
+ [user delete](cloudhsm_cli-user-delete.md)
+ [user change-password](cloudhsm_cli-user-change-password.md)

# Replicate a user with CloudHSM CLI
<a name="cloudhsm_cli-user-replicate"></a>

Use the **user replicate** command in CloudHSM CLI to replicate a user from a source AWS CloudHSM cluster to a destination AWS CloudHSM cluster.

## User type
<a name="chsm-cli-user-replicate-user-type"></a>

The following types of users can run this command.
+ Admins (COs)

## Requirements
<a name="cloudhsm_cli-user-replicate-requirements"></a>
+ The source and destination clusters must be clones. This means one was created from a backup of the other, or they were both created from a common backup. See [Creating clusters from backups](create-cluster-from-backup.md) for more information.
+ To run this command, you must be logged in as an admin on both the source and destination clusters.
  +  In single command mode, the command will use the CLOUDHSM\$1PIN and CLOUDHSM\$1ROLE environmental variables to authenticate on the source cluster. See [Single Command mode](cloudhsm_cli-modes.md#cloudhsm_cli-mode-single-command) for more information. To provide credentials for the destination cluster, you need to set two additional environmental variables: DESTINATION\$1CLOUDHSM\$1PIN and DESTINATION\$1CLOUDHSM\$1ROLE:

    ```
    $ export DESTINATION_CLOUDHSM_ROLE=<role>
    ```

    ```
    $ export DESTINATION_CLOUDHSM_PIN=<username:password>
    ```
  +  In interactive mode, users will need to explicitly log into both the source and destination clusters.

## Syntax
<a name="chsm-cli-user-replicate-syntax"></a>

```
aws-cloudhsm > help user replicate
Replicate a user from a source to a destination cluster

Usage: user replicate --username <USERNAME> --role <ROLE> --source-cluster-id <SOURCE_CLUSTER_ID> --destination-cluster-id <DESTINATION_CLUSTER_ID>

Options:
      --username <USERNAME>
          Username of the user to replicate

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --source-cluster-id <SOURCE_CLUSTER_ID>
          Source cluster ID

      --destination-cluster-id <DESTINATION_CLUSTER_ID>
          Destination cluster ID

  -h, --help
          Print help (see a summary with '-h')
```

## Examples
<a name="chsm-cli-user-replicate-examples"></a>

**Example: Replicate user**  
This command replicates a user from a source cluster with to a cloned destination cluster. The example below demonstrates the output when logged in as an admin on both clusters.  

```
admin-user@cluster-1234abcdefg > user replicate \
      --username example-admin \
      --role admin \
      --source-cluster-id cluster-1234abcdefg \
      --destination-cluster-id cluster-2345bcdefgh
{
  "error_code": 0,
  "data": {
    "user": {
      "username": "example-admin",
      "role": "admin",
      "locked": "false",
      "mfa": [],
      "quorum": [],
      "cluster-coverage": "full"
    },
    "message": "Successfully replicated user"
  }
}
```

## Arguments
<a name="user-replicate-arguments"></a>

***<USERNAME>***  
Specifies the username of the user to replicate in the source cluster.  
Required: Yes

***<ROLE>***  
Specifies the role assigned to this user. This parameter is required. Valid values are **admin**, **crypto-user**.  
To get the user’s role, use the **user list** command. For detailed information about the user types on an HSM, see [Understanding HSM users](manage-hsm-users.md).  
Required: Yes

***<SOURCE\$1CLUSTER\$1ID>***  
The source cluster ID.  
Required: Yes

***<DESTINATION\$1CLUSTER\$1ID>***  
The destination cluster ID.  
Required: Yes

## Related topics
<a name="chsm-user-replicate-seealso"></a>
+ [Connecting to multiple clusters with CloudHSM CLI](cloudhsm_cli-configs-multi-cluster.md)

# The quorum category in CloudHSM CLI
<a name="cloudhsm_cli-qm"></a>

In the CloudHSM CLI, **quorum** is a parent category for a group of commands that, when combined with **quorum**, creates a command specific to quorum authentication, or M of N operations. Currently, this category consists of the **token-sign** sub-category which consists of its own commands. Click the link below for details.
+ [token-sign](cloudhsm_cli-qm-token.md)

**Admin Services**: Quorum authentication is used for admin privileged services like creating users, deleting users, changing user passwords, setting quorum values, and deactivating quorum and MFA capabilities.

**Crypto User Services**: Quorum authentication is used for crypto-user privileged services associated with a specific key like signing with a key, sharing/unsharing a key, wrapping/unwrapping a key, and setting a key's attribute. The quorum value of an associated key is configured when the key is generated, imported, or unwrapped. The quorum value must be equal to or less than the number of users that the key is associated with, which includes users that the key is shared with and the key owner.

Each service type is further broken down into a qualifying service name, which contains a specific set of quorum supported service operations that can be performed.


****  

| Service name | Service type | Service operations | 
| --- | --- | --- | 
| user | Admin |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm.html)  | 
| quorum | Admin |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm.html)  | 
| cluster1 | Admin |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm.html)  | 
| key-management | Crypto User |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm.html)  | 
| key-usage | Crypto User |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm.html)  | 

[1] Cluster service is exclusively available on hsm2m.medium

## Related topics
<a name="cloudhsm_cli-qm-seealso"></a>
+ [Set up quorum authentication for AWS CloudHSM admins using CloudHSM CLI](quorum-auth-chsm-cli-first-time.md)
+ [Manage quorum authentication (M of N access control) using CloudHSM CLI](quorum-auth-chsm-cli.md)

# The quorum token-sign category in CloudHSM CLI
<a name="cloudhsm_cli-qm-token"></a>

In the CloudHSM CLI, **quorum token-sign** is a category for a group of commands that, when combined with **quorum token-sign**, create a command specific to quorum authentication, or M of N operations.

Currently, this category consists of the following commands:
+ [delete](cloudhsm_cli-qm-token-del.md)
+ [generate](cloudhsm_cli-qm-token-gen.md)
+ [list](cloudhsm_cli-qm-token-list.md)
+ [list-quorum-values](cloudhsm_cli-qm-token-list-qm.md)
+ [set-quorum-value](cloudhsm_cli-qm-token-set-qm.md)

# Delete quorum tokens using CloudHSM CLI
<a name="cloudhsm_cli-qm-token-del"></a>

Use the **quorum token-sign delete** command in CloudHSM CLI to delete one or more tokens for a quorum authorized service.

## User type
<a name="quorum-token-delete-user-type"></a>

The following users can run this command.
+ Admin

## Syntax
<a name="quorum-token-delete-syntax"></a>

```
aws-cloudhsm > help quorum token-sign delete 
Delete one or more Quorum Tokens

Usage: quorum token-sign delete --scope <SCOPE>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --scope <SCOPE>
          Scope of which token(s) will be deleted

          Possible values:
          - user: Deletes all token(s) of currently logged in user
          - all:  Deletes all token(s) on the HSM
  -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="quorum-token-delete-examples"></a>

The following example shows how the **quorum token-sign delete** command in CloudHSM CLI can be used to delete one or more tokens for a quorum authorized service.

**Example : Delete one or more tokens for a quorum authorized service**  

```
aws-cloudhsm > quorum token-sign delete --scope all
{
  "error_code": 0,
  "data": "Deletion of quorum token(s) successful"
}
```

## Arguments
<a name="quorum-token-delete-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<SCOPE>***  
The scope in which token(s) will be deleted in the AWS CloudHSM cluster.  
**Valid values**  
+ **User**: Used to delete only tokens owned by the logged in user.
+ **All**: Used to delete all tokens in the AWS CloudHSM cluster.

## Related topics
<a name="quorum-token-delete-seealso"></a>
+ [user list](cloudhsm_cli-user-list.md)
+ [user create](cloudhsm_cli-user-create.md)
+ [user delete](cloudhsm_cli-user-delete.md)

# Generate a quorum token using CloudHSM CLI
<a name="cloudhsm_cli-qm-token-gen"></a>

Use the **quorum token-sign generate** command in CloudHSM CLI to generate a token for a quorum authorized service.

There is a limit to obtaining one active token per user per service on an HSM cluster for services user and quorum. This limit does not apply to tokens related to key services.

**Note**  
Only Admins and Crypto Users may generate specific service tokens. For more information about service types and names, see [Service names and types that support quorum authentication](quorum-auth-chsm-cli-service-names.md)

**Admin Services**: Quorum authentication is used for admin privileged services like creating users, deleting users, changing user passwords, setting quorum values, and deactivating quorum and MFA capabilities.

**Crypto User Services**: Quorum authentication is used for crypto-user privileged services associated with a specific key like signing with a key, sharing/unsharing a key, wrapping/unwrapping a key, and setting a key's attribute. The quorum value of an associated key is configured when the key is generated, imported, or unwrapped. The quorum value must be equal to or less than the number of users that the key is associated with, which includes users that the key is shared with and the key owner.

Each service type is further broken down into a qualifying service name, which contains a specific set of quorum supported service operations that can be performed.


****  

| Service name | Service type | Service operations | 
| --- | --- | --- | 
| user | Admin |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm-token-gen.html)  | 
| quorum | Admin |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm-token-gen.html)  | 
| cluster1 | Admin |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm-token-gen.html)  | 
| key-management | Crypto User |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm-token-gen.html)  | 
| key-usage | Crypto User |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-qm-token-gen.html)  | 

[1] Cluster service is exclusively available on hsm2m.medium

## User type
<a name="quorum-token-generate-user-type"></a>

The following users can run this command.
+ Admin
+ Crypto user (CU)

## Syntax
<a name="quorum-token-generate-syntax"></a>

```
aws-cloudhsm > help quorum token-sign generate
Generate a token

Usage: quorum token-sign generate --service <SERVICE> --token <TOKEN>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --service <SERVICE>
          Service the token will be used for

          Possible values:
          - user:
            User management service is used for executing quorum authenticated user management operations
          - quorum:
            Quorum management service is used for setting quorum values for any quorum service
          - cluster: 
            Cluster management service is used for executing quorum for cluster wide configuration managements like mtls enforcement, mtls registration and mtls deregistration
          - registration:
            Registration service is used for registering a public key for quorum authentication
          - key-usage:
            Key usage service is used for executing quorum authenticated key usage operations
          - key-management:
            Key management service is used for executing quorum authenticated key management operations

      --token <TOKEN>
          Filepath where the unsigned token file will be written
  -h, --help                     Print help
```

## Example
<a name="quorum-token-generate-examples"></a>

This command will write one unsigned token per HSM in your cluster to the file specified by `token`.

**Example : Write one unsigned token per HSM in your cluster**  

```
aws-cloudhsm > quorum token-sign generate --service user --token /home/tfile
{
  "error_code": 0,
  "data": {
    "filepath": "/home/tfile"
  }
}
```

## Arguments
<a name="quorum-token-generate-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<SERVICE>***  
Specifies the quorum authorized service for which to generate a token. This parameter is required.  
**Valid values**  
+ **user**: The user management service that is used for executing quorum authorized user management operations.
+ **quorum**: The quorum management service that is used for setting quorum authorized quorum values for any quorum authorized service.
+ **cluster**: The cluster management service that is used for executing quorum for cluster wide configuration managements like mtls enforcement, mtls registration and mtls deregistration.
+ **registration**: Generates an unsigned token for use in registering a public key for quorum authorization.
+ **key-usage**: Generates an unsigned token that is used for executing quorum authorized key usage operations.
+ **key-management**: Generates an unsigned token that is used for executing quorum authorized key management operations.
**Required**: Yes

***<TOKEN>***  
Filepath where the unsigned token file will be written.  
**Required**: Yes

## Related topics
<a name="quorum-token-generate-seealso"></a>
+ [Service names and types that support quorum authentication](quorum-auth-chsm-cli-service-names.md)

# List quorum tokens using CloudHSM CLI
<a name="cloudhsm_cli-qm-token-list"></a>

Use the **quorum token-sign list** command in CloudHSM CLI to list all token-sign quorum tokens present in your AWS CloudHSM cluster. This includes tokens generated by other users. A token is bound to a user, so while you may see tokens from other users, you will only be able to use tokens associated with the currently logged in user.

For more information about service types and names, see [Service names and types that support quorum authentication.](quorum-auth-chsm-cli-service-names.md) For more information about the content displayed from listed tokens, see [Key management and usage with quorum authentication enabled for AWS CloudHSM using CloudHSM CLI](key-quorum-auth-chsm-cli-crypto-user.md) for tokens associated with `key-management` and `key-usage` services, and see [User management with quorum authentication enabled for AWS CloudHSM using CloudHSM CLI](quorum-auth-chsm-cli-admin.md) for tokens associated with `user`, `quorum`, or `cluster` service, respectively.

## User type
<a name="quorum-token-list-user-type"></a>

The following users can run this command.
+ Admin
+ Crypto user (CU)

## Syntax
<a name="quorum-token-list-syntax"></a>

```
aws-cloudhsm > help quorum token-sign list
List the token-sign tokens in your cluster

Usage: quorum token-sign list

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
  -h, --help                     Print help
```

## Example
<a name="quorum-token-list-examples"></a>

This command will list all token-sign tokens present in your AWS CloudHSM cluster. This includes tokens generated by other users. A token is bound to a user, so while you may see tokens from other users, you will only be able to use tokens associated with the currently logged in user.

**Example**  

```
aws-cloudhsm > quorum token-sign list
{
  "error_code": 0,
  "data": {
    "tokens": [
      {
        "username": "admin",
        "service": "quorum",
        "approvals-required": 2,
        "number-of-approvals": 0,
        "token-timeout-seconds": 397,
        "cluster-coverage": "full"
      },
      {
        "username": "admin",
        "service": "user",
        "approvals-required": 2,
        "number-of-approvals": 0,
        "token-timeout-seconds": 588,
        "cluster-coverage": "full"
      },
      {
        "username": "crypto_user1",
        "service": "key-management",
        "key-reference": "0x00000000002c33f7",
        "minimum-token-count": 1
      },
      {
        "username": "crypto_user1",
        "service": "key-usage",
        "key-reference": "0x00000000002c33f7",
        "minimum-token-count": 1
      }
    ]
  }
}
```

## Related topics
<a name="quorum-token-list-seealso"></a>
+ [quorum token-sign generate](cloudhsm_cli-qm-token-gen.md)

# Show quorum values using CloudHSM CLI
<a name="cloudhsm_cli-qm-token-list-qm"></a>

Use the **quorum token-sign list-quorum-values** command in CloudHSM CLI to lists the quorum values set in your AWS CloudHSM cluster.

## User type
<a name="quorum-token-list-qm-user-type"></a>

The following users can run this command.
+ All users. You do not need to be logged in to run this command.

## Syntax
<a name="quorum-token-list-qm-syntax"></a>

```
aws-cloudhsm > help quorum token-sign list-quorum-values
List current quorum values

Usage: quorum token-sign list-quorum-values

Options:
      --cluster-id <CLUSTER_ID>  Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
  -h, --help                     Print help
```

## Example
<a name="quorum-token-list-qm-examples"></a>

This command lists quorum values set in your AWS CloudHSM cluster for each service.

**Example**  
**hsm1.medium**:  

```
aws-cloudhsm > quorum token-sign list-quorum-values
{
  "error_code": 0,
  "data": {
    "user": 1,
    "quorum": 1
  }
}
```
**hsm2m.medium**:  

```
aws-cloudhsm > quorum token-sign list-quorum-values
{
  "error_code": 0,
  "data": {
    "user": 1,
    "quorum": 1,
    "cluster": 1
  }
}
```

## Related topics
<a name="quorum-token-list-qm-seealso"></a>
+ [Service names and types that support quorum authentication](quorum-auth-chsm-cli-service-names.md)
+  [Setup mTLS (recommended)](getting-started-setup-mtls.md) 

# Update a quorum value using CloudHSM CLI
<a name="cloudhsm_cli-qm-token-set-qm"></a>

Use the **quorum token-sign set-quorum-value** command in CloudHSM CLI to set a new quorum value for a quorum authorized service.

## User type
<a name="quorum-token-set-qm-user-type"></a>

The following users can run this command.
+ Admin

## Syntax
<a name="quorum-token-set-qm-syntax"></a>

```
aws-cloudhsm > help quorum token-sign set-quorum-value
Set a quorum value

Usage: quorum token-sign set-quorum-value [OPTIONS] --service <SERVICE> --value <VALUE>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error

      --service <SERVICE>
          Service the token will be used for

          Possible values:
          - user:
            User management service is used for executing quorum authenticated user management operations
          - quorum:
            Quorum management service is used for setting quorum values for any quorum service
          - cluster: 
            Cluster management service is used for executing quorum for cluster wide configuration managements like mtls enforcement, mtls registration and mtls deregistration

      --value <VALUE>
          Value to set for service

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation

  -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="quorum-token-set-qm-examples"></a>

**Example**  
In the following example, this command writes one unsigned token per HSM in your cluster to the file specified by token. When you are prompted, sign the tokens in the file.  

```
aws-cloudhsm > quorum token-sign set-quorum-value --service quorum --value 2
{
  "error_code": 0,
  "data": "Set Quorum Value successful"
}
```
You can then run the **list-quorum-values** command to confirm that the quorum value for the quorum management service has been set:  
**hsm1.medium**:  

```
aws-cloudhsm > quorum token-sign list-quorum-values
{
  "error_code": 0,
  "data": {
    "user": 1,
    "quorum": 2
  }
}
```
**hsm2m.medium**:  

```
aws-cloudhsm > quorum token-sign list-quorum-values
{
  "error_code": 0,
  "data": {
    "user": 1,
    "quorum": 2,
    "cluster": 1
  }
}
```

## Arguments
<a name="quorum-token-set-qm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<APPROVAL>***  
The filepath of the signed token file to be approved on the HSM.

***<SERVICE>***  
Specifies the quorum authorized service for which to generate a token. This parameter is required. For more information about service types and names, see [Service names and types that support quorum authentication](quorum-auth-chsm-cli-service-names.md).  
**Valid values**  
+ **user**: The user management service. Service used for executing quorum authorized user management operations.
+ **quorum**: The quorum management service. Service used for setting a quorum authorized quorum values for any quorum authorized service.
+ **cluster**: The cluster management service that is used for executing quorum for cluster wide configuration managements like mtls enforcement, mtls registration and mtls deregistration.
+ **registration**: Generates a unsigned token for use in registering a public key for quorum authorization.
**Required**: Yes

***<VALUE>***  
Specifies The quorum value to be set. The maximum quorum value is eight (8).  
**Require**: Yes

## Related topics
<a name="quorum-token-set-qm-seealso"></a>
+ [quorum token-sign list-quorum-values](cloudhsm_cli-qm-token-list-qm.md)
+ [Service names and types that support quorum authentication](quorum-auth-chsm-cli-service-names.md)
+ [Setup mTLS (recommended)](getting-started-setup-mtls.md)