Getting started with CloudHSM Command Line Interface (CLI) - AWS CloudHSM

Getting started with CloudHSM Command Line Interface (CLI)

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

Install the CloudHSM CLI

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

Amazon Linux 2

Amazon Linux 2 on x86_64 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
Amazon Linux 2023

Amazon Linux 2023 on x86_64 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
CentOS 7 (7.8+)

CentOS 7 on x86_64 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
RHEL 7 (7.8+)

RHEL 7 on x86_64 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
RHEL 8 (8.3+)

RHEL 8 on x86_64 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 9 (9.2+)

RHEL 9 on x86_64 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
Ubuntu 20.04 LTS

Ubuntu 20.04 LTS on x86_64 architecture:

$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Focal/cloudhsm-cli_latest_u20.04_amd64.deb
$ sudo apt install ./cloudhsm-cli_latest_u20.04_amd64.deb
Ubuntu 22.04 LTS

Ubuntu 22.04 LTS on x86_64 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 2016

For Windows Server 2016 on x86_64 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_64 architecture, open PowerShell as an administrator and run the following command:

PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMCLI-latest.msi -Outfile C:\AWSCloudHSMCLI-latest.msi
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMCLI-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait

Use the following commands to configure CloudHSM CLI.

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

    $ sudo /opt/cloudhsm/bin/configure-cli -a <The ENI IP addresses of the HSMs>
To bootstrap a Windows EC2 instance for Client SDK 5
  • Use the configure tool to specify the IP address of the HSM(s) in your cluster.

    "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" -a <The ENI IP addresses of the HSMs>

Using CloudHSM CLI

  1. Use the following command to start CloudHSM CLI.

    Linux
    $ /opt/cloudhsm/bin/cloudhsm-cli interactive
    Windows
    C:\Program Files\Amazon\CloudHSM\bin\> .\cloudhsm-cli.exe interactive
  2. 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 account. You set this user's password when you activated the cluster.

    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" } }
  3. 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" } ] } }
  4. Use user create to create a CU user named example_user.

    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" } }
  5. 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" } ] } }
  6. Use the logout command to log out of AWS CloudHSM cluster.

    aws-cloudhsm > logout { "error_code": 0, "data": "Logout successful" }
  7. Use the quit command to stop the CLI.

    aws-cloudhsm > quit