# The cluster category in CloudHSM CLI cluster 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 activate 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 hsm-info 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 mtls 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 deregister-trust-anchor 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 get-enforcement 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 list-trust-anchors 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 register-trust-anchor 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 set-enforcement 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)