# AWS CloudHSM Management Utility (CMU) The **cloudhsm\$1mgmt\$1util** command line tool helps crypto officers manage users in the hardware security modules (HSMs) in AWS CloudHSM clusters. The AWS CloudHSM Management Utility (CMU) includes tools that create, delete, and list users, and change user passwords. The CMU and Key Management Utility (KMU) are part of [the Client SDK 3 suite](choose-client-sdk.md). Client SDK 3 and its related command line tools (Key Management Utility and CloudHSM Management Utility) are only available in the HSM type *hsm1.medium*. cloudhsm\$1mgmt\$1util also includes commands that allow crypto users (CUs) to share keys and get and set key attributes. These commands complement the key management commands in the primary key management tool, [key\$1mgmt\$1util](key_mgmt_util.md). For a quick start, see [Getting started with AWS CloudHSM Management Utility (CMU)](cloudhsm_mgmt_util-getting-started.md). For detailed information about the cloudhsm\$1mgmt\$1util commands and examples of using the commands, see [Reference for AWS CloudHSM Management Utility commands](cloudhsm_mgmt_util-reference.md). **Topics** + [Supported platforms](cmu-support.md) + [Getting started](cloudhsm_mgmt_util-getting-started.md) + [Install the client (Linux)](cmu-install-and-configure-client-linux.md) + [Install the client (Windows)](cmu-install-and-configure-client-win.md) + [Reference](cloudhsm_mgmt_util-reference.md) # Supported platforms for AWS CloudHSM Management Utility This topic describes the Linux and Windows platforms that the AWS CloudHSM Management Utility (CMU) supports. ## Linux support + Amazon Linux + Amazon Linux 2 + CentOS 6.10\$1 + CentOS 7.3\$1 + CentOS 8 + Red Hat Enterprise Linux (RHEL) 6.10\$1 + Red Hat Enterprise Linux (RHEL) 7.9\$1 + Red Hat Enterprise Linux (RHEL) 8 + Ubuntu 16.04 LTS + Ubuntu 18.04 LTS ## Windows support + Microsoft Windows Server 2012 + Microsoft Windows Server 2012 R2 + Microsoft Windows Server 2016 + Microsoft Windows Server 2019 # Getting started with AWS CloudHSM Management Utility (CMU) AWS CloudHSM Management Utility (CMU) enables you to manage hardware security module (HSM) users. Use this topic to get started with basic HSM user management tasks, such as creating users, listing users, and connecting CMU to the cluster. 1. To use CMU, you must first use the configure tool to update the local CMU configuration with the `--cmu` parameter and an IP address from one of the HSMs in your cluster. Do this each time you use CMU to ensure you're managing HSM users on every HSM in the cluster. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure --cmu ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" --cmu ``` ------ 1. Use the following command to start the CLI in interactive mode. ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\cloudhsm_mgmt_util.exe" C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_mgmt_util.cfg ``` ------ Output should be similar to the following depending on how many HSMs you have. ``` Connecting to the server(s), it may take time depending on the server(s) load, please wait... Connecting to server '10.0.2.9': hostname '10.0.2.9', port 2225... Connected to server '10.0.2.9': hostname '10.0.2.9', port 2225. Connecting to server '10.0.3.11': hostname '10.0.3.11', port 2225... Connected to server '10.0.3.11': hostname '10.0.3.11', port 2225. Connecting to server '10.0.1.12': hostname '10.0.1.12', port 2225... Connected to server '10.0.1.12': hostname '10.0.1.12', port 2225. ``` The prompt changes to `aws-cloudhsm>` when cloudhsm\$1mgmt\$1util is running. 1. Use the **loginHSM** command to log in to the cluster. Any type user can use this command to log in to the cluster. The command in the following example logs in *admin*, which is the default [crypto officer (CO)](understanding-users-cmu.md). You set this user's password when you activated the cluster. You can use the `-hpswd` parameter to hide your password. ``` aws-cloudhsm>loginHSM CO admin -hpswd ``` The system prompts you for your password. You enter the password, the system hides the password, and the output shows that the command was successful and that the you have connected to all the HSMs on the cluster. ``` Enter password: loginHSM success on server 0(10.0.2.9) loginHSM success on server 1(10.0.3.11) loginHSM success on server 2(10.0.1.12) ``` 1. Use **listUsers** to list all the users on the cluster. ``` aws-cloudhsm>listUsers ``` CMU lists all the users on the cluster. ``` Users on server 0(10.0.2.9): Number of users found:2 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 CO admin NO 0 NO 2 AU app_user NO 0 NO Users on server 1(10.0.3.11): Number of users found:2 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 CO admin NO 0 NO 2 AU app_user NO 0 NO Users on server 2(10.0.1.12): Number of users found:2 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 CO admin NO 0 NO 2 AU app_user NO 0 NO ``` 1. Use **createUser** to create a CU user named **example\$1user** with a password of **password1**. You use CU users in your applications to perform cryptographic and key management operations. You can create CU users because in step 3 you logged in as a CO user. Only CO users can perform user management tasks with CMU, such as creating and deleting users and changing the passwords of other users. ``` aws-cloudhsm>createUser CU example_user password1 ``` CMU prompts you about the create user operation. ``` *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)? ``` 1. To create the CU user **example\$1user**, type **y**. 1. Use **listUsers** to list all the users on the cluster. ``` aws-cloudhsm>listUsers ``` CMU lists all the users on the cluster, including the new CU user you just created. ``` Users on server 0(10.0.2.9): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 CO admin NO 0 NO 2 AU app_user NO 0 NO 3 CU example_user NO 0 NO Users on server 1(10.0.3.11): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 CO admin NO 0 NO 2 AU app_user NO 0 NO 3 CU example_user NO 0 NO Users on server 2(10.0.1.12): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 CO admin NO 0 NO 2 AU app_user NO 0 NO 3 CU example_user NO 0 NO ``` 1. Use the **logoutHSM** command to log out of the HSMs. ``` aws-cloudhsm>logoutHSM logoutHSM success on server 0(10.0.2.9) logoutHSM success on server 1(10.0.3.11) logoutHSM success on server 2(10.0.1.12) ``` 1. Use the **quit** command to stop cloudhsm\$1mgmt\$1util. ``` aws-cloudhsm>quit disconnecting from servers, please wait... ``` # Install and configure the AWS CloudHSM client for CMU (Linux) To interact with the hardware security module (HSM) in your AWS CloudHSM cluster using the cloudhsm\$1mgmt\$1util (CMU), you need the AWS CloudHSM client software for Linux. You should install it on the Linux Amazon EC2 client instance that you created previously. You can also install a client if you are using Windows. For more information, see [Install and configure the AWS CloudHSM client for CMU (Windows)](cmu-install-and-configure-client-win.md). **Topics** + [Step 1. Install the AWS CloudHSM client and command line tools](#cmu-install-client) + [Step 2. Edit the client configuration](#cmu-edit-client-configuration) ## Step 1. Install the AWS CloudHSM client and command line tools Connect to your client instance and run the following commands to download and install the AWS CloudHSM client and command line tools. ------ #### [ Amazon Linux ] ``` wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-latest.el6.x86_64.rpm ``` ``` sudo yum install ./cloudhsm-client-latest.el6.x86_64.rpm ``` ------ #### [ Amazon Linux 2 ] ``` wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-latest.el7.x86_64.rpm ``` ``` sudo yum install ./cloudhsm-client-latest.el7.x86_64.rpm ``` ------ #### [ CentOS 7 ] ``` sudo yum install wget ``` ``` wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-latest.el7.x86_64.rpm ``` ``` sudo yum install ./cloudhsm-client-latest.el7.x86_64.rpm ``` ------ #### [ CentOS 8 ] ``` sudo yum install wget ``` ``` wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-latest.el8.x86_64.rpm ``` ``` sudo yum install ./cloudhsm-client-latest.el8.x86_64.rpm ``` ------ #### [ RHEL 7 ] ``` sudo yum install wget ``` ``` wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-latest.el7.x86_64.rpm ``` ``` sudo yum install ./cloudhsm-client-latest.el7.x86_64.rpm ``` ------ #### [ RHEL 8 ] ``` sudo yum install wget ``` ``` wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-latest.el8.x86_64.rpm ``` ``` sudo yum install ./cloudhsm-client-latest.el8.x86_64.rpm ``` ------ #### [ Ubuntu 16.04 LTS ] ``` wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client_latest_amd64.deb ``` ``` sudo apt install ./cloudhsm-client_latest_amd64.deb ``` ------ #### [ Ubuntu 18.04 LTS ] ``` wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-client_latest_u18.04_amd64.deb ``` ``` sudo apt install ./cloudhsm-client_latest_u18.04_amd64.deb ``` ------ ## Step 2. Edit the client configuration Before you can use the AWS CloudHSM client to connect to your cluster, you must edit the client configuration. **To edit the client configuration** 1. If installing Client SDK 3 on cloudhsm\$1mgmt\$1util, complete the following steps to ensure all the nodes in the cluster are synced. 1. Run **configure -a ****. 1. Restart the client service. 1. Run **configure -m**. 1. Copy your issuing certificate—[the one that you used to sign the cluster's certificate](initialize-cluster.md#sign-csr)—to the following location on the client instance: `/opt/cloudhsm/etc/customerCA.crt`. You need instance root user permissions on the client instance to copy your certificate to this location. 1. Use the following [configure](configure-tool.md) command to update the configuration files for the AWS CloudHSM client and command line tools, specifying the IP address of the HSM in your cluster. To get the HSM's IP address, view your cluster in the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), or run the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** AWS CLI command. In the command's output, the HSM's IP address is the value of the `EniIp` field. If you have more than one HSM, choose the IP address for any of the HSMs; it doesn't matter which one. ``` sudo /opt/cloudhsm/bin/configure -a Updating server config in /opt/cloudhsm/etc/cloudhsm_client.cfg Updating server config in /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` 1. Go to [Activate the cluster in AWS CloudHSM](activate-cluster.md). # Install and configure the AWS CloudHSM client for CMU (Windows) To work with a hardware security module (HSM) in your AWS CloudHSM cluster on Windows using the cloudhsm\$1mgmt\$1util (CMU), you need the AWS CloudHSM client software for Windows. You should install it on the Windows Server instance that you created previously. **Note** If you are updating the client, existing configuration files from previous installations are *not* overwritten. The AWS CloudHSM client installer for Windows automatically registers the Cryptography API: Next Generation (CNG) and Key Storage Provider (KSP). To uninstall the client, run the installer again and follow the uninstall instructions. If you are using Linux, you can install the Linux client. For more information, see [Install and configure the AWS CloudHSM client for CMU (Linux)](cmu-install-and-configure-client-linux.md). **To install (or update) the latest Windows client and command line tools** 1. Connect to your Windows Server instance. 1. Download the [AWSCloudHSMClient-latest.msi installer](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMClient-latest.msi). 1. If installing Client SDK 3 on cloudhsm\$1mgmt\$1util, complete the following steps to ensure all the nodes in the cluster are synced. 1. Run **configure.exe -a ****. 1. Restart the client service. 1. Run **configure.exe -m**. 1. Go to your download location and run the installer (**AWSCloudHSMClient-latest.msi**) with administrative privilege. 1. Follow the installer instructions, then choose **Close** after the installer has finished. 1. Copy your self-signed issuing certificate—[the one that you used to sign the cluster certificate](initialize-cluster.md#sign-csr)—to the `C:\ProgramData\Amazon\CloudHSM` folder. 1. Run the following command to update your configuration files. Be sure to stop and start the client during reconfiguration if you are updating it: ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" -a ``` 1. Go to [Activate the cluster in AWS CloudHSM](activate-cluster.md). # Reference for AWS CloudHSM Management Utility commands The AWS CloudHSM cloudhsm\$1mgmt\$1util command line tool helps crypto officers manage users in the hardware security modules (HSMs) in the AWS CloudHSM cluster. It also includes commands that allow crypto users (CUs) to share keys, and get and set key attributes. These commands complement the primary key management commands in the [key\$1mgmt\$1util](key_mgmt_util.md) command line tool. For a quick start, see [Getting started with AWS CloudHSM Management Utility (CMU)](cloudhsm_mgmt_util-getting-started.md). Before you run any cloudhsm\$1mgmt\$1util command, you must start cloudhsm\$1mgmt\$1util and log in to the HSM. Be sure that you log in with the user account type that can run the commands you plan to use. To list all cloudhsm\$1mgmt\$1util commands, run the following command: ``` aws-cloudhsm> help ``` To get the syntax for a cloudhsm\$1mgmt\$1util command, run the following command: ``` aws-cloudhsm> help ``` **Note** Use the syntax as per the documentation. While the built-in software help may provide additional options, these should not be considered supported and should not be utilized in production code. To run a command, enter the command name, or enough of the name to distinguish it from the names of other cloudhsm\$1mgmt\$1util commands. For example, to get a list of users on the HSMs, enter **listUsers** or **listU**. ``` aws-cloudhsm> listUsers ``` To end your cloudhsm\$1mgmt\$1util session, run the following command: ``` aws-cloudhsm> quit ``` For help interpreting the key attributes, see the [AWS CloudHSM key attribute reference for KMU](key-attribute-table.md). The following topics describe commands in cloudhsm\$1mgmt\$1util. **Note** Some commands in key\$1mgmt\$1util and cloudhsm\$1mgmt\$1util have the same names. However, the commands typically have different syntax, different output, and slightly different functionality. | Command | Description | User Type | | --- | --- | --- | | [changePswd](cloudhsm_mgmt_util-changePswd.md) | Changes the passwords of users on the HSMs. Any user can change their own password. COs can change anyone's password. | CO | | [createUser](cloudhsm_mgmt_util-createUser.md) | Creates users of all types on the HSMs. | CO | | [deleteUser](cloudhsm_mgmt_util-deleteUser.md) | Deletes users of all types from the HSMs. | CO | | [findAllKeys](cloudhsm_mgmt_util-findAllKeys.md) | Gets the keys that a user owns or shares. Also gets a hash of the key ownership and sharing data for all keys on each HSM. | CO, AU | | [getAttribute](cloudhsm_mgmt_util-getAttribute.md) | Gets an attribute value for an AWS CloudHSM key and writes it to a file or stdout (standard output). | CU | | [getHSMInfo](cloudhsm_mgmt_util-getHSMInfo.md) | Gets information about the hardware on which an HSM is running. | All. Login is not required. | | [getKeyInfo](cloudhsm_mgmt_util-getKeyInfo.md) | Gets owners, shared users, and the quorum authentication status of a key. | All. Login is not required. | | [info](cloudhsm_mgmt_util-info.md) | Gets information about an HSM, including the IP address, hostname, port, and current user. | All. Login is not required. | | [listUsers](cloudhsm_mgmt_util-listUsers.md) | Gets the users in each of the HSMs, their user type and ID, and other attributes. | All. Login is not required. | | [loginHSM and logoutHSM](cloudhsm_mgmt_util-loginLogout.md) | Log in and log out of an HSM. | All. | | [quit](cloudhsm_mgmt_util-quit.md) | Quits cloudhsm\$1mgmt\$1util. | All. Login is not required. | | [server](cloudhsm_mgmt_util-server.md) | Enters and exits server mode on an HSM. | All. | | [registerQuorumPubKey](cloudhsm_mgmt_util-registerQuorumPubKey.md) | Associates an HSM user with an asymmetric RSA-2048 key pair. | CO | | [setAttribute](cloudhsm_mgmt_util-setAttribute.md) | Changes the values of the label, encrypt, decrypt, wrap, and unwrap attributes of an existing key. | CU | | [shareKey](cloudhsm_mgmt_util-shareKey.md) | Shares an existing key with other users. | CU | | [syncKey](cloudhsm_mgmt_util-syncKey.md) | Syncs a key across cloned AWS CloudHSM clusters. | CU, CO | | [syncUser](cloudhsm_mgmt_util-syncUser.md) | Syncs a user across cloned AWS CloudHSM clusters. | CO | # Change a user's password using CMU Use the **changePswd** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util (CMU) to change the password of an existing user on the hardware security modules (HSM) in the AWS CloudHSM cluster. Any user can change their own password. In addition, Crypto officers (COs and PCOs) can change the password of another CO or crypto user (CU). You do not need to enter the current password to make the change. **Note** You cannot change the password of a user who is currently logged into the AWS CloudHSM client or key\$1mgmt\$1util. ## To troubleshoot changePswd Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following users can run this command. + Crypto officers (CO) + Crypto users (CU) ## Syntax Enter the arguments in the order specified in the syntax diagram. Use the `-hpswd` parameter to mask your password. To enable two-factor authentication (2FA) for a CO user, use the `-2fa` parameter and include a file path. For more information, see [Arguments](#changePswd-params). ``` changePswd [-2fa ] ``` ## Examples The following examples show how to use **changePassword** to reset the password for the current user or any other user in your HSMs. **Example : Change your password** Any user on the HSMs can use **changePswd** to change their own password. Before you change the password, use [info](cloudhsm_mgmt_util-info.md) to get information about each of the HSMs in the cluster, including the username and the user type of the logged in user. The following output shows that Bob is currently logged in as a crypto user(CU). ``` aws-cloudhsm> info server 0 Id Name Hostname Port State Partition LoginState 0 10.1.9.193 10.1.9.193 2225 Connected hsm-jqici4covtv Logged in as 'bob(CU)' aws-cloudhsm> info server 1 Id Name Hostname Port State Partition LoginState 1 10.1.10.7 10.1.10.7 2225 Connected hsm-ogi3sywxbqx Logged in as 'bob(CU)' ``` To change password, Bob runs **changePswd** followed with the user type, username, and a new password. ``` aws-cloudhsm> changePswd CU bob newPassword *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)?y Changing password for bob(CU) on 2 nodes ``` **Example : Change the password of another user** You must be a CO or PCO to change the password of another CO, or CU on the HSMs. Before you change the password for another user, use the [info](cloudhsm_mgmt_util-info.md) command to confirm that your user type is either CO or PCO. The following output confirms that Alice, who is a CO, is currently logged in. ``` aws-cloudhsm>info server 0 Id Name Hostname Port State Partition LoginState 0 10.1.9.193 10.1.9.193 2225 Connected hsm-jqici4covtv Logged in as 'alice(CO)' aws-cloudhsm>info server 1 Id Name Hostname Port State Partition LoginState 0 10.1.10.7 10.1.10.7 2225 Connected hsm-ogi3sywxbqx Logged in as 'alice(CO)' ``` Alice wants to reset the password of another user, John. Before she changes the password, she uses the [listUsers](cloudhsm_mgmt_util-listUsers.md) command to verify John's user type. The following output lists John as a CO user. ``` aws-cloudhsm> listUsers Users on server 0(10.1.9.193): Number of users found:5 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU jane NO 0 NO 3 CU bob NO 0 NO 4 CU alice NO 0 NO 5 CO john NO 0 NO Users on server 1(10.1.10.7): Number of users found:5 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU jane NO 0 NO 3 CU bob NO 0 NO 4 CO alice NO 0 NO 5 CO john NO 0 NO ``` To change the password, Alice runs **changePswd** followed with John's user type, username, and a new password. ``` aws-cloudhsm>changePswd CO john newPassword *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)?y Changing password for john(CO) on 2 nodes ``` ## Arguments Enter the arguments in the order specified in the syntax diagram. Use the `-hpswd` parameter to mask your password. To enable 2FA for a CO user, use the `-2fa` parameter and include a file path. For more information about working with 2FA, see [Manage user 2FA](manage-2fa.md) ``` changePswd [-2fa ] ``` **** Specifies the current type of the user whose password you are changing. You cannot use **changePswd** to change the user type. Valid values are `CO`, `CU`, `PCO`, and `PRECO`. To get the user type, use [listUsers](cloudhsm_mgmt_util-listUsers.md). For detailed information about the user types on an HSM, see [HSM user types for AWS CloudHSM Management Utility](understanding-users-cmu.md). Required: Yes **** Specifies the user's friendly name. This parameter is not case-sensitive. You cannot use **changePswd** to change the user name. Required: Yes **** Specifies a new password for the user. Enter a string of 7 to 32 characters. This value is case sensitive. The password appears in plaintext when you type it. To hide your password, use the `-hpswd` parameter in place of the password and follow the prompts. Required: Yes **[-2fa ]** Specifies enabling 2FA for this CO user. To get the data necessary for setting up 2FA, include a path to a location in the file system with a file name after the `-2fa` parameter. For more information about working with 2FA, see [Manage user 2FA](manage-2fa.md). Required: No ## Related topics + [info](cloudhsm_mgmt_util-info.md) + [listUsers](cloudhsm_mgmt_util-listUsers.md) + [createUser](cloudhsm_mgmt_util-createUser.md) + [deleteUser](cloudhsm_mgmt_util-deleteUser.md) # Create an AWS CloudHSM user with CMU Use the **createUser** command in cloudhsm\$1mgmt\$1util (CMU) to create a user on the hardware security modules (HSM) in the AWS CloudHSM cluster. Only crypto officers (COs and PRECOs) can run this command. When the command succeeds, it creates the user in all HSMs in the cluster. ## To troubleshoot createUser If your HSM configuration is inaccurate, the user might not be created on all HSMs. To add the user to any HSMs in which it is missing, use the [syncUser](cloudhsm_mgmt_util-syncUser.md) or [createUser](#cloudhsm_mgmt_util-createUser) command only on the HSMs that are missing that user. To prevent configuration errors, run the [configure](configure-tool.md) tool with the `-m` option. Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following types of users can run this command. + Crypto officers (CO, PRECO) ## Syntax Enter the arguments in the order specified in the syntax diagram. Use the `-hpswd` parameter to mask your password. To create a CO user with two-factor authentication (2FA), use the `-2fa` parameter and include a file path. For more information, see [Arguments](#createUser-params). ``` createUser |-hpswd> [-2fa ] ``` ## Examples These examples show how to use **createUser** to create new users in your HSMs. **Example : Create a crypto officer** This example creates a crypto officer (CO) on the HSMs in a cluster. The first command uses [loginHSM](cloudhsm_mgmt_util-loginLogout.md) to log in to the HSM as a crypto officer. ``` aws-cloudhsm> loginHSM CO admin 735782961 loginHSM success on server 0(10.0.0.1) loginHSM success on server 1(10.0.0.2) loginHSM success on server 1(10.0.0.3) ``` The second command uses the **createUser** command to create `alice`, a new crypto officer on the HSM. The caution message explains that the command creates users on all of the HSMs in the cluster. But, if the command fails on any HSMs, the user will not exist on those HSMs. To continue, type `y`. The output shows that the new user was created on all three HSMs in the cluster. ``` aws-cloudhsm> createUser CO alice 391019314 *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)?Invalid option, please type 'y' or 'n' Do you want to continue(y/n)?y Creating User alice(CO) on 3 nodes ``` When the command completes, `alice` has the same permissions on the HSM as the `admin` CO user, including changing the password of any user on the HSMs. The final command uses the [listUsers](cloudhsm_mgmt_util-listUsers.md) command to verify that `alice` exists on all three HSMs on the cluster. The output also shows that `alice` is assigned user ID `3`.`.` You use the user ID to identify `alice` in other commands, such as [findAllKeys](cloudhsm_mgmt_util-findAllKeys.md). ``` aws-cloudhsm> listUsers Users on server 0(10.0.0.1): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PRECO admin YES 0 NO 2 AU app_user NO 0 NO 3 CO alice NO 0 NO Users on server 1(10.0.0.2): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PRECO admin YES 0 NO 2 AU app_user NO 0 NO 3 CO alice NO 0 NO Users on server 1(10.0.0.3): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PRECO admin YES 0 NO 2 AU app_user NO 0 NO 3 CO alice NO 0 NO ``` **Example : Create a crypto user** This example creates a crypto user (CU), `bob`, on the HSM. Crypto users can create and manage keys, but they cannot manage users. After you type `y` to respond to the caution message, the output shows that `bob` was created on all three HSMs in the cluster. The new CU can log in to the HSM to create and manage keys. The command used a password value of `defaultPassword`. Later, `bob` or any CO can use the [changePswd](cloudhsm_mgmt_util-changePswd.md) command to change his password. ``` aws-cloudhsm> createUser CU bob defaultPassword *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)?Invalid option, please type 'y' or 'n' Do you want to continue(y/n)?y Creating User bob(CU) on 3 nodes ``` ## Arguments Enter the arguments in the order specified in the syntax diagram. Use the `-hpswd` parameter to mask your password. To create a CO user with 2FA enabled, use the `-2fa` parameter and include a file path. For more information about 2FA, see [Manage user 2FA](manage-2fa.md). ``` createUser |-hpswd> [-2fa ] ``` **** Specifies the type of user. This parameter is required. For detailed information about the user types on an HSM, see [HSM user types for AWS CloudHSM Management Utility](understanding-users-cmu.md). Valid values: + **CO**: Crypto officers can manage users, but they cannot manage keys. + **CU**: Crypto users can create an manage keys and use keys in cryptographic operations. The PRECO is converted to a CO when you assign a password during [HSM activation](activate-cluster.md). Required: Yes **** Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). You cannot change the name of a user after it is created. In cloudhsm\$1mgmt\$1util commands, the user type and password are case-sensitive, but the user name is not. Required: Yes **** Specifies a password for the user. Enter a string of 7 to 32 characters. This value is case-sensitive. The password appears in plaintext when you type it. To hide your password, use the `-hpswd` parameter in place of the password and follow the prompts. To change a user password, use [changePswd](cloudhsm_mgmt_util-changePswd.md). Any HSM user can change their own password, but CO users can change the password of any user (of any type) on the HSMs. Required: Yes **[-2fa ]** Specifies the creation of a CO user with 2FA enabled. To get the data necessary for setting up 2FA authentication, include a path to a location in the file system with a file name after the `-2fa` parameter. For more information about setting up and working with 2FA, see [Manage user 2FA](manage-2fa.md). Required: No ## Related topics + [listUsers](cloudhsm_mgmt_util-listUsers.md) + [deleteUser](cloudhsm_mgmt_util-deleteUser.md) + [syncUser](cloudhsm_mgmt_util-syncUser.md) + [changePswd](cloudhsm_mgmt_util-changePswd.md) # Delete an AWS CloudHSM user using CMU Use the **deleteUser** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util (CMU) to delete a user from the hardware security modules (HSM) in the AWS CloudHSM cluster. Only crypto officers (CO) can run this command. You cannot delete a user who is currently logged into an HSM. For more information about deleting users, see [How to Delete HSM Users](delete-user.md). **Tip** You can't delete crypto users (CU) that own keys. ## User type The following types of users can run this command. + CO ## Syntax Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` deleteUser ``` ## Example This example deletes a crypto officer (CO) from the HSMs in a cluster. The first command uses [listUsers](cloudhsm_mgmt_util-listUsers.md) to list all users on the HSMs. The output shows that user `3`, `alice`, is a CO on the HSMs. ``` aws-cloudhsm> listUsers Users on server 0(10.0.0.1): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU app_user NO 0 NO 3 CO alice NO 0 NO Users on server 1(10.0.0.2): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU app_user NO 0 NO 3 CO alice NO 0 NO Users on server 1(10.0.0.3): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU app_user NO 0 NO 3 CO alice NO 0 NO ``` The second command uses the **deleteUser** command to delete `alice` from the HSMs. The output shows that the command succeeded on all three HSMs in the cluster. ``` aws-cloudhsm> deleteUser CO alice Deleting user alice(CO) on 3 nodes deleteUser success on server 0(10.0.0.1) deleteUser success on server 0(10.0.0.2) deleteUser success on server 0(10.0.0.3) ``` The final command uses the **listUsers** command to verify that `alice` is deleted from all three of the HSMs on the cluster. ``` aws-cloudhsm> listUsers Users on server 0(10.0.0.1): Number of users found:2 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU app_user NO 0 NO Users on server 1(10.0.0.2): Number of users found:2 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU app_user NO 0 NO Users on server 1(10.0.0.3): Number of users found:2 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU app_user NO 0 NO ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` deleteUser ``` **** Specifies the type of user. This parameter is required. You can't delete crypto users (CU) that own keys. Valid values are **CO**, **CU**. To get the user type, use [listUsers](cloudhsm_mgmt_util-listUsers.md). For detailed information about the user types on an HSM, see [HSM user types for AWS CloudHSM Management Utility](understanding-users-cmu.md). Required: Yes **** Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). You cannot change the name of a user after it is created. In cloudhsm\$1mgmt\$1util commands, the user type and password are case-sensitive, but the user name is not. Required: Yes ## Related topics + [listUsers](cloudhsm_mgmt_util-listUsers.md) + [createUser](cloudhsm_mgmt_util-createUser.md) + [syncUser](cloudhsm_mgmt_util-syncUser.md) + [changePswd](cloudhsm_mgmt_util-changePswd.md) # List the keys that an AWS CloudHSM crypto user owns using CMU Use the **findAllKeys** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util (CMU) to get the keys that a specified crypto user (CU) of AWS CloudHSM owns or shares. The command also returns a hash of the user data on each of the HSMs. You can use the hash to determine at a glance whether the users, key ownership, and key sharing data are the same on all HSMs in the cluster. In the output, the keys owned by the user are annotated by `(o)` and shared keys are annotated by `(s)`. **findAllKeys** returns public keys only when the specified CU owns the key, even though all CUs on the HSM can use any public key. This behavior is different from [findKey](key_mgmt_util-findKey.md) in key\$1mgmt\$1util, which returns public keys for all CU users. Only crypto officers (COs and PCOs) and appliance users (AUs) can run this command. Crypto users (CUs) can run the following commands: + [listUsers](cloudhsm_mgmt_util-listUsers.md) to find all users + [findKey](key_mgmt_util-findKey.md) in key\$1mgmt\$1util to find the keys that they can use + [getKeyInfo](key_mgmt_util-getKeyInfo.md) in key\$1mgmt\$1util to find the owner and shared users of a particular key they own or share Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following users can run this command. + Crypto officers (CO, PCO) + Appliance users (AU) ## Syntax Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` findAllKeys [] ``` ## Examples These examples show how to use `findAllKeys` to find all keys for a user and get a hash of key user information on each of the HSMs. **Example : Find the keys for a CU** This example uses **findAllKeys** to find the keys in the HSMs that user 4 owns and shares. The command uses a value of `0` for the second argument to suppress the hash value. Because it omits the optional file name, the command writes to stdout (standard output). The output shows that user 4 can use 6 keys: 8, 9, 17, 262162, 19, and 31. The output uses an `(s)` to indicate keys that are explicitly shared by the user. The keys that the user owns are indicated by an `(o)` and include symmetric and private keys that the user does not share, and public keys that are available to all crypto users. ``` aws-cloudhsm> findAllKeys 4 0 Keys on server 0(10.0.0.1): Number of keys found 6 number of keys matched from start index 0::6 8(s),9(s),17,262162(s),19(o),31(o) findAllKeys success on server 0(10.0.0.1) Keys on server 1(10.0.0.2): Number of keys found 6 number of keys matched from start index 0::6 8(s),9(s),17,262162(s),19(o),31(o) findAllKeys success on server 1(10.0.0.2) Keys on server 1(10.0.0.3): Number of keys found 6 number of keys matched from start index 0::6 8(s),9(s),17,262162(s),19(o),31(o) findAllKeys success on server 1(10.0.0.3) ``` **Example : Verify that user data is synchronized** This example uses **findAllKeys** to verify that all of the HSMs in the cluster contain the same users, key ownership, and key sharing values. To do this, it gets a hash of the key user data on each HSM and compares the hash values. To get the key hash, the command uses a value of `1` in the second argument. The optional file name is omitted, so the command writes the key hash to stdout. The example specifies user `6`, but the hash value will be the same for any user that owns or shares any of the keys on the HSMs. If the specified user does not own or share any keys, such as a CO, the command does not return a hash value. The output shows that the key hash is identical to both of the HSMs in the cluster. If one of the HSM had different users, different key owners, or different shared users, the key hash values would not be equal. ``` aws-cloudhsm> findAllKeys 6 1 Keys on server 0(10.0.0.1): Number of keys found 3 number of keys matched from start index 0::3 8(s),9(s),11,17(s) Key Hash: 55655676c95547fd4e82189a072ee1100eccfca6f10509077a0d6936a976bd49 findAllKeys success on server 0(10.0.0.1) Keys on server 1(10.0.0.2): Number of keys found 3 number of keys matched from start index 0::3 8(s),9(s),11(o),17(s) Key Hash: 55655676c95547fd4e82189a072ee1100eccfca6f10509077a0d6936a976bd49 findAllKeys success on server 1(10.0.0.2) ``` This command demonstrates that the hash value represents the user data for all keys on the HSM. The command uses the **findAllKeys** for user 3. Unlike user 6, who owns or shares just 3 keys, user 3 own or shares 17 keys, but the key hash value is the same. ``` aws-cloudhsm> findAllKeys 3 1 Keys on server 0(10.0.0.1): Number of keys found 17 number of keys matched from start index 0::17 6(o),7(o),8(s),11(o),12(o),14(o),262159(o),262160(o),17(s),262162(s),19(s),20(o),21(o),262177(o),262179(o),262180(o),262181(o) Key Hash: 55655676c95547fd4e82189a072ee1100eccfca6f10509077a0d6936a976bd49 findAllKeys success on server 0(10.0.0.1) Keys on server 1(10.0.0.2): Number of keys found 17 number of keys matched from start index 0::17 6(o),7(o),8(s),11(o),12(o),14(o),262159(o),262160(o),17(s),262162(s),19(s),20(o),21(o),262177(o),262179(o),262180(o),262181(o) Key Hash: 55655676c95547fd4e82189a072ee1100eccfca6f10509077a0d6936a976bd49 findAllKeys success on server 1(10.0.0.2) ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` findAllKeys [] ``` **** Gets all keys that the specified user owns or shares. Enter the user ID of a user on the HSMs. To find the user IDs of all users, use [listUsers](cloudhsm_mgmt_util-listUsers.md). All user IDs are valid, but `findAllKeys` returns keys only for crypto users (CUs). Required: Yes **** Includes (`1`) or excludes (`0`) a hash of the user ownership and sharing data for all keys in each HSM. When the `user id` argument represents a user who owns or shares keys, the key hash is populated. The key hash value is identical for all users who own or share keys on the HSM, even though they own and share different keys. However, when the `user id` represents a user who does not own or share any keys, such as a CO, the hash value is not populated. Required: Yes **** Writes the output to the specified file. Required: No Default: Stdout ## Related topics + [changePswd](cloudhsm_mgmt_util-changePswd.md) + [deleteUser](cloudhsm_mgmt_util-deleteUser.md) + [listUsers](cloudhsm_mgmt_util-listUsers.md) + [syncUser](cloudhsm_mgmt_util-syncUser.md) + [findKey](key_mgmt_util-findKey.md) in key\$1mgmt\$1util + [getKeyInfo](key_mgmt_util-getKeyInfo.md) in key\$1mgmt\$1util # Get an AWS CloudHSM key attribute value using CMU Use the **getAttribute** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util (CMU) to get one attribute value for a key from all hardware security modules (HSM) in the AWS CloudHSM cluster and writes it to stdout (standard output) or to a file. Only crypto users (CUs) can run this command. *Key attributes* are properties of a key. They include characteristics, like the key type, class, label, and ID, and values that represent actions that you can perform on the key, like encrypt, decrypt, wrap, sign, and verify. You can use **getAttribute** only on keys that you own and key that are shared with you. You can run this command or the [getAttribute](#cloudhsm_mgmt_util-getAttribute) command in key\$1mgmt\$1util, which writes one or all of the attribute values of a key to a file. To get a list of attributes and the constants that represent them, use the [listAttributes](key_mgmt_util-listAttributes.md) command. To change the attribute values of existing keys, use [setAttribute](key_mgmt_util-setAttribute.md) in key\$1mgmt\$1util and [setAttribute](cloudhsm_mgmt_util-setAttribute.md) in cloudhsm\$1mgmt\$1util. For help interpreting the key attributes, see the [AWS CloudHSM key attribute reference for KMU](key-attribute-table.md). Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following users can run this command. + Crypto users (CU) ## Syntax Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` getAttribute [] ``` ## Example This example gets the value of the extractable attribute for a key in the HSMs. You can use a command like this to determine whether you can export a key from the HSMs. The first command uses [listAttributes](cloudhsm_mgmt_util-listAttributes.md) to find the constant that represents the extractable attribute. The output shows that the constant for `OBJ_ATTR_EXTRACTABLE` is `354`. You can also find this information with descriptions of the attributes and their values in the [AWS CloudHSM key attribute reference for KMU](key-attribute-table.md). ``` aws-cloudhsm> listAttributes Following are the possible attribute values for getAttribute: OBJ_ATTR_CLASS = 0 OBJ_ATTR_TOKEN = 1 OBJ_ATTR_PRIVATE = 2 OBJ_ATTR_LABEL = 3 OBJ_ATTR_TRUSTED = 134 OBJ_ATTR_KEY_TYPE = 256 OBJ_ATTR_ID = 258 OBJ_ATTR_SENSITIVE = 259 OBJ_ATTR_ENCRYPT = 260 OBJ_ATTR_DECRYPT = 261 OBJ_ATTR_WRAP = 262 OBJ_ATTR_UNWRAP = 263 OBJ_ATTR_SIGN = 264 OBJ_ATTR_VERIFY = 266 OBJ_ATTR_DERIVE = 268 OBJ_ATTR_LOCAL = 355 OBJ_ATTR_MODULUS = 288 OBJ_ATTR_MODULUS_BITS = 289 OBJ_ATTR_PUBLIC_EXPONENT = 290 OBJ_ATTR_VALUE_LEN = 353 OBJ_ATTR_EXTRACTABLE = 354 OBJ_ATTR_NEVER_EXTRACTABLE = 356 OBJ_ATTR_ALWAYS_SENSITIVE = 357 OBJ_ATTR_DESTROYABLE = 370 OBJ_ATTR_KCV = 371 OBJ_ATTR_WRAP_WITH_TRUSTED = 528 OBJ_ATTR_WRAP_TEMPLATE = 1073742353 OBJ_ATTR_UNWRAP_TEMPLATE = 1073742354 OBJ_ATTR_ALL = 512 ``` The second command uses **getAttribute** to get the value of the extractable attribute for the key with key handle `262170` in the HSMs. To specify the extractable attribute, the command uses `354`, the constant that represents the attribute. Because the command does not specify a file name, **getAttribute** writes the output to stdout. The output shows that the value of the extractable attribute is 1 on all of the HSM. This value indicates that the owner of the key can export it. When the value is 0 (0x0), it cannot be exported from the HSMs. You set the value of the extractable attribute when you create a key, but you cannot change it. ``` aws-cloudhsm> getAttribute 262170 354 Attribute Value on server 0(10.0.1.10): OBJ_ATTR_EXTRACTABLE 0x00000001 Attribute Value on server 1(10.0.1.12): OBJ_ATTR_EXTRACTABLE 0x00000001 Attribute Value on server 2(10.0.1.7): OBJ_ATTR_EXTRACTABLE 0x00000001 ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` getAttribute [] ``` **** Specifies the key handle of the target key. You can specify only one key in each command. To get the key handle of a key, use [findKey](key_mgmt_util-findKey.md) in key\$1mgmt\$1util. You must own the specified key or it must be shared with you. To find the users of a key, use [getKeyInfo](key_mgmt_util-getKeyInfo.md) in key\$1mgmt\$1util. Required: Yes **** Identifies the attribute. Enter a constant that represents an attribute, or `512`, which represents all attributes. For example, to get the key type, enter `256`, which is the constant for the `OBJ_ATTR_KEY_TYPE` attribute. To list the attributes and their constants, use [listAttributes](key_mgmt_util-listAttributes.md). For help interpreting the key attributes, see the [AWS CloudHSM key attribute reference for KMU](key-attribute-table.md). Required: Yes **** Writes the output to the specified file. Enter a file path. If the specified file exists, **getAttribute** overwrites the file without warning. Required: No Default: Stdout ## Related topics + [getAttribute](key_mgmt_util-getAttribute.md) in key\$1mgmt\$1util + [listAttributes](cloudhsm_mgmt_util-listAttributes.md) + [setAttribute](cloudhsm_mgmt_util-setAttribute.md) in cloudhsm\$1mgmt\$1util + [setAttribute](key_mgmt_util-setAttribute.md) in key\$1mgmt\$1util + [Key Attribute Reference](key-attribute-table.md) # Get hardware information for each HSM in an AWS CloudHSM cluster with CMU Use the **getHSMInfo** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util (CMU) to get information about the hardware on which each hardware security module (HSM) runs, including the model, serial number, FIPS state, memory, temperature, and the version numbers of the hardware and firmware. The information also includes the server ID that cloudhsm\$1mgmt\$1util uses to refer to the HSM. Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following types of users can run this command. + All users. You do not have to be logged in to run this command. ## Syntax This command has no parameters. ``` getHSMInfo ``` ## Example This example uses **getHSMInfo** to get information about the HSMs in the cluster. ``` aws-cloudhsm> getHSMInfo Getting HSM Info on 3 nodes *** Server 0 HSM Info *** Label :cavium Model :NITROX-III CNN35XX-NFBE Serial Number :3.0A0101-ICM000001 HSM Flags :0 FIPS state :2 [FIPS mode with single factor authentication] Manufacturer ID : Device ID :10 Class Code :100000 System vendor ID :177D SubSystem ID :10 TotalPublicMemory :560596 FreePublicMemory :294568 TotalPrivateMemory :0 FreePrivateMemory :0 Hardware Major :3 Hardware Minor :0 Firmware Major :2 Firmware Minor :03 Temperature :56 C Build Number :13 Firmware ID :xxxxxxxxxxxxxxx ... ``` ## Related topics + [info](cloudhsm_mgmt_util-info.md) # Get AWS CloudHSM user info about a key using CMU Use the **getKeyInfo** command in the AWS CloudHSM key\$1mgmt\$1util (KMU) to return the hardware security module (HSM) user IDs of users who can use the key, including the owner and crypto users (CU) with whom the key is shared. When quorum authentication is enabled on a key, **getKeyInfo** also returns the number of users who must approve cryptographic operations that use the key. You can run **getKeyInfo** only on keys that you own and keys that are shared with you. When you run **getKeyInfo** on public keys, **getKeyInfo** returns only the key owner, even though all users of the HSM can use the public key. To find the HSM user IDs of users in your HSMs, use [listUsers](key_mgmt_util-listUsers.md). To find the keys for a particular user, use [findKey](key_mgmt_util-findKey.md) `-u` in key\$1mgmt\$1util. Crypto officers can use [findAllKeys](cloudhsm_mgmt_util-findAllKeys.md) in cloudhsm\$1mgmt\$1util. You own the keys that you create. You can share a key with other users when you create it. Then, to share or unshare an existing key, use [shareKey](cloudhsm_mgmt_util-shareKey.md) in cloudhsm\$1mgmt\$1util. Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following types of users can run this command. + Crypto users (CU) ## Syntax ``` getKeyInfo -k [] ``` ## Examples These examples show how to use **getKeyInfo** to get information about the users of a key. **Example : Get the users for an asymmetric key** This command gets the users who can use the AES (asymmetric) key with key handle `262162`. The output shows that user 3 owns the key and has shares it with users 4 and 6. Only users 3, 4, and 6 can run **getKeyInfo** on key 262162. ``` aws-cloudhsm>getKeyInfo 262162 Key Info on server 0(10.0.0.1): Token/Flash Key, Owned by user 3 also, shared to following 2 user(s): 4 6 Key Info on server 1(10.0.0.2): Token/Flash Key, Owned by user 3 also, shared to following 2 user(s): 4 6 ``` **Example : Get the users for a symmetric key pair** These commands use **getKeyInfo** to get the users who can use the keys in an [ECC (symmetric) key pair](key_mgmt_util-genSymKey.md). The public key has key handle `262179`. The private key has key handle `262177`. When you run **getKeyInfo** on the private key (`262177`), it returns the key owner (3) and crypto users (CUs) 4, with whom the key is shared. ``` aws-cloudhsm>getKeyInfo -k 262177 Key Info on server 0(10.0.0.1): Token/Flash Key, Owned by user 3 also, shared to following 1 user(s): 4 Key Info on server 1(10.0.0.2): Token/Flash Key, Owned by user 3 also, shared to following 1 user(s): 4 ``` When you run **getKeyInfo** on the public key (`262179`), it returns only the key owner, user `3`. ``` aws-cloudhsm>getKeyInfo -k 262179 Key Info on server 0(10.0.3.10): Token/Flash Key, Owned by user 3 Key Info on server 1(10.0.3.6): Token/Flash Key, Owned by user 3 ``` To confirm that user 4 can use the public key (and all public keys on the HSM), use the `-u` parameter of [findKey](key_mgmt_util-findKey.md) in key\$1mgmt\$1util. The output shows that user 4 can use both the public (`262179`) and private (`262177`) key in the key pair. User 4 can also use all other public keys and any private keys that they have created or that have been shared with them. ``` Command: findKey -u 4 Total number of keys present 8 number of keys matched from start index 0::7 11, 12, 262159, 262161, 262162, 19, 20, 21, 262177, 262179 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS ``` **Example : Get the quorum authentication value (m\$1value) for a key** This example shows how to get the `m_value` for a key. The m\$1value is the number of users in the quorum who must approve any cryptographic operations that use the key and operations to share the unshare the key. When quorum authentication is enabled on a key, a quorum of users must approve any cryptographic operations that use the key. To enable quorum authentication and set the quorum size, use the `-m_value` parameter when you create the key. This command uses [genSymKey](key_mgmt_util-genSymKey.md) to create a 256-bit AES key that is shared with user 4. It uses the `m_value` parameter to enable quorum authentication and set the quorum size to two users. The number of users must be large enough to provide the required approvals. The output shows that the command created key 10. ``` Command: genSymKey -t 31 -s 32 -l aes256m2 -u 4 -m_value 2 Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Created. Key Handle: 10 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS ``` This command uses **getKeyInfo** in cloudhsm\$1mgmt\$1util to get information about the users of key `10`. The output shows that the key is owned by user `3` and shared with user `4`. It also shows that a quorum of two users must approve every cryptographic operation that uses the key. ``` aws-cloudhsm>getKeyInfo 10 Key Info on server 0(10.0.0.1): Token/Flash Key, Owned by user 3 also, shared to following 1 user(s): 4 2 Users need to approve to use/manage this key Key Info on server 1(10.0.0.2): Token/Flash Key, Owned by user 3 also, shared to following 1 user(s): 4 2 Users need to approve to use/manage this key ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` getKeyInfo -k ``` **** Specifies the key handle of one key in the HSM. Enter the key handle of a key that you own or share. This parameter is required. Required: Yes **** Writes the output to the specified file, instead of stdout. If the file exists, the command overwrites it without warning. Required: No Default: stdout ## Related topics + [getKeyInfo](key_mgmt_util-getKeyInfo.md) in key\$1mgmt\$1util + [findKey](key_mgmt_util-findKey.md) in key\$1mgmt\$1util + [findAllKeys](cloudhsm_mgmt_util-findAllKeys.md) in cloudhsm\$1mgmt\$1util + [listUsers](cloudhsm_mgmt_util-listUsers.md) + [shareKey](cloudhsm_mgmt_util-shareKey.md) # Get information for each HSM in an AWS CloudHSM cluster using CMU Use the **info** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util (CMU) to get information about each of the hardware security modules (HSM) in the AWS CloudHSM cluster, including the host name, port, IP address and the name and type of the user who is logged in to cloudhsm\$1mgmt\$1util on the HSM. Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following types of users can run this command. + All users. You do not have to be logged in to run this command. ## Syntax Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` info server ``` ## Example This example uses **info** to get information about an HSM in the cluster. The command uses 0 to refer to the first HSM in the cluster. The output shows the IP address, port, and the type and name of the current user. ``` aws-cloudhsm> info server 0 Id Name Hostname Port State Partition LoginState 0 10.0.0.1 10.0.0.1 2225 Connected hsm-udw0tkfg1ab Logged in as 'testuser(CU)' ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` info server ``` **** Specifies the server ID of the HSM. The HSMs are assigned ordinal numbers that represent the order in which they are added to the cluster, beginning with 0. To find the server ID of an HSM, use getHSMInfo. Required: Yes ## Related topics + [getHSMInfo](cloudhsm_mgmt_util-getHSMInfo.md) + [loginHSM and logoutHSM](cloudhsm_mgmt_util-loginLogout.md) # List the attributes of an AWS CloudHSM key using CMU Use the **listAttributes** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util (CMU) to list the attributes of an AWS CloudHSM key and the constants that represent them. You use these constants to identify the attributes in [getAttribute](cloudhsm_mgmt_util-getAttribute.md) and [setAttribute](cloudhsm_mgmt_util-setAttribute.md) commands. For help interpreting the key attributes, see the [AWS CloudHSM key attribute reference for KMU](key-attribute-table.md). Before you run any key\$1mgmt\$1util command, you must [start key\$1mgmt\$1util](key_mgmt_util-setup.md#key_mgmt_util-start) and [log in](key_mgmt_util-log-in.md) to the HSM as a crypto user (CU). ## User type The following users can run this command. + All users. You do not have to be logged in to run this command. ## Syntax ``` listAttributes [-h] ``` ## Example This command lists the key attributes that you can get and change in key\$1mgmt\$1util and the constants that represent them. For help interpreting the key attributes, see the [AWS CloudHSM key attribute reference for KMU](key-attribute-table.md). To represent all attributes, use `512`. ``` Command: listAttributes Description =========== The following are all of the possible attribute values for getAttribute. OBJ_ATTR_CLASS = 0 OBJ_ATTR_TOKEN = 1 OBJ_ATTR_PRIVATE = 2 OBJ_ATTR_LABEL = 3 OBJ_ATTR_TRUSTED = 134 OBJ_ATTR_KEY_TYPE = 256 OBJ_ATTR_ID = 258 OBJ_ATTR_SENSITIVE = 259 OBJ_ATTR_ENCRYPT = 260 OBJ_ATTR_DECRYPT = 261 OBJ_ATTR_WRAP = 262 OBJ_ATTR_UNWRAP = 263 OBJ_ATTR_SIGN = 264 OBJ_ATTR_VERIFY = 266 OBJ_ATTR_DERIVE = 268 OBJ_ATTR_LOCAL = 355 OBJ_ATTR_MODULUS = 288 OBJ_ATTR_MODULUS_BITS = 289 OBJ_ATTR_PUBLIC_EXPONENT = 290 OBJ_ATTR_VALUE_LEN = 353 OBJ_ATTR_EXTRACTABLE = 354 OBJ_ATTR_NEVER_EXTRACTABLE = 356 OBJ_ATTR_ALWAYS_SENSITIVE = 357 OBJ_ATTR_DESTROYABLE = 370 OBJ_ATTR_KCV = 371 OBJ_ATTR_WRAP_WITH_TRUSTED = 528 OBJ_ATTR_WRAP_TEMPLATE = 1073742353 OBJ_ATTR_UNWRAP_TEMPLATE = 1073742354 OBJ_ATTR_ALL = 512 ``` ## Parameters **-h** Displays help for the command. Required: Yes ## Related topics + [getAttribute](cloudhsm_mgmt_util-getAttribute.md) + [setAttribute](cloudhsm_mgmt_util-setAttribute.md) + [Key Attribute Reference](key-attribute-table.md) # List all AWS CloudHSM users using CMU Use the **listUsers** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util to get the users in each of the hardware security modules (HSM), along with their user type and other attributes. All types of users can run this command. You do not even need to be logged in to cloudhsm\$1mgmt\$1util to run this command. Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for 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 This command has no parameters. ``` listUsers ``` ## Example This command lists the users on each of the HSMs in the cluster and displays their attributes. You can use the `User ID` attribute to identify users in other commands, such as **deleteUser**, **changePswd**, and **findAllKeys**. ``` aws-cloudhsm> listUsers Users on server 0(10.0.0.1): Number of users found:6 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU app_user NO 0 NO 3 CU crypto_user1 NO 0 NO 4 CU crypto_user2 NO 0 NO 5 CO officer1 YES 0 NO 6 CO officer2 NO 0 NO Users on server 1(10.0.0.2): Number of users found:5 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin YES 0 NO 2 AU app_user NO 0 NO 3 CU crypto_user1 NO 0 NO 4 CU crypto_user2 NO 0 NO 5 CO officer1 YES 0 NO ``` The output includes the following user attributes: + **User ID**: Identifies the user in key\$1mgmt\$1util and [cloudhsm\$1mgmt\$1util](cloudhsm_mgmt_util.md) commands. + [User type](understanding-users.md): Determines the operations that the user can perform on the HSM. + **User Name**: Displays the user-defined friendly name for the user. + **MofnPubKey**: Indicates whether the user has registered a key pair for signing [quorum authentication tokens](quorum-authentication.md). + **LoginFailureCnt**: Indicates the number of times the user has unsuccessfully logged in. + **2FA**: Indicates that the user has enabled multi-factor authentication. ## Related topics + [listUsers](key_mgmt_util-listUsers.md) in key\$1mgmt\$1util + [createUser](cloudhsm_mgmt_util-createUser.md) + [deleteUser](cloudhsm_mgmt_util-deleteUser.md) + [changePswd](cloudhsm_mgmt_util-changePswd.md) # Log in and out of an HSM using AWS CloudHSM Management Utility Use the **loginHSM** and **logoutHSM** commands in the AWS CloudHSM cloudhsm\$1mgmt\$1util to log in and out of each HSM in a cluster. Any user of any type can use these commands. **Note** If you exceed five incorrect login attempts, your account is locked out. To unlock the account, a cryptographic officer (CO) must reset your password using the [changePswd](cloudhsm_mgmt_util-changePswd.md) command in cloudhsm\$1mgmt\$1util. ## To troubleshoot loginHSM and logoutHSM Before you run these cloudhsm\$1mgmt\$1util commands, you must start cloudhsm\$1mgmt\$1util. 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. If you have more than one HSM in your cluster, you may be allowed additional incorrect login attempts before your account is locked out. This is because the CloudHSM client balances load across various HSMs. Therefore, the login attempt may not begin on the same HSM each time. If you are testing this functionality, we recommend you do so on a cluster with only one active HSM. If you created your cluster before February 2018, your account is locked out after 20 incorrect login attempts. ## User type The following users can run these commands. + Pre-crypto officer (PRECO) + Crypto officer (CO) + Crypto user (CU) ## Syntax Enter the arguments in the order specified in the syntax diagram. Use the `-hpswd` parameter to mask your password. To login with two-factor authentication (2FA), use the `-2fa` parameter and include a file path. For more information, see [Arguments](#loginLogout-params). ``` loginHSM |-hpswd> [-2fa ] ``` ``` logoutHSM ``` ## Examples These examples show how to use **loginHSM** and **logoutHSM** to log in and out of all HSMs in a cluster. **Example : Log in to the HSMs in a cluster** This command logs you in to all HSMs in a cluster with the credentials of a CO user named `admin` and a password of `co12345`. The output shows that the command was successful and that you have connected to the HSMs (which, in this case, are `server 0` and `server 1`). ``` aws-cloudhsm>loginHSM CO admin co12345 loginHSM success on server 0(10.0.2.9) loginHSM success on server 1(10.0.3.11) ``` **Example : Log in with a hidden password** This command is the same as the example above, except this time you specify that the system should hide the password. ``` aws-cloudhsm>loginHSM CO admin -hpswd ``` The system prompts you for your password. You enter the password, the system hides the password, and the output shows that the command was successful and that the you have connected to the HSMs. ``` Enter password: loginHSM success on server 0(10.0.2.9) loginHSM success on server 1(10.0.3.11) aws-cloudhsm> ``` **Example : Log out of an HSM** This command logs you out of the HSMs that you are currently logged in to (which, in this case, are `server 0` and `server 1`). The output shows that the command was successful and that you have disconnected from the HSMs. ``` aws-cloudhsm>logoutHSM logoutHSM success on server 0(10.0.2.9) logoutHSM success on server 1(10.0.3.11) ``` ## Arguments Enter the arguments in the order specified in the syntax diagram. Use the `-hpswd` parameter to mask your password. To login with two-factor authentication (2FA), use the `-2fa` parameter and include a file path. For more information about working with 2FA, see [Manage user 2FA](manage-2fa.md) ``` loginHSM |-hpswd> [-2fa ] ``` **** Specifies the type of user who is logging in to the HSMs. For more information, see [User Type](#chmu-loginLogout-userType) above. Required: Yes **** Specifies the user name of the user who is logging in to the HSMs. Required: Yes **** Specifies the password of the user who is logging in to the HSMs. To hide your password, use the `-hpswd` parameter in place of the password and follow the prompt. Required: Yes **[-2fa ]** Specifies that the system should use a second factor to authenticate this 2FA-enabled CO user. To get the necessary data for logging in with 2FA, include a path to a location in the file system with a file name after the `-2fa` parameter. For more information about working with 2FA, see [Manage user 2FA](manage-2fa.md). Required: No ## Related topics + [Getting Started with cloudhsm\$1mgmt\$1util](cloudhsm_mgmt_util-getting-started.md) + [Activate the Cluster](activate-cluster.md) # Associate AWS CloudHSM users with keys using CMU Use the **registerQuorumPubKey** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util to associate hardware security module (HSM) users with asymmetric RSA-2048 key pairs. Once you associate HSM users with keys, those users can use the private key to approve quorum requests and the cluster can use the registered public key to verify the signature is from the user. For more information about quorum authentication, see [Managing Quorum Authentication (M of N Access Control)](quorum-authentication.md). **Tip** In the AWS CloudHSM documentation, quorum authentication is sometimes referred to as M of N (MofN), which means a minimum of *M* approvers out of a total number *N* approvers. ## User type The following types of users can run this command. + Crypto officers (CO) ## Syntax Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` registerQuorumPubKey ``` ## Examples This example shows how to use **registerQuorumPubKey** to register crypto officers (CO) as approvers on quorum authentication requests. To run this command, you must have an asymmetric RSA-2048 key pair, a signed token, and an unsigned token. For more information about these requirements, see [Arguments](#registerQuorumPubKey-params). **Example : Register an HSM user for quorum authentication** This example registers a CO named `quorum_officer` as an approver for quorum authentication. ``` aws-cloudhsm> registerQuorumPubKey CO *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)?y registerQuorumPubKey success on server 0(10.0.0.1) ``` The final command uses the [listUsers](cloudhsm_mgmt_util-listUsers.md) command to verify that `quorum_officer` is registered as an MofN user. ``` aws-cloudhsm> listUsers Users on server 0(10.0.0.1): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin NO 0 NO 2 AU app_user NO 0 NO 3 CO quorum_officer YES 0 NO ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` registerQuorumPubKey ``` **** Specifies the type of user. This parameter is required. For detailed information about the user types on an HSM, see [HSM user types for AWS CloudHSM Management Utility](understanding-users-cmu.md). Valid values: + **CO**: Crypto officers can manage users, but they cannot manage keys. Required: Yes **** Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). You cannot change the name of a user after it is created. In cloudhsm\$1mgmt\$1util commands, the user type and password are case-sensitive, but the user name is not. Required: Yes **** Specifies the path to a file that contains an unsigned registration token. Can have any random data of max file size of 245 bytes. For more information about creating an unsigned registration token, see [Create and Sign a Registration Token](quorum-authentication-crypto-officers-first-time-setup.md#mofn-registration-token). Required: Yes **** Specifies the path to a file that contains the SHA256\$1PKCS mechanism signed hash of the registration-token. For more information, see [Create and Sign a Registration Token](quorum-authentication-crypto-officers-first-time-setup.md#mofn-registration-token). Required: Yes **** Specifies the path to a file that contains the public key of an asymmetric RSA-2048 key pair. Use the private key to sign the registration token. For more information, see [Create an RSA Key Pair](quorum-authentication-crypto-officers-first-time-setup.md#mofn-key-pair-create). Required: Yes The cluster uses the same key for quorum authentication and for two-factor authentication (2FA). This means you can't rotate a quorum key for a user that has 2FA enabled using **registerQuorumPubKey**. To rotate the key, you must use **changePswd**. For more information about using quorum authentication and 2FA, see [Quorum Authentication and 2FA](quorum-2fa.md). ## Related topics + [Create an RSA Key Pair](quorum-authentication-crypto-officers-first-time-setup.md#mofn-key-pair-create) + [Create and Sign a Registration Token](quorum-authentication-crypto-officers-first-time-setup.md#mofn-registration-token) + [Register the Public Key with the HSM](quorum-authentication-crypto-officers-first-time-setup.md#mofn-register-key) + [Managing Quorum Authentication (M of N Access Control)](quorum-authentication.md) + [Quorum Authentication and 2FA](quorum-2fa.md) + [listUsers](cloudhsm_mgmt_util-listUsers.md) # Interact with one HSM in an AWS CloudHSM cluster using CMU Use the **server** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util to enter *server mode* and interact directly with a particular hardware security module (HSM) instance. Normally, when you issue a command in cloudhsm\$1mgmt\$1util, the command effects all HSMs in the designated cluster (*global mode)*. However, there may be circumstances for which you need to issue commands to a single HSM. For instance, in the event that automatic synchronization fails, you may need to sync keys and users on an HSM in order to maintain consistency across the cluster. Upon successful initiation, the `aws-cloudhsm >` command prompt is replaced with the `server >` command prompt. In order to exit server mode, use the `exit` command. Upon successful exit, you will be returned to the cloudhsm\$1mgmt\$1util command prompt. Before you run any cloudhsm\$1mgmt\$1util command, you must start cloudhsm\$1mgmt\$1util. ## User type The following users can run this command. + All users. ## Prerequisites In order to enter server mode, you must first know the server number of the target HSM. Server numbers are listed in the trace output generated by cloudhsm\$1mgmt\$1util upon initiation. Server numbers are assigned in the same order that the HSMs appear in the configuration file. For this example, we assume that `server 0` is the server that corresponds to the desired HSM. ## Syntax To start server mode: ``` server ``` To exit server mode: ``` server> exit ``` ## Example This command enters server mode on an HSM with server number `0`. ``` aws-cloudhsm> server 0 Server is in 'E2' mode... ``` In order to exit server mode, use the **exit** command. ``` server0> exit ``` ## Arguments ``` server ``` **** Specifies the server number of the target HSM. Required: Yes There are no arguments for the `exit` command. ## Related topics + [syncKey](cloudhsm_mgmt_util-syncKey.md) + [createUser](cloudhsm_mgmt_util-createUser.md) + [deleteUser](cloudhsm_mgmt_util-deleteUser.md) # Set the attributes of AWS CloudHSM keys using CMU Use the **setAttribute** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util to change the value of the label, encrypt, decrypt, wrap, and unwrap attributes of a key in the HSMs. You can also use the [setAttribute](key_mgmt_util-setAttribute.md) command in key\$1mgmt\$1util to convert a session key to a persistent key. You can only change the attributes of keys that you own. Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following users can run this command. + Crypto users (CU) ## Syntax Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` setAttribute ``` ## Example This example shows how to disable the decrypt functionality of a symmetric key. You can use a command like this one to configure a wrapping key, which should be able to wrap and unwrap other keys but not encrypt or decrypt data. The first step is to create the wrapping key. This command uses [genSymKey](key_mgmt_util-genSymKey.md) in key\$1mgmt\$1util to generate a 256-bit AES symmetric key. The output shows that the new key has key handle 14. ``` $ genSymKey -t 31 -s 32 -l aes256 Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Created. Key Handle: 14 Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS ``` Next, we want to confirm the current value of the decrypt attribute. To get the attribute ID of the decrypt attribute, use [listAttributes](cloudhsm_mgmt_util-listAttributes.md). The output shows that the constant that represents the `OBJ_ATTR_DECRYPT` attribute is `261`. For help interpreting the key attributes, see the [AWS CloudHSM key attribute reference for KMU](key-attribute-table.md). ``` aws-cloudhsm> listAttributes Following are the possible attribute values for getAttribute: OBJ_ATTR_CLASS = 0 OBJ_ATTR_TOKEN = 1 OBJ_ATTR_PRIVATE = 2 OBJ_ATTR_LABEL = 3 OBJ_ATTR_TRUSTED = 134 OBJ_ATTR_KEY_TYPE = 256 OBJ_ATTR_ID = 258 OBJ_ATTR_SENSITIVE = 259 OBJ_ATTR_ENCRYPT = 260 OBJ_ATTR_DECRYPT = 261 OBJ_ATTR_WRAP = 262 OBJ_ATTR_UNWRAP = 263 OBJ_ATTR_SIGN = 264 OBJ_ATTR_VERIFY = 266 OBJ_ATTR_DERIVE = 268 OBJ_ATTR_LOCAL = 355 OBJ_ATTR_MODULUS = 288 OBJ_ATTR_MODULUS_BITS = 289 OBJ_ATTR_PUBLIC_EXPONENT = 290 OBJ_ATTR_VALUE_LEN = 353 OBJ_ATTR_EXTRACTABLE = 354 OBJ_ATTR_NEVER_EXTRACTABLE = 356 OBJ_ATTR_ALWAYS_SENSITIVE = 357 OBJ_ATTR_DESTROYABLE = 370 OBJ_ATTR_KCV = 371 OBJ_ATTR_WRAP_WITH_TRUSTED = 528 OBJ_ATTR_WRAP_TEMPLATE = 1073742353 OBJ_ATTR_UNWRAP_TEMPLATE = 1073742354 OBJ_ATTR_ALL = 512 ``` To get the current value of the decrypt attribute for key 14, the next command uses [getAttribute](cloudhsm_mgmt_util-getAttribute.md) in cloudhsm\$1mgmt\$1util. The output shows that the value of the decrypt attribute is true (1) on both HSMs in the cluster. ``` aws-cloudhsm> getAttribute 14 261 Attribute Value on server 0(10.0.0.1): OBJ_ATTR_DECRYPT 0x00000001 Attribute Value on server 1(10.0.0.2): OBJ_ATTR_DECRYPT 0x00000001 ``` This command uses **setAttribute** to change the value of the decrypt attribute (attribute `261`) of key 14 to `0`. This disables the decrypt functionality on the key. The output shows that the command succeeded on both HSMs in the cluster. ``` aws-cloudhsm> setAttribute 14 261 0 *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)? y setAttribute success on server 0(10.0.0.1) setAttribute success on server 1(10.0.0.2) ``` The final command repeats the **getAttribute** command. Again, it gets the decrypt attribute (attribute `261`) of key 14. This time, the output shows that the value of the decrypt attribute is false (0) on both HSMs in the cluster. ``` aws-cloudhsm > getAttribute 14 261 Attribute Value on server 0(10.0.3.6): OBJ_ATTR_DECRYPT 0x00000000 Attribute Value on server 1(10.0.1.7): OBJ_ATTR_DECRYPT 0x00000000 ``` ## Arguments ``` setAttribute ** Specifies the key handle of a key that you own. You can specify only one key in each command. To get the key handle of a key, use [findKey](key_mgmt_util-findKey.md) in key\$1mgmt\$1util. To find the users of a key, use [getKeyInfo](cloudhsm_mgmt_util-getKeyInfo.md). Required: Yes **** Specifies the constant that represents the attribute that you want to change. You can specify only one attribute in each command. To get the attributes and their integer values, use [listAttributes](key_mgmt_util-listAttributes.md). For help interpreting the key attributes, see the [AWS CloudHSM key attribute reference for KMU](key-attribute-table.md). Valid values: + **3** – `OBJ_ATTR_LABEL`. + **134** – `OBJ_ATTR_TRUSTED`. + **260** – `OBJ_ATTR_ENCRYPT`. + **261** – `OBJ_ATTR_DECRYPT`. + **262** – `OBJ_ATTR_WRAP`. + **263** – `OBJ_ATTR_UNWRAP`. + **264** – `OBJ_ATTR_SIGN`. + **266** – `OBJ_ATTR_VERIFY`. + **268** – `OBJ_ATTR_DERIVE`. + **370** – `OBJ_ATTR_DESTROYABLE`. + **528** – `OBJ_ATTR_WRAP_WITH_TRUSTED`. + **1073742353** – `OBJ_ATTR_WRAP_TEMPLATE`. + **1073742354** – `OBJ_ATTR_UNWRAP_TEMPLATE`. Required: Yes ## Related topics + [setAttribute](key_mgmt_util-setAttribute.md) in key\$1mgmt\$1util + [getAttribute](cloudhsm_mgmt_util-getAttribute.md) + [listAttributes](cloudhsm_mgmt_util-listAttributes.md) + [Key Attribute Reference](key-attribute-table.md) # Exit the CMU Use the **quit** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util to exit the cloudhsm\$1mgmt\$1util. Any user of any type can use this command. Before you run any cloudhsm\$1mgmt\$1util command, you must start cloudhsm\$1mgmt\$1util. ## User type The following users can run this command. + All users. You do not need to be logged in to run this command. ## Syntax ``` quit ``` ## Example This command exits cloudhsm\$1mgmt\$1util. Upon successful completion, you are returned to your regular command line. This command has no output parameters. ``` aws-cloudhsm> quit disconnecting from servers, please wait... ``` ## Related topics + [Getting Started with cloudhsm\$1mgmt\$1util](cloudhsm_mgmt_util-getting-started.md) # Share AWS CloudHSM keys using CMU Use the **shareKey** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util to share and unshare keys that you own with other crypto users. Only the key owner can share and unshare a key. You can also share a key when you create it. Users who share the key can use the key in cryptographic operations, but they cannot delete, export, share, or unshare the key, or change its attributes. When quorum authentication is enabled on a key, the quorum must approve any operations that share or unshare the key. Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following types of users can run this command. + Crypto users (CU) ## Syntax Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. **User Type**: Crypto user (CU) ``` shareKey <(share/unshare key?) 1/0> ``` ## Example The following examples show how to use **shareKey** to share and unshare keys that you own with other crypto users. **Example : Share a key** This example uses **shareKey** to share an [ECC private key](key_mgmt_util-genSymKey.md) that the current user owns with another crypto user on the HSMs. Public keys are available to all users of the HSM, so you cannot share or unshare them. The first command uses [getKeyInfo](cloudhsm_mgmt_util-getKeyInfo.md) to get the user information for key `262177`, an ECC private key on the HSMs. The output shows that key `262177` is owned by user 3, but is not shared. ``` aws-cloudhsm>getKeyInfo 262177 Key Info on server 0(10.0.3.10): Token/Flash Key, Owned by user 3 Key Info on server 1(10.0.3.6): Token/Flash Key, Owned by user 3 ``` This command uses **shareKey** to share key `262177` with user `4`, another crypto user on the HSMs. The final argument uses a value of `1` to indicate a share operation. The output shows that the operation succeeded on both HSMs in the cluster. ``` aws-cloudhsm>shareKey 262177 4 1 *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)?y shareKey success on server 0(10.0.3.10) shareKey success on server 1(10.0.3.6) ``` To verify that the operation succeeded, the example repeats the first **getKeyInfo** command. The output shows that key `262177` is now shared with user `4`. ``` aws-cloudhsm>getKeyInfo 262177 Key Info on server 0(10.0.3.10): Token/Flash Key, Owned by user 3 also, shared to following 1 user(s): 4 Key Info on server 1(10.0.3.6): Token/Flash Key, Owned by user 3 also, shared to following 1 user(s): 4 ``` **Example : Unshare a key** This example unshares a symmetric key, that is, it removes a crypto user from the list of shared users for the key. This command uses **shareKey** to remove user `4` from the list of shared users for key `6`. The final argument uses a value of `0` to indicate an unshare operation. The output shows that the command succeeded on both HSMs. As a result, user `4` can no longer use key `6` in cryptographic operations. ``` aws-cloudhsm>shareKey 6 4 0 *************************CAUTION******************************** This is a CRITICAL operation, should be done on all nodes in the cluster. AWS does NOT synchronize these changes automatically with the nodes on which this operation is not executed or failed, please ensure this operation is executed on all nodes in the cluster. **************************************************************** Do you want to continue(y/n)?y shareKey success on server 0(10.0.3.10) shareKey success on server 1(10.0.3.6) ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` shareKey <(share/unshare key?) 1/0> ``` **** Specifies the key handle of a key that you own. You can specify only one key in each command. To get the key handle of a key, use [findKey](key_mgmt_util-findKey.md) in key\$1mgmt\$1util. To verify that you own a key, use [getKeyInfo](cloudhsm_mgmt_util-getKeyInfo.md). Required: Yes **** Specifies the user ID the crypto user (CU) with whom you are sharing or unsharing the key. To find the user ID of a user, use [listUsers](cloudhsm_mgmt_util-listUsers.md). Required: Yes **** To share the key with the specified user, type `1`. To unshare the key, that is, to remove the specified user from the list of shared users for the key, type `0`. Required: Yes ## Related topics + [getKeyInfo](cloudhsm_mgmt_util-getKeyInfo.md) # Synchronize keys across the AWS CloudHSM cluster using CMU Use the **syncKey** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util to manually synchronize keys across HSM instances within a cluster or across cloned clusters. In general, you will not need to use this command, as HSM instances within a cluster sync keys automatically. However, key synchronization across cloned clusters must be done manually. Cloned clusters are usually created in different AWS Regions in order to simplify the global scaling and disaster recovery processes. You cannot use **syncKey** to synchronize keys across arbitrary clusters: one of the clusters must have been created from a backup of the other. Additionally, both clusters must have consistent CO and CU credentials in order for the operation to be successful. For more information, see [HSM Users](understanding-users-cmu.md). To use **syncKey**, you must first [create an AWS CloudHSM configuration file](cloned-clusters.md) that specifies one HSM from the source cluster and one from the destination cluster. This will allow cloudhsm\$1mgmt\$1util to connect to both HSM instances. Use this configuration file to start cloudhsm\$1mgmt\$1util. Then log in with the credentials of a CO or a CU who owns the keys you want to synchronize. ## User type The following types of users can run this command. + Crypto officers (CO) + Crypto users (CU) **Note** COs can use **syncKey** on any keys, while CUs can only use this command on keys that they own. For more information, see [HSM user types for AWS CloudHSM Management Utility](understanding-users-cmu.md). ## Prerequisites Before you begin, you must know the `key handle` of the key on the source HSM to be synchronized with the destination HSM. To find the `key handle`, use the [listUsers](cloudhsm_mgmt_util-listUsers.md) command to list all identifiers for named users. Then, use the [findAllKeys](cloudhsm_mgmt_util-findAllKeys.md) command to find all keys that belong to a particular user. You also need to know the `server IDs` assigned to the source and destination HSMs, which are shown in the trace output returned by cloudhsm\$1mgmt\$1util upon initiation. These are assigned in the same order that the HSMs appear in the configuration file. Follow the instructions in [Using CMU Across Cloned Clusters](cloned-clusters.md) and initialize cloudhsm\$1mgmt\$1util with the new config file. Then, enter server mode on the source HSM by issuing the [server](cloudhsm_mgmt_util-server.md) command. ## Syntax **Note** To run **syncKey**, first enter server mode on the HSM which contains the key to be synchronized. Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. **User Type**: Crypto user (CU) ``` syncKey ``` ## Example Run the **server** command to log into the source HSM and enter server mode. For this example, we assume that `server 0` is the source HSM. ``` aws-cloudhsm> server 0 ``` Now run the **syncKey** command. In this example, we assume key `261251` is to be synced to `server 1`. ``` aws-cloudhsm> syncKey 261251 1 syncKey success ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` syncKey ``` **** Specifies the key handle of the key to sync. You can specify only one key in each command. To get the key handle of a key, use [findAllKeys](cloudhsm_mgmt_util-findAllKeys.md) while logged in to an HSM server. Required: Yes **** Specifies the number of the server to which you are syncing a key. Required: Yes ## Related topics + [listUsers](cloudhsm_mgmt_util-listUsers.md) + [findAllKeys](cloudhsm_mgmt_util-findAllKeys.md) + [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) in AWS CLI + [server](cloudhsm_mgmt_util-server.md) # Synchronize users across the AWS CloudHSM cluster using CMU Use the **syncUser** command in the AWS CloudHSM cloudhsm\$1mgmt\$1util to manually synchronize crypto users (CUs) or crypto officers (COs) across HSM instances within a cluster or across cloned clusters. AWS CloudHSM does not automatically synchronize users. Generally, you manage users in global mode so that all HSMs in a cluster are updated together. You might need to use **syncUser** if an HSM is accidentally desynchronized (for example, due to password changes) or if you want to rotate user credentials across cloned clusters. Cloned clusters are usually created in different AWS Regions to simplify the global scaling and disaster recovery processes. Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use. If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster. ## User type The following types of users can run this command. + Crypto officers (CO) ## Prerequisites Before you begin, you must know the `user ID` of the user on the source HSM to be synchronized with the destination HSM. To find the `user ID`, use the [listUsers](cloudhsm_mgmt_util-listUsers.md) command to list all users on the HSMs in a cluster. You also need to know the `server ID` assigned to the source and destination HSMs, which are shown in the trace output returned by cloudhsm\$1mgmt\$1util upon initiation. These are assigned in the same order that the HSMs appear in the configuration file. If you are synchronizing HSMs across cloned clusters, follow the instructions in [Using CMU Across Cloned Clusters](cloned-clusters.md) and initialize cloudhsm\$1mgmt\$1util with the new config file. When you are ready to run **syncUser**, enter server mode on the source HSM by issuing the [**server**](cloudhsm_mgmt_util-server.md) command. ## Syntax Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` syncUser ``` ## Example Run the **server** command to log into the source HSM and enter server mode. For this example, we assume that `server 0` is the source HSM. ``` aws-cloudhsm> server 0 ``` Now run the **syncUser** command. For this example, we assume that user `6` is the user to be synced, and `server 1` is the destination HSM. ``` server 0> syncUser 6 1 ExtractMaskedObject: 0x0 ! InsertMaskedObject: 0x0 ! syncUser success ``` ## Arguments Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram. ``` syncUser ``` **** Specifies the ID of the user to sync. You can specify only one user in each command. To get the ID of a user, use [listUsers](cloudhsm_mgmt_util-listUsers.md). Required: Yes **** Specifies the server number of the HSM to which you are syncing a user. Required: Yes ## Related topics + [listUsers](cloudhsm_mgmt_util-listUsers.md) + [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) in AWS CLI + [server](cloudhsm_mgmt_util-server.md)