AWS CloudHSM CLI: User and Key Management with the Modern cloudhsm-cli

If you've worked with AWS CloudHSM before, you may have used the older cloudhsm_mgmt_util or key_mgmt_util tools. The newer cloudhsm-cli replaces both with a unified, structured CLI that returns JSON output and behaves more like a modern developer tool. This post is a practical walkthrough of day-to-day operations: getting in, managing users, and working with keys.

Starting the Interactive CLI

The CLI ships to /opt/cloudhsm/bin/cloudhsm-cli and supports an interactive REPL mode:

sudo /opt/cloudhsm/bin/cloudhsm-cli interactive

You'll land at an aws-cloudhsm > prompt. All commands are run from here.

Authentication and Roles

The new CLI uses two roles — and the names differ from what older documentation describes:

To log in:

aws-cloudhsm > login --username myuser --role crypto-user

For admin operations (user management):

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

Note: if you try --role crypto-officer you'll get an error. The old terminology is gone.

To log out:

aws-cloudhsm > logout

Cluster and HSM Information

Hardware Info

To see information about the HSMs in your cluster:

aws-cloudhsm > cluster hsm-info

Note the exact subcommand — cluster hsm-info, not cluster info or hsm info (both of which will error). This returns hardware and firmware details for each HSM in the cluster:

{
  "hsms": [
    {
      "vendor": "Marvell Semiconductors, Inc.",
      "model": "LS2",
      "serial-number": "B.0RCN2307B00615",
      "firmware-id": "MARVELL-LS2-FW-10.23-0602",
      "fips-state": "2 [FIPS mode with single factor authentication]"
    }
  ]
}

Finding HSM IP Addresses

The interactive CLI does not expose IP addresses — cluster hsm-info only returns hardware and firmware data. To find the actual IPs, look outside the CLI:

From the config file:

cat /opt/cloudhsm/etc/cloudhsm-cli.cfg

Via the AWS CLI:

aws cloudhsmv2 describe-clusters --region us-east-1

The AWS CLI output includes HSM IP addresses, subnet IDs, and AZ placement. You can cross-reference the serial numbers from cluster hsm-info against the AWS CLI output to confirm you're connected to the expected hardware — useful when managing multiple clusters across environments.

User Management

Listing Users

You don't need to be authenticated to list users:

aws-cloudhsm > user list

This returns all users with their role, lock status, MFA config, and cluster coverage. Useful for a quick inventory before you start digging for credentials.

Creating a New User

You must be logged in as admin to create users. This is important if you want to give team members individual named accounts rather than sharing a service credential:

aws-cloudhsm > login --username admin --role admin
aws-cloudhsm > user create --username jdoe --role crypto-user

You'll be prompted to set a password. HSM passwords are not recoverable, so store them somewhere safe (a secrets manager, not a sticky note).

Changing a Password

A user can change their own password from within their own session:

aws-cloudhsm > login --username jdoe --role crypto-user
aws-cloudhsm > user change-password --username jdoe --role crypto-user

An admin can also set another user's password the same way while logged in as admin — but having users set their own is better practice.

Deleting a User

Before deleting a user, verify they own no keys (see the key inventory section below). Once confirmed:

aws-cloudhsm > login --username admin --role admin
aws-cloudhsm > user delete --username jdoe --role crypto-user

Deleting a user who owns keys is something you want to avoid — key ownership on an HSM is not trivially transferred, and you could lose access to operational keys.

Key Inventory

Basic Key List

aws-cloudhsm > key list

Returns key references and labels for all keys visible to the currently logged-in user. Output is paginated at 10 keys by default.

Pagination

If total_key_count is higher than returned_key_count, use the --starting-token flag to page through:

aws-cloudhsm > key list --starting-token 10
aws-cloudhsm > key list --starting-token 20

Verbose Output (Attributes and Ownership)

The --verbose flag is where the real detail lives:

aws-cloudhsm > key list --verbose

Each key entry includes:

• key-owners: the user who created/owns the key
• shared-users: other users the key has been shared with
• attributes: key type, length, encrypt/decrypt/wrap/unwrap/sign/verify flags, sensitivity, extractability, etc.

You can also filter to a specific key:

aws-cloudhsm > key list --verbose --filter attr.label=AES256_mykey_2025

Key Reference Format

Key references are 64-bit hex values like 0x000000000070000d. When you need the decimal equivalent for logging or documentation purposes, just convert from hex — 0x70000d is 7,340,045.

If you notice key references spanning wildly different ranges (single digits, hundreds of thousands, millions), that's a sign the keys were created across multiple cluster lifecycles or HSM replacements over the years. Worth documenting in a migration inventory.

Sharing Keys Between Users

Keys on CloudHSM are owned by the user who created them. Other users cannot see or use a key unless it has been explicitly shared. This matters when you have service accounts that own operational keys and you need human users to also access them.

To share a key, log in as the key owner and use:

aws-cloudhsm > key share --filter attr.label=AES256_mykey_2025 --username jdoe --role crypto-user

Note the exact syntax — the CLI is particular about it:

• Use attr.label= as the filter prefix (not handle= or bare values)
• --username not --users
• --role is required

To verify the share took effect, log in as the target user and check key list — the key should now appear.

Sharing vs. Ownership

Sharing gives another user access but does not transfer ownership. If you eventually plan to decommission a service account, you'll want a plan for re-creating those keys under a new owner rather than just deleting the user.

Key Attributes Worth Knowing

When reviewing verbose key output, a few attributes are particularly relevant for operational and compliance purposes:

The last three are particularly useful for PCI DSS or other compliance contexts where you need to demonstrate key provenance and handling history.

A Note on the JCE Provider

If you're integrating CloudHSM with a Java application via the JCE provider and hitting DataException: The input data to the cryptographic operation was invalid, the key attributes are usually not the problem. More likely culprits:

• Padding/mode mismatch: AES requires explicit mode and padding in the cipher spec (e.g. AES/CBC/PKCS5Padding vs AES/CBC/NoPadding)
• Missing IV: CBC mode requires an IV that matches what was used during encryption
• Data encoding: passing base64 or hex-encoded data when raw bytes are expected

Also double-check that the user your JCE integration authenticates as actually has access to the key — if the key is owned by a service account and not shared with the authenticating user, the operation will fail in ways that don't always make the ownership issue obvious.

Quick Reference

# Start interactive CLI
sudo /opt/cloudhsm/bin/cloudhsm-cli interactive

# Login / Logout
login --username myuser --role crypto-user
login --username admin --role admin
logout

# Cluster
cluster hsm-info

# Users
user list
user create --username jdoe --role crypto-user
user change-password --username jdoe --role crypto-user
user delete --username jdoe --role crypto-user

# Keys
key list
key list --starting-token 10
key list --verbose
key list --verbose --filter attr.label=my_key_label
key share --filter attr.label=my_key_label --username jdoe --role crypto-user

# Find HSM IPs (outside the CLI)
cat /opt/cloudhsm/etc/cloudhsm-cli.cfg
aws cloudhsmv2 describe-clusters --region us-east-1