# AWS CloudHSM command line tools In addition to the AWS Command Line Interface (AWS CLI) that you use for managing your AWS resources, AWS CloudHSM offers command-line tools for creating and managing hardware security module (HSM) users and keys on your HSMs. In AWS CloudHSM, you use the familiar CLI to manage your cluster, and the CloudHSM command-line tools to manage your HSM. These are the various command-line tools: **To manage HSMs and clusters** [CloudHSMv2 commands in AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/index.html) and [HSM2 PowerShell cmdlets in the AWSPowerShell module](https://aws.amazon.com/powershell/) + These tools get, create, delete, and tag AWS CloudHSM clusters and HSMs: + To use the commands in [CloudHSMv2 commands in CLI](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/index.html), you need to [install](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) and [configure](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-quick-configuration) AWS CLI. + [HSM2 PowerShell cmdlets in the AWSPowerShell module](https://aws.amazon.com/powershell/) are available in a Windows PowerShell module and a cross-platform PowerShell Core module. **To manage HSM users** [CloudHSM CLI](cloudhsm_cli.md) + Use [CloudHSM CLI](cloudhsm_cli.md) to create users, delete users, list users, change user passwords, and update user multi-factor authentication (MFA). It is not included in the AWS CloudHSM client software. For guidance on installing this tool, see [Install and configure CloudHSM CLI](gs_cloudhsm_cli-install.md). **Helper Tools** Two tools help you to use AWS CloudHSM tools and software libraries: + The [configure tool](configure-tool.md) updates your CloudHSM client configuration files. This allows AWS CloudHSM to synchronize the HSMs in a cluster. AWS CloudHSM offers two major versions, and Client SDK 5 is the latest. It offers a variety of advantages over Client SDK 3 (the previous series). + [pkpspeed](troubleshooting-verify-hsm-performance.md) measures the performance of your HSM hardware independent of software libraries. **Tools for previous SDKs** Use the key management tool (KMU) create, delete, import, and export symmetric keys and asymmetric key pairs: + [key\$1mgmt\$1util](key_mgmt_util.md). This tool is included in the AWS CloudHSM client software. Use the CloudHSM management tool (CMU) to create and delete HSM users, including implementing quorum authentication of user management tasks + [cloudhsm\$1mgmt\$1util](cloudhsm_mgmt_util.md). This tool is included in the AWS CloudHSM client software. The following topics further describe the command-line tools available for managing and using AWS CloudHSM. **Topics** + [AWS CloudHSM configure tool](configure-tool.md) + [AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli.md) + [AWS CloudHSM Management Utility (CMU)](cloudhsm_mgmt_util.md) + [AWS CloudHSM Key Management Utility (KMU)](key_mgmt_util.md) # AWS CloudHSM configure tool AWS CloudHSM automatically synchronizes data among all hardware security modules (HSM) in a cluster. The **configure** tool updates the HSM data in the configuration files that the synchronization mechanisms use. Use **configure** to refresh the HSM data before you use the command line tools, especially when the HSMs in the cluster have changed. AWS CloudHSM includes two major Client SDK versions: + Client SDK 5: This is our latest and default Client SDK. For information on the benefits and advantages it provides, see [Benefits of AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md). + Client SDK 3: This is our older Client SDK. It includes a full set of components for platform and language-based applications compatibility and management tools. For instructions on migrating from Client SDK 3 to Client SDK 5, see [Migrating from AWS CloudHSM Client SDK 3 to Client SDK 5](client-sdk-migration.md). **Topics** + [Client SDK 5 configure tool](configure-sdk-5.md) + [Client SDK 3 configure tool](configure-sdk-3.md) # AWS CloudHSM Client SDK 5 configure tool Use the AWS CloudHSM Client SDK 5 configure tool to update client-side configuration files. Each component in Client SDK 5 includes a configure tool with a designator of the component in the file name of the configure tool. For example, the PKCS \$111 library for Client SDK 5 includes a configure tool named `configure-pkcs11` on Linux or `configure-pkcs11.exe` on Windows. **Topics** + [Syntax](configure-tool-syntax5.md) + [Parameters](configure-tool-params5.md) + [Examples](configure-tool-examples5.md) + [Bootstrap OpenSSL Provider](configure-openssl-provider.md) + [Advanced configurations](configure-sdk5-advanced-configs.md) + [Related topics](configure-tool-seealso5.md) # AWS CloudHSM Client SDK 5 configuration syntax The following table illustrates the syntax for AWS CloudHSM configuration files for Client SDK 5. For more information about the parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). ------ #### [ PKCS \$111 ] ``` Usage: configure-pkcs11[ .exe ] [OPTIONS] Options: --disable-certificate-storage Disables Certificate Storage --enable-certificate-storage Enables Certificate Storage -a ... The address of the HSM instance --cluster-id The id of the cluster containing the HSM instance(s) --disable-key-availability-check Disables key availability check during key use --enable-key-availability-check Enables key availability check during key use --disable-validate-key-at-init Disables parameter validation during initialization of crypto operations --enable-validate-key-at-init Enables parameter validation during initialization of crypto operations --endpoint Specify the AWS CloudHSM API Endpoint --region The region of the cluster --hsm-ca-cert The HSM CA certificate file --log-type The log type [possible values: term, file] --log-file The log file --log-level The logging level [possible values: error, warn, info, debug, trace] --log-rotation The log rotation interval [possible values: never, hourly, daily] --default-retry-mode The default method of retry to use for certain non-terminal failures [possible values: off, standard] --client-cert-hsm-tls-file The client certificate used for TLS client-hsm mutual authentication --client-key-hsm-tls-file The client private key used for TLS client-hsm mutual authentication -h, --help Print help ``` ------ #### [ OpenSSL ] ``` Usage: configure-dyn[ .exe ] [OPTIONS] Options: -a ... The address of the HSM instance --cluster-id The id of the cluster containing the HSM instance(s) --disable-key-availability-check Disables key availability check during key use --enable-key-availability-check Enables key availability check during key use --disable-validate-key-at-init Disables parameter validation during initialization of crypto operations --enable-validate-key-at-init Enables parameter validation during initialization of crypto operations --endpoint Specify the AWS CloudHSM API Endpoint --region The region of the cluster --hsm-ca-cert The HSM CA certificate file --log-type The log type [possible values: term, file] --log-file The log file --log-level The logging level [possible values: error, warn, info, debug, trace] --log-rotation The log rotation interval [possible values: never, hourly, daily] --default-retry-mode The default method of retry to use for certain non-terminal failures [possible values: off, standard] --client-cert-hsm-tls-file The client certificate used for TLS client-hsm mutual authentication --client-key-hsm-tls-file The client private key used for TLS client-hsm mutual authentication -h, --help Print help ``` ------ #### [ KSP ] ``` Usage: configure-ksp.exe [OPTIONS] Options: -a ... The address of the HSM instance --server-client-cert-file The client certificate used for TLS client-server mutual authentication --server-client-key-file The client private key used for TLS client-server mutual authentication --cluster-id The id of the cluster containing the HSM instance(s) --disable-key-availability-check Disables key availability check during key use --enable-key-availability-check Enables key availability check during key use --disable-validate-key-at-init Disables parameter validation during initialization of crypto operations --enable-validate-key-at-init Enables parameter validation during initialization of crypto operations --endpoint Specify the AWS CloudHSM API Endpoint --region The region of the cluster --hsm-ca-cert The HSM CA certificate file --log-type The log type [possible values: term, file] --log-file The log file --log-level The logging level [possible values: error, warn, info, debug, trace] --log-rotation The log rotation interval [possible values: never, hourly, daily] --default-retry-mode The default method of retry to use for certain non-terminal failures [possible values: off, standard] --client-cert-hsm-tls-file The client certificate used for TLS client-hsm mutual authentication --client-key-hsm-tls-file The client private key used for TLS client-hsm mutual authentication --enable-sdk3-compatibility-mode Enables key file usage for KSP --disable-sdk3-compatibility-mode Disables key file usage for KSP -h, --help Print help ``` ------ #### [ JCE ] ``` Usage: configure-jce[ .exe ] [OPTIONS] Options: -a ... The address of the HSM instance --cluster-id The id of the cluster containing the HSM instance(s) --disable-key-availability-check Disables key availability check during key use --enable-key-availability-check Enables key availability check during key use --disable-validate-key-at-init Disables parameter validation during initialization of crypto operations --enable-validate-key-at-init Enables parameter validation during initialization of crypto operations --endpoint Specify the AWS CloudHSM API Endpoint --region The region of the cluster --hsm-ca-cert The HSM CA certificate file --log-type The log type [possible values: term, file] --log-file The log file --log-level The logging level [possible values: error, warn, info, debug, trace] --log-rotation The log rotation interval [possible values: never, hourly, daily] --default-retry-mode The default method of retry to use for certain non-terminal failures [possible values: off, standard] --client-cert-hsm-tls-file The client certificate used for TLS client-hsm mutual authentication --client-key-hsm-tls-file The client private key used for TLS client-hsm mutual authentication -h, --help Print help ``` ------ #### [ CloudHSM CLI ] ``` Usage: configure-cli[ .exe ] [OPTIONS] Options: -a ... The address of the HSM instance --cluster-id The id of the cluster containing the HSM instance(s) --disable-key-availability-check Disables key availability check during key use --enable-key-availability-check Enables key availability check during key use --disable-validate-key-at-init Disables parameter validation during initialization of crypto operations --enable-validate-key-at-init Enables parameter validation during initialization of crypto operations --endpoint Specify the AWS CloudHSM API Endpoint --region The region of the cluster --hsm-ca-cert The HSM CA certificate file --log-type The log type [possible values: term, file] --log-file The log file --log-level The logging level [possible values: error, warn, info, debug, trace] --log-rotation The log rotation interval [possible values: never, hourly, daily] --default-retry-mode The default method of retry to use for certain non-terminal failures [possible values: off, standard] --client-cert-hsm-tls-file The client certificate used for TLS client-hsm mutual authentication --client-key-hsm-tls-file The client private key used for TLS client-hsm mutual authentication -h, --help Print help ``` ------ #### [ OpenSSL Provider ] ``` Usage: configure-openssl-provider[ .exe ] [OPTIONS] Options: -a ... The address of the HSM instance --cluster-id The id of the cluster containing the HSM instance(s) --disable-key-availability-check Disables key availability check during key use --enable-key-availability-check Enables key availability check during key use --disable-validate-key-at-init Disables parameter validation during initialization of crypto operations --enable-validate-key-at-init Enables parameter validation during initialization of crypto operations --endpoint Specify the AWS CloudHSM API Endpoint --region The region of the cluster --hsm-ca-cert The HSM CA certificate file --log-type The log type [possible values: term, file] --log-file The log file --log-level The logging level [possible values: error, warn, info, debug, trace] --log-rotation The log rotation interval [possible values: never, hourly, daily] --default-retry-mode The default method of retry to use for certain non-terminal failures [possible values: off, standard] --client-cert-hsm-tls-file The client certificate used for TLS client-hsm mutual authentication --client-key-hsm-tls-file The client private key used for TLS client-hsm mutual authentication -h, --help Print help ``` ------ # AWS CloudHSM Client SDK 5 configuration parameters The following is a list of parameters to configure AWS CloudHSM Client SDK 5. **-a **** Adds the specified IP address to Client SDK 5 configuration files. Enter any ENI IP address of an HSM from the cluster. For more information about how to use this option, see [Bootstrap Client SDK 5](cluster-connect.md#sdk8-connect). Required: Yes **--hsm-ca-cert **** Path to the directory storing the certificate authority (CA) certificate use to connect EC2 client instances to the cluster. You create this file when you initialize the cluster. By default, the system looks for this file in the following location: Linux ``` /opt/cloudhsm/etc/customerCA.crt ``` Windows ``` C:\ProgramData\Amazon\CloudHSM\customerCA.crt ``` For more information about initializing the cluster or placing the certificate, see [Place the issuing certificate on each EC2 instance](cluster-connect.md#place-hsm-cert) and [Initialize the cluster in AWS CloudHSM](initialize-cluster.md). Required: No **--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: No **--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 **--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 **** 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 **** 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 **--log-level **** Specifies the minimum logging level the system should write to the log file. Each level includes the previous levels, with error as the minimum level and trace the maximum level. This means that if you specify errors, the system only writes errors to the log. If you specify trace, the system writes errors, warnings, informational (info) and debug messages to the log. For more information, see [Client SDK 5 Logging](hsm-client-logs.md#sdk5-logging). Required: No **--log-rotation **** Specifies the frequency with which the system rotates logs. For more information, see [Client SDK 5 Logging](hsm-client-logs.md#sdk5-logging). Required: No **--log-file **** Specifies where the system will write the log file. For more information, see [Client SDK 5 Logging](hsm-client-logs.md#sdk5-logging). Required: No **--log-type **** Specifies whether the system will write the log to a file or terminal. For more information, see [Client SDK 5 Logging](hsm-client-logs.md#sdk5-logging). Required: No **-h \$1 --help** Displays help. Required: No **--disable-key-availability-check ** Flag to disable key availability quorum. Use this flag to indicate AWS CloudHSM should disable key availability quorum and you can use keys that exist on only one HSM in the cluster. For more information about using this flag to set key availability quorum, see [Managing client key durability settings](working-client-sync.md#setting-file-sdk8). Required: No **--enable-key-availability-check ** Flag to enable key availability quorum. Use this flag to indicate AWS CloudHSM should use key availability quorum and not allow you to use keys until those keys exist on two HSMs in the cluster. For more information about using this flag to set key availability quorum, see [Managing client key durability settings](working-client-sync.md#setting-file-sdk8). Enabled by default. Required: No **--disable-validate-key-at-init ** Improves performance by specifying that you can skip an initialization call to verify permissions on a key for subsequent calls. Use with caution. Background: Some mechanisms in the PKCS \$111 library support multi-part operations where an initialization call verifies if you can use the key for subsequent calls. This requires a verification call to the HSM, which adds latency to the overall operation. This option enables you to disable the subsequent call and potentially improve performance. Required: No **--enable-validate-key-at-init ** Specifies that you should use an initialization call to verify permissions on a key for subsequent calls. This is the default option. Use `enable-validate-key-at-init` to resume these initialization calls after you use `disable-validate-key-at-init` to suspend them. Required: No # AWS CloudHSM Client SDK 5 configuration examples These examples show how to use the configure tool for AWS CloudHSM Client SDK 5. ## Bootstrap Client SDK 5 **Example** This example uses the `-a` parameter to update the HSM data for Client SDK 5. To use the `-a` parameter, you must have the IP address for one of the HSMs in your cluster. **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 -a ``` **To bootstrap a Windows EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" -a ``` **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-dyn -a ``` **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider -a ``` **To bootstrap a Windows EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" -a ``` **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-jce -a ``` **To bootstrap a Windows EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" -a ``` **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 ``` **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 ``` you can use the `–-cluster-id` parameter in place of `-a `. To see requirements for using `–-cluster-id`, see [AWS CloudHSM Client SDK 5 configure tool](configure-sdk-5.md). For more information about the `-a` parameter, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). ## Specify cluster, region, and endpoint for Client SDK 5 **Example** This example uses the `cluster-id` parameter to bootstrap Client SDK 5 by making a `DescribeClusters` call. **To bootstrap a Linux EC2 instance for Client SDK 5 with `cluster-id`** + Use the cluster ID `cluster-1234567` to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 --cluster-id ``` **To bootstrap a Windows EC2 instance for Client SDK 5 with `cluster-id`** + Use the cluster ID `cluster-1234567` to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --cluster-id ``` **To bootstrap a Linux EC2 instance for Client SDK 5 with `cluster-id`** + Use the cluster ID `cluster-1234567` to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-dyn --cluster-id ``` **To bootstrap a Windows EC2 instance for Client SDK 5 with `cluster-id`** + Use the cluster ID `cluster-1234567` to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --cluster-id ``` **To bootstrap a Linux EC2 instance for Client SDK 5 with `cluster-id`** + Use the cluster ID `cluster-1234567` to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-jce --cluster-id ``` **To bootstrap a Windows EC2 instance for Client SDK 5 with `cluster-id`** + Use the cluster ID `cluster-1234567` to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --cluster-id ``` **To bootstrap a Linux EC2 instance for Client SDK 5 with `cluster-id`** + Use the cluster ID `cluster-1234567` to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-cli --cluster-id ``` **To bootstrap a Windows EC2 instance for Client SDK 5 with `cluster-id`** + Use the cluster ID `cluster-1234567` to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" --cluster-id ``` You can use the `--region` and `--endpoint` parameters in combination with the `cluster-id` parameter to specify how the system makes the `DescribeClusters` call. For instance, if the region of the cluster is different than the one configured as your AWS CLI default, you should use the `--region` parameter to use that region. Additionally, you have the ability to specify the AWS CloudHSM API endpoint to use for the call, which might be necessary for various network setups, such as using VPC interface endpoints that don’t use the default DNS hostname for AWS CloudHSM. **To bootstrap a Linux EC2 instance with a custom endpoint and region** + Use the configure tool to specify the IP address of an HSM in your cluster with a custom region and endpoint. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 --cluster-id --region --endpoint ``` **To bootstrap a Windows EC2 instance with a endpoint and region** + Use the configure tool to specify the IP address of an HSM in your cluster with a custom region and endpoint. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --cluster-id --region --endpoint ``` **To bootstrap a Linux EC2 instance with a custom endpoint and region** + Use the configure tool to specify the IP address of an HSM in your cluster with a custom region and endpoint. ``` $ sudo /opt/cloudhsm/bin/configure-dyn --cluster-id --region --endpoint ``` **To bootstrap a Windows EC2 instance with a endpoint and region** + Use the configure tool to specify the IP address of an HSM in your cluster with a custom region and endpoint. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --cluster-id --region --endpoint ``` **To bootstrap a Linux EC2 instance with a custom endpoint and region** + Use the configure tool to specify the IP address of an HSM in your cluster with a custom region and endpoint. ``` $ sudo /opt/cloudhsm/bin/configure-jce --cluster-id --region --endpoint ``` **To bootstrap a Windows EC2 instance with a endpoint and region** + Use the configure tool to specify the IP address of an HSM in your cluster with a custom region and endpoint. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --cluster-id --region --endpoint ``` **To bootstrap a Linux EC2 instance with a custom endpoint and region** + Use the configure tool to specify the IP address of an HSM in your cluster with a custom region and endpoint. ``` $ sudo /opt/cloudhsm/bin/configure-cli --cluster-id --region --endpoint ``` **To bootstrap a Windows EC2 instance with a endpoint and region** + Use the configure tool to specify the IP address of an HSM in your cluster with a custom region and endpoint. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" --cluster-id --region --endpoint ``` For more information about the `--cluster-id`, `--region`, and `--endpoint` parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). ## Update client certificate and key for TLS client-HSM mutual authentication **Example** This examples shows how to use the `--client-cert-hsm-tls-file` and `--client-key-hsm-tls-file` parameters to reconfigure SSL by specifying a custom key and SSL certificate for AWS CloudHSM **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Linux** 1. Copy your key and certificate to the appropriate directory. ``` $ sudo cp ssl-client.pem $ sudo cp ssl-client.key ``` 1. Use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 \ --client-cert-hsm-tls-file \ --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Windows** 1. Copy your key and certificate to the appropriate directory. ``` cp ssl-client.pem cp ssl-client.key ``` 1. With a PowerShell interpreter, use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" ` --client-cert-hsm-tls-file ` --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Linux** 1. Copy your key and certificate to the appropriate directory. ``` $ sudo cp ssl-client.pem sudo cp ssl-client.key ``` 1. Use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` $ sudo /opt/cloudhsm/bin/configure-dyn \ --client-cert-hsm-tls-file \ --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Windows** 1. Copy your key and certificate to the appropriate directory. ``` cp ssl-client.pem cp ssl-client.key ``` 1. With a PowerShell interpreter, use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" ` --client-cert-hsm-tls-file ` --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Linux** 1. Copy your key and certificate to the appropriate directory. ``` $ sudo cp ssl-client.pem sudo cp ssl-client.key ``` 1. Use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` $ sudo /opt/cloudhsm/bin/configure-jce \ --client-cert-hsm-tls-file \ --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Windows** 1. Copy your key and certificate to the appropriate directory. ``` cp ssl-client.pem cp ssl-client.key ``` 1. With a PowerShell interpreter, use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" ` --client-cert-hsm-tls-file ` --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Linux** 1. Copy your key and certificate to the appropriate directory. ``` $ sudo cp ssl-client.pem sudo cp ssl-client.key ``` 1. Use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` $ sudo /opt/cloudhsm/bin/configure-cli \ --client-cert-hsm-tls-file \ --client-key-hsm-tls-file ``` **To use a custom certificate and key for TLS client-HSM mutual authentication with Client SDK 5 on Windows** 1. Copy your key and certificate to the appropriate directory. ``` cp ssl-client.pem cp ssl-client.key ``` 1. With a PowerShell interpreter, use the configure tool to specify `ssl-client.pem` and `ssl-client.key`. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" ` --client-cert-hsm-tls-file ` --client-key-hsm-tls-file ``` For more information about the `--client-cert-hsm-tls-file` and `--client-key-hsm-tls-file` parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). ## Disable client key durability settings **Example** This example uses the `--disable-key-availability-check` parameter to disable client key durability settings. To run a cluster with a single HSM, you must disable client key durability settings. **To disable client key durability for Client SDK 5 on Linux** + Use the configure tool to disable client key durability settings. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 --disable-key-availability-check ``` **To disable client key durability for Client SDK 5 on Windows** + Use the configure tool to disable client key durability settings. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --disable-key-availability-check ``` **To disable client key durability for Client SDK 5 on Linux** + Use the configure tool to disable client key durability settings. ``` $ sudo /opt/cloudhsm/bin/configure-dyn --disable-key-availability-check ``` **To disable client key durability for Client SDK 5 on Linux** + Use the configure tool to disable client key durability settings. ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider --disable-key-availability-check ``` **To disable client key durability for Client SDK 5 on Windows** + Use the configure tool to disable client key durability settings. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-key-availability-check ``` **To disable client key durability for Client SDK 5 on Linux** + Use the configure tool to disable client key durability settings. ``` $ sudo /opt/cloudhsm/bin/configure-jce --disable-key-availability-check ``` **To disable client key durability for Client SDK 5 on Windows** + Use the configure tool to disable client key durability settings. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-key-availability-check ``` **To disable client key durability for Client SDK 5 on Linux** + Use the configure tool to disable client key durability settings. ``` $ sudo /opt/cloudhsm/bin/configure-cli --disable-key-availability-check ``` **To disable client key durability for Client SDK 5 on Windows** + Use the configure tool to disable client key durability settings. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" --disable-key-availability-check ``` For more information about the `--disable-key-availability-check` parameter, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). ## Manage logging options **Example** Client SDK 5 uses the `log-file`, `log-level`, `log-rotation`, and `log-type` parameters to manage logging. To configure your SDK for serverless environments such as AWS Fargate or AWS Lambda, we recommend you configure your AWS CloudHSM log type to `term`. The client logs will be output to `stderr` and captured in the CloudWatch Logs log group configured for that environment. **Default logging location** + If you do not specify a location for the file, the system writes logs to the following default location: Linux ``` /opt/cloudhsm/run/cloudhsm-pkcs11.log ``` Windows ``` C:\Program Files\Amazon\CloudHSM\cloudhsm-pkcs11.log ``` **To configure the logging level and leave other logging options set to default** + ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 --log-level info ``` **To configure file logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 --log-type file --log-file --log-rotation daily --log-level info ``` **To configure terminal logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 --log-type term --log-level info ``` **Default logging location** + If you do not specify a location for the file, the system writes logs to the following default location: Linux ``` stderr ``` **To configure the logging level and leave other logging options set to default** + ``` $ sudo /opt/cloudhsm/bin/configure-dyn --log-level info ``` **To configure file logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-dyn --log-type file --log-file --log-rotation daily --log-level info ``` **To configure terminal logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-dyn --log-type term --log-level info ``` **Default logging location** + If you do not specify a location for the file, the system writes logs to the following default location: Linux ``` stderr ``` **To configure the logging level and leave other logging options set to default** + ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider --log-level info ``` **To configure file logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider --log-type file --log-file --log-rotation daily --log-level info ``` **To configure terminal logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider --log-type term --log-level info ``` **Default logging location** + If you do not specify a location for the file, the system writes logs to the following default location: Windows ``` C:\Program Files\Amazon\CloudHSM\cloudhsm-ksp.log ``` **To configure the logging level and leave other logging options set to default** + ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --log-level info ``` **To configure file logging options** + ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --log-type file --log-file --log-rotation daily --log-level info ``` **To configure terminal logging options** + ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --log-type term --log-level info ``` **Default logging location** + If you do not specify a location for the file, the system writes logs to the following default location: Linux ``` /opt/cloudhsm/run/cloudhsm-jce.log ``` Windows ``` C:\Program Files\Amazon\CloudHSM\cloudhsm-jce.log ``` **To configure the logging level and leave other logging options set to default** + ``` $ sudo /opt/cloudhsm/bin/configure-jce --log-level info ``` **To configure file logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-jce --log-type file --log-file --log-rotation daily --log-level info ``` **To configure terminal logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-jce --log-type term --log-level info ``` **Default logging location** + If you do not specify a location for the file, the system writes logs to the following default location: Linux ``` /opt/cloudhsm/run/cloudhsm-cli.log ``` Windows ``` C:\Program Files\Amazon\CloudHSM\cloudhsm-cli.log ``` **To configure the logging level and leave other logging options set to default** + ``` $ sudo /opt/cloudhsm/bin/configure-cli --log-level info ``` **To configure file logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-cli --log-type file --log-file --log-rotation daily --log-level info ``` **To configure terminal logging options** + ``` $ sudo /opt/cloudhsm/bin/configure-cli --log-type term --log-level info ``` For more information about the `log-file`, `log-level`, `log-rotation`,and `log-type` parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). ## Place the issuing certificate for Client SDK 5 **Example** This example uses the `--hsm-ca-cert` parameter to update the location of the issuing certificate for Client SDK 5. **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 --hsm-ca-cert ``` **To place the issuing certificate on Windows for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --hsm-ca-cert ``` **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-dyn --hsm-ca-cert ``` **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider --hsm-ca-cert ``` **To place the issuing certificate on Windows for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --hsm-ca-cert ``` **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-jce --hsm-ca-cert ``` **To place the issuing certificate on Windows for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --hsm-ca-cert ``` **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-cli --hsm-ca-cert ``` **To place the issuing certificate on Windows for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" --hsm-ca-cert ``` For more information about the `--hsm-ca-cert` parameter, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). # Bootstrap OpenSSL Provider Use the configure-openssl-provider tool to bootstrap your OpenSSL Provider installation and connect it to your AWS CloudHSM cluster. **To bootstrap the OpenSSL Provider** 1. Run the configure-openssl-provider command with the IP address of an HSM in your cluster: ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider -a ``` Replace ** with the IP address of any HSM in your cluster. 1. Verify the configuration by checking that the OpenSSL Provider can connect to your cluster: ``` $ openssl list -providers -provider-path /opt/cloudhsm/lib -provider cloudhsm ``` For more information about the configuration parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). # Advanced configurations for the Client SDK 5 configure tool The AWS CloudHSM Client SDK 5 configure tool includes advanced configurations that are not part of the general features most customers utilize. Advanced configurations provide additional capabilities. **Important** After making any changes to your configuration, you need to restart your application for the changes to take effect. + Advanced configurations for PKCS \$111 + [Multiple slot configuration with PKCS \$111 library for AWS CloudHSM](pkcs11-library-configs-multi-slot.md) + [Retry commands for PKCS \$111 library for AWS CloudHSM](pkcs11-library-configs-retry.md) + Advanced configurations for OpenSSL + [Retry commands for OpenSSL for AWS CloudHSM](openssl-library-configs-retry.md) + Advanced configurations for KSP + [SDK3 compatibility mode for Key Storage Provider (KSP) for AWS CloudHSM](ksp-library-configs-sdk3-compatibility-mode.md) + Advanced configurations for JCE + [Connecting to multiple AWS CloudHSM clusters with the JCE provider](java-lib-configs-multi.md) + [Retry commands for JCE for AWS CloudHSM](java-lib-configs-retry.md) + [Key extraction using JCE for AWS CloudHSM](java-lib-configs-getencoded.md) + Advanced configurations for AWS CloudHSM Command Line Interface (CLI) + [Connecting to multiple clusters with CloudHSM CLI](cloudhsm_cli-configs-multi-cluster.md) # AWS CloudHSM Client SDK 5 related topics See the following related topics to learn more about the AWS CloudHSM Client SDK 5. + [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) API operation + [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) AWS CLI + [Get-HSM2Cluster](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-HSM2Cluster.html) PowerShell cmdlet + [Bootstrap Client SDK 5](cluster-connect.md#sdk8-connect) + [Bootstrap OpenSSL Provider](configure-openssl-provider.md) + [AWS CloudHSM VPC endpoints](cloudhsm-vpc-endpoint.md) + [Managing Client SDK 5 Key Durability Settings](working-client-sync.md#setting-file-sdk8) + [Client SDK 5 Logging](hsm-client-logs.md#sdk5-logging) + [Setup mTLS (recommended)](getting-started-setup-mtls.md) # AWS CloudHSM Client SDK 3 configure tool Use the AWS CloudHSM Client SDK 3 configure tool to bootstrap the client daemon and configure CloudHSM Management Utility (CMU). **Topics** + [Syntax](configure-tool-syntax.md) + [Parameters](configure-tool-params.md) + [Examples](configure-tool-examples.md) + [Related topics](configure-tool-seealso.md) # AWS CloudHSM Client SDK 3 configuration syntax The following table illustrates the syntax for AWS CloudHSM configuration files for Client SDK 3. ``` configure -h | --help -a -m [-i ] --ssl --pkey --cert --cmu ``` # AWS CloudHSM Client SDK 3 configuration parameters The following is a list of parameters to configure AWS CloudHSM Client SDK 3. **-h \$1 --help** Displays command syntax. Required: Yes **-a **** Adds the specified HSM elastic network interface (ENI) IP address to AWS CloudHSM configuration files. Enter the ENI IP address of any one of the HSMs in the cluster. It does not matter which one you select. To get the ENI IP addresses of the HSMs in your cluster, use the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation, the [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) AWS CLI command, or the [Get-HSM2Cluster](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-HSM2Cluster.html) PowerShell cmdlet. Before running the ` -a` **configure** command, stop the AWS CloudHSM client. Then, when the `-a` command completes, restart the AWS CloudHSM client. For details, [see the examples](configure-tool-examples.md). This parameter edits the following configuration files: + `/opt/cloudhsm/etc/cloudhsm_client.cfg`: Used by AWS CloudHSM client and [key\$1mgmt\$1util](key_mgmt_util.md). + `/opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg`: Used by [cloudhsm\$1mgmt\$1util](cloudhsm_mgmt_util.md). When the AWS CloudHSM client starts, it uses the ENI IP address in its configuration file to query the cluster and update the `cluster.info` file (`/opt/cloudhsm/daemon/1/cluster.info`) with the correct ENI IP addresses for all HSMs in the cluster. Required: Yes **-m** Updates the HSM ENI IP addresses in the configuration file that CMU uses. The `-m` parameter is for use with CMU from Client SDK 3.2.1 and earlier. For CMU from Client SDK 3.3.0 and later, see `--cmu` parameter, which simplifies the process of updating HSM data for CMU. When you update the `-a` parameter of **configure** and then start the AWS CloudHSM client, the client daemon queries the cluster and updates the `cluster.info` files with the correct HSM IP addresses for all HSMs in the cluster. Running the `-m` **configure** command completes the update by copying the HSM IP addresses from the `cluster.info` to the `cloudhsm_mgmt_util.cfg` configuration file that cloudhsm\$1mgmt\$1util uses. Be sure to run `-a` **configure** command and restart the AWS CloudHSM client before running the `-m` command. This ensures that the data copied into `cloudhsm_mgmt_util.cfg` from `cluster.info` is complete and accurate. Required: Yes **-i** Specifies an alternate client daemon. The default value represents the AWS CloudHSM client. Default: `1` Required: No **--ssl** Replaces the SSL key and certificate for the cluster with the specified private key and certificate. When you use this parameter, the `--pkey` and `--cert` parameters are required. Required: No **--pkey** Specifies the new private key. Enter the path and file name of the file that contains the private key. Required: Yes if **--ssl** is specified. Otherwise, this should not be used. **--cert** Specifies the new certificate. Enter the path and file name of the file that contains the certificate. The certificate should chain up to the `customerCA.crt` certificate, the self-signed certificate used to initialize the cluster. For more information, see [Initialize the Cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html#sign-csr). Required: Yes if **--ssl** is specified. Otherwise, this should not be used. **--cmu **** Combines the `-a` and `-m` parameters into one parameter. Adds the specified HSM elastic network interface (ENI) IP address to AWS CloudHSM configuration files and then updates the CMU configuration file. Enter an IP address from any HSM in the cluster. For Client SDK 3.2.1 and earlier, see [Using CMU with Client SDK 3.2.1 and Earlier](understand-users.md#downlevel-cmu). Required: Yes # AWS CloudHSM Client SDK 3 configuration examples These examples show how to use the **configure** tool for AWS CloudHSM Client SDK 3. **Example : Update the HSM data for the AWS CloudHSM client and key\$1mgmt\$1util** This example uses the `-a` parameter of **configure** to update the HSM data for the AWS CloudHSM client and key\$1mgmt\$1util. To use the `-a` parameter, you must have the IP address for one of the HSMs in your cluster. Use either the console or the AWS CLI to get the IP address. **To get an IP address for an HSM (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. To change the AWS Region, use the Region selector in the upper-right corner of the page. 1. To open the cluster detail page, in the cluster table, choose the cluster ID. 1. To get the IP address, go to the HSMs tab. For IPv4 clusters, choose an address listed under **ENI IPv4 address**. For dual-stack clusters use either the ENI IPv4 or the **ENI IPv6 address**. **To get an IP address for an HSM (AWS CLI)** + Get the IP address of an HSM by using the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command from the AWS CLI. In the output from the command, the IP address of the HSMs are the values of `EniIp` and `EniIpV6` (if it is a dual-stack cluster). ``` $ aws cloudhsmv2 describe-clusters { "Clusters": [ { ... } "Hsms": [ { ... "EniIp": "10.0.0.9", ... }, { ... "EniIp": "10.0.1.6", "EniIpV6": "2600:113f:404:be09:310e:ed34:3412:f733", ... ``` **To update the HSM data** 1. Before updating the `-a` parameter, stop the AWS CloudHSM client. This prevents conflicts that might occur while **configure** edits the client's configuration file. If the client is already stopped, this command has no effect, so you can use it in a script. ------ #### [ Amazon Linux ] ``` $ sudo stop cloudhsm-client ``` ------ #### [ Amazon Linux 2 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ CentOS 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ CentOS 8 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 8 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Windows ] + For Windows client 1.1.2\$1: ``` C:\Program Files\Amazon\CloudHSM>net.exe stop AWSCloudHSMClient ``` + For Windows clients 1.1.1 and older: Use **Ctrl**\$1**C** in the command window where you started the AWS CloudHSM client. ------ 1. This step uses the `-a` parameter of **configure** to add the `10.0.0.9` ENI IP address to the configurations files. ------ #### [ Amazon Linux ] ``` $ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 ``` ------ #### [ Amazon Linux 2 ] ``` $ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 ``` ------ #### [ CentOS 7 ] ``` $ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 ``` ------ #### [ CentOS 8 ] ``` $ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 ``` ------ #### [ RHEL 7 ] ``` $ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 ``` ------ #### [ RHEL 8 ] ``` $ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" -a 10.0.0.9 ``` ------ 1. Next, restart the AWS CloudHSM client. When the client starts, it uses the ENI IP address in its configuration file to query the cluster. Then, it writes the ENI IP addresses of all HSMs in the cluster to the `cluster.info` file. ------ #### [ Amazon Linux ] ``` $ sudo start cloudhsm-client ``` ------ #### [ Amazon Linux 2 ] ``` $ sudo service cloudhsm-client start ``` ------ #### [ CentOS 7 ] ``` $ sudo service cloudhsm-client start ``` ------ #### [ CentOS 8 ] ``` $ sudo service cloudhsm-client start ``` ------ #### [ RHEL 7 ] ``` $ sudo service cloudhsm-client start ``` ------ #### [ RHEL 8 ] ``` $ sudo service cloudhsm-client start ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo service cloudhsm-client start ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo service cloudhsm-client start ``` ------ #### [ Windows ] + For Windows client 1.1.2\$1: ``` C:\Program Files\Amazon\CloudHSM>net.exe start AWSCloudHSMClient ``` + For Windows clients 1.1.1 and older: ``` C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg ``` ------ When the command completes, the HSM data that the AWS CloudHSM client and key\$1mgmt\$1util use is complete and accurate. **Example : Update the HSM Data for CMU from client SDK 3.2.1 and earlier** This example uses the `-m` **configure** command to copy the updated HSM data from the `cluster.info` file to the `cloudhsm_mgmt_util.cfg` file that cloudhsm\$1mgmt\$1util uses. Use this with CMU that ships with Client SDK 3.2.1 and earlier. + Before running the `-m`, stop the AWS CloudHSM client, run the `-a` command, and then restart the AWS CloudHSM client, as shown in the [previous example](#configure-tool-examples). This ensures that the data copied into the `cloudhsm_mgmt_util.cfg` file from the `cluster.info` file is complete and accurate. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure -m ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" -m ``` ------ **Example : Update the HSM Data for CMU from client SDK 3.3.0 and later** This example uses the `--cmu` parameter of the **configure** command to update HSM data for CMU. Use this with CMU that ships with Client SDK 3.3.0 and later. For more information about using CMU, see [Using CloudHSM Management Utility (CMU) to Manage Users](manage-hsm-users-cmu.md) and [Using CMU with Client SDK 3.2.1 and Earlier](understand-users.md#downlevel-cmu). + Use the `--cmu` parameter to pass the IP address of an HSM in your cluster. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure --cmu ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" --cmu ``` ------ # AWS CloudHSM Client SDK 3 configuration related topics See the following related topics to learn more about the AWS CloudHSM Client SDK 3. + [Set up AWS CloudHSM key\$1mgmt\$1util](key_mgmt_util-setup.md) # AWS CloudHSM Command Line Interface (CLI) **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 This topic describes the Linux and Windows platforms that the AWS CloudHSM CLI supports. ## Linux support | 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 + 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) 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 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 ``` **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 ``` # Use the CloudHSM CLI 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 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 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 --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 ``` 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 **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 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 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 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 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 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 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 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 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 When connecting to multiple clusters, use the `configure-cli add-cluster` command to add a cluster to your configuration. ## Syntax ``` configure-cli add-cluster [OPTIONS] --cluster-id [--region ] [--endpoint ] [--hsm-ca-cert ] [--client-cert-hsm-tls-file ] [--client-key-hsm-tls-file ] [-h, --help] ``` ## Examples ### Add a cluster using the `cluster-id` parameter **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 ``` ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" add-cluster --cluster-id ``` **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 **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 --region --endpoint ``` ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" add-cluster --cluster-id --region --endpoint ``` For more information about the `--cluster-id`, `--region`, and `--endpoint` parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). ## Parameters **--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 **** 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 **** Specifies the filepath to the HSM CA certificate. Required: No **--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 **** 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 **** 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 When connecting to multiple clusters with CloudHSM CLI, use the `configure-cli remove-cluster` command to remove a cluster from your configuration. ## Syntax ``` configure-cli remove-cluster [OPTIONS] --cluster-id [-h, --help] ``` ## Examples ### Remove a cluster using the `cluster-id` parameter **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 ``` ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" remove-cluster --cluster-id ``` For more information about the `--cluster-id` parameter, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md). ## Parameter **--cluster-id **** The ID of the cluster to remove from the configuration. Required: Yes # Interact with multiple clusters in AWS CloudHSM After configuring multiple clusters with CloudHSM CLI, use the `cloudhsm-cli` command to interact with them. ## Examples ### Setting a default `cluster-id` when using interactive mode **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 ``` ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive --cluster-id ``` ### Setting the `cluster-id` when running a single command **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 ``` ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" cluster hsm-info --cluster-id ``` # Reference for CloudHSM CLI commands 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 [...] --wrapping-filter [...] Options: --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 [...] 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 [...] 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 to the binary file where the wrapped key data will be saved --wrapping-approval File path of signed quorum token file to approve operation for wrapping key --payload-approval 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** 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 to the binary file where the wrapped key data will be saved. Required: No ****** 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 ****** 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. ****** 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 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 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 The following types of users can run this command. + Unactivated admin ## Syntax 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 ] Options: --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 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 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 + [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 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 The following types of users can run this command. + All users. You do not need to be logged in to run this command. ## Syntax ``` aws-cloudhsm > help cluster hsm-info List info about each HSM in the cluster Usage: cloudhsm-cli cluster hsm-info [OPTIONS] Options: --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 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 + [Activate a cluster with CloudHSM CLI](cloudhsm_cli-cluster-activate.md) # The cluster mtls category in CloudHSM CLI 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 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 The following users can run this command. + Admin ## Requirements + To run this command, you must be logged in as a admin user. ## Syntax ``` aws-cloudhsm > help cluster mtls deregister-trust-anchor Deregister a trust anchor for mtls Usage: cluster mtls deregister-trust-anchor [OPTIONS] --certificate-reference [...] Options: --certificate-reference A hexadecimal or decimal certificate reference --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 Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Example **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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ** ** ** 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. ** ** ** 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 + [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 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 The following users can run this command. + Admin + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a admin user or crypto user (CUs). ## Syntax ``` 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 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 **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 ****** 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 + [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 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 The following users can run this command. + All users. You do not need to be logged in to run this command. ## Syntax ``` aws-cloudhsm > help cluster mtls list-trust-anchors List all trust anchors for mtls Usage: cluster mtls list-trust-anchors [OPTIONS] Options: --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 **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": "", "cluster-coverage": "full" }, { "certificate-reference": "0x02", "certificate": "", "cluster-coverage": "full" } ] } } ``` ## Arguments ****** 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 + [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 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 The following users can run this command. + Admin ## Requirements 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 ``` aws-cloudhsm > help cluster mtls register-trust-anchor Register a trust anchor for mtls Usage: cluster mtls register-trust-anchor [OPTIONS] --path [...] Options: --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 Filepath of the trust anchor to register --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Example **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": "", "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": "", "cluster-coverage": "full" } ] } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ** ** ** 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. ** ** ** 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 + [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 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 The following users can run this command. + Admin with username as admin ## Requirements 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 ``` aws-cloudhsm > help cluster mtls set-enforcement Set mtls enforcement policy in the cluster Usage: cluster mtls set-enforcement [OPTIONS] --level [...] Options: --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 to be set for mtls in the cluster [possible values: none, cluster] --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Example **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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ** ** ** 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. ** ** ** 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 + [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 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 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 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 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 crypto sign ecdsa Sign with the ECDSA mechanism Usage: crypto sign ecdsa --key-filter [>...] --hash-function <--data-path |--data > Options: --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 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 [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be signed --data Base64 Encoded data to be signed --approval Filepath of signed quorum token file to approve operation --data-type The type of data passed in, either raw or digest [possible values: raw, digest] -h, --help Print help ``` ## Example 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data path) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** 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 ****** 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. ****** 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 + [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 **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 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. + HashEdDSA signing operations are only supported on hsm2m.medium instances in non-FIPS mode. ## Syntax ``` aws-cloudhsm > help crypto sign ed25519ph Sign with the Ed25519ph mechanism Usage: crypto sign ed25519ph [OPTIONS] --key-filter [...] --data-type --hash-function <--data-path |--data > Options: --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 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 The path to the file containing the data to be signed --data Base64 Encoded data to be signed --approval Filepath of signed quorum token file to approve operation --data-type The type of data passed in, either raw or digest [possible values: raw, digest] --hash-function Hash function [possible values: sha512] -h, --help Print help ``` ## Example 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data parameter) ****** Specifies the hash function. Ed25519ph only supports SHA512. Valid values: + sha512 Required: Yes ****** 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 ****** 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. ****** 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 + [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 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 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 crypto sign rsa-pkcs Sign with the RSA-PKCS mechanism Usage: crypto sign rsa-pkcs --key-filter [>...] --hash-function <--data-path |--data > Options: --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 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 [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be signed --data Base64 Encoded data to be signed --approval Filepath of signed quorum token file to approve operation --data-type The type of data passed in, either raw or digest [possible values: raw, digest] -h, --help Print help ``` ## Example 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** 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 ****** 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. ****** 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 + [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 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 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 crypto sign rsa-pkcs-pss Sign with the RSA-PKCS-PSS mechanism Usage: crypto sign rsa-pkcs-pss [OPTIONS] --key-filter [...] --hash-function --mgf --salt-length <--data-path |--data > Options: --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 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 [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be signed --data Base64 Encoded data to be signed --mgf The mask generation function [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512] --salt-length The salt length --approval Filepath of signed quorum token file to approve operation --data-type The type of data passed in, either raw or digest [possible values: raw, digest] -h, --help Print help ``` ## Example 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** 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 ****** 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 ****** Specifies the salt length. Required: Yes ****** 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. ****** 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 + [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 + [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) # The crypto verify category in CloudHSM CLI 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 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 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 crypto verify ecdsa Verify with the ECDSA mechanism Usage: crypto verify ecdsa --key-filter [...] --hash-function <--data-path |--data > <--signature-path |--signature > Options: --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 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 [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be verified --data Base64 encoded data to be verified --signature-path The path to where the signature is located --signature Base64 encoded signature to be verified --data-type The type of data passed in, either raw or digest [possible values: raw, digest] -h, --help Print help ``` ## Example 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data path) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** 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 ****** Base64 encoded signature. Required: Yes (unless provided through signature path) ****** Specifies the location of the signature. Required: Yes (unless provided through signature path) ****** 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 + [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 **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 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. + HashEdDSA signature verification operations are only supported on hsm2m.medium instances in non-FIPS mode. ## Syntax ``` aws-cloudhsm > help crypto verify ed25519ph Verify with the Ed25519ph mechanism Usage: crypto verify ed25519ph [OPTIONS] --key-filter [...] --data-type --hash-function <--data-path |--data > <--signature-path |--signature > Options: --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 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 The path to the file containing the data to be verified --data Base64 encoded data to be verified --signature-path The path to where the signature is located --signature Base64 encoded signature to be verified --data-type The type of data passed in, either raw or digest [possible values: raw, digest] --hash-function Hash function [possible values: sha512] -h, --help Print help ``` ## Example 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be verified. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be verified. Required: Yes (unless provided through data parameter) ****** Specifies the hash function. Ed25519ph only supports SHA512. Valid values: + sha512 Required: Yes ****** 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 ****** Base64 encoded signature. Required: Yes (unless provided through signature path) ****** Specifies the location of the signature. Required: Yes (unless provided through signature parameter) ****** 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 + [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 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 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 crypto verify rsa-pkcs Verify with the RSA-PKCS mechanism Usage: crypto verify rsa-pkcs --key-filter [...] --hash-function <--data-path |--data > <--signature-path |--signature > Options: --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 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 [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be verified --data Base64 encoded data to be verified --signature-path The path to where the signature is located --signature Base64 encoded signature to be verified --data-type The type of data passed in, either raw or digest [possible values: raw, digest] -h, --help Print help ``` ## Example 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data path) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** 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 ****** Base64 encoded signature. Required: Yes (unless provided through signature path) ****** Specifies the location of the signature. Required: Yes (unless provided through signature path) ****** 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 + [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 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 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 crypto verify rsa-pkcs-pss Verify with the RSA-PKCS-PSS mechanism Usage: crypto verify rsa-pkcs-pss --key-filter [...] --hash-function --mgf --salt-length >SALT_LENGTH< <--data-path |--data <--signature-path |--signature > Options: --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 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 [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be verified --data Base64 encoded data to be verified --signature-path The path to where the signature is located --signature Base64 encoded signature to be verified --data-type The type of data passed in, either raw or digest [possible values: raw, digest] --mgf The mask generation function [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512] --salt-length The salt length -h, --help Print help ``` ## Example 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data path) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** 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 ****** 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 ****** Base64 encoded signature. Required: Yes (unless provided through signature path) ****** Specifies the location of the signature. Required: Yes (unless provided through signature path) ****** 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 + [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 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 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 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 delete Delete a key in the HSM cluster Usage: key delete [OPTIONS] --filter [...] Options: --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 [...] 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 ``` aws-cloudhsm > key delete --filter attr.label="ec-test-public-key" { "error_code": 0, "data": { "message": "Key deleted successfully" } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** 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 + [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 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 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 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 --path --filter [...] Options: --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 format for the key file Possible values: - reference-pem: PEM formatted key reference (supports private keys) - pem: PEM format (supports public keys) --path Filepath where the key file will be written --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 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** 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 ****** Specifies the encoding format for the key file Required: Yes ****** Specifies the file path where the key file will be written Required: Yes ## Generating KSP key references (Windows) **Note** This feature is only in SDK version 5.16.0 and later. ### Prerequisites + You can generate KSP key references only on Windows platforms. + You must sign in as a crypto user (CU). ### File location 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 ``` 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 --path --filter [...] Options: --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 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 Directory path where the key file will be written --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 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 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 + [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 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 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 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 generate-asymmetric-pair ec Generate an Elliptic-Curve Cryptography (ECC) key pair Usage: key generate-asymmetric-pair ec [OPTIONS] --public-label --private-label --curve Options: --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 Label for the public key --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 Elliptic curve used to generate the key pair [possible values: prime256v1, secp256r1, secp224r1, secp384r1, secp256k1, secp521r1, ed25519] --public-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 [...] 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 [...] Space separated list of Crypto User usernames to share the EC private key with --manage-private-key-quorum-value The quorum value for key management operations for the private key --use-private-key-quorum-value The quorum value for key usage operations for the private key -h, --help Print help ``` ## Examples 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** 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 ****** 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 ****** 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 ****** 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 ****** 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 ****** 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 changes this, ensuring a key generated with this argument is a session (ephemeral) key. Required: No ****** Specifies a space separated list of Crypto User usernames to share the EC private key with Required: No ****** 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 ****** 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 + [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 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 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 generate-asymmetric-pair rsa Generate an RSA key pair Usage: key generate-asymmetric-pair rsa [OPTIONS] --public-label --private-label --modulus-size-bits --public-exponent Options: --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 Label for the public key --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 in bits used to generate the RSA key pair --public-exponent Public exponent used to generate the RSA key pair --public-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 [...] 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 [...] Space separated list of Crypto User usernames to share the RSA key with --manage-private-key-quorum-value The quorum value for key management operations for the private key --use-private-key-quorum-value The quorum value for key usage operations for the private key -h, --help Print help ``` ## Examples 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 ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Specifies the length of the modulus in bits. The minimum value is 2048. Required: Yes ****** 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 ****** 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 ****** Specifies the public exponent. The value must be an odd number greater than or equal to 65537. Required: Yes ****** 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 ****** 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 ****** 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 changes this, ensuring a key generated with this argument is a session (ephemeral) key. Required: No ****** Specifies a space separated list of Crypto User usernames to share the RSA private key with Required: No ****** 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 ****** 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 + [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 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 Use the **key generate-symmetric aes** command in CloudHSM CLI to generate a symmetric AES key in your AWS CloudHSM cluster. ## 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 generate-symmetric aes Generate an AES key Usage: key generate-symmetric aes [OPTIONS] --label