# HSM user management with CloudHSM Management Utility (CMU) User management with CMU To manage hardware security module (HSM) users in AWS CloudHSM, you must log in to the HSM with the user name and password of a [cryptographic officer](understanding-users-cmu.md#crypto-officer) (CO). Only COs can manage users. The HSM contains a default CO named admin. You set the password for admin when you [activated the cluster](activate-cluster.md). This topic provides step-by-step instruction on and detail about managing HSM users with AWS CloudHSM Management Utility (CMU). **Topics** + [Prerequisites](understand-users.md) + [User types](understanding-users-cmu.md) + [Permissions table](user-permissions-table-cmu.md) + [Create users](create-users-cmu.md) + [List all users](list-users.md) + [Change passwords](change-user-password-cmu.md) + [Delete users](delete-user.md) + [Manage user 2FA](manage-2fa.md) + [Using CMU to manage quorum authentication](quorum-authentication.md) # Prerequisites for user management in AWS CloudHSM Management Utility Prerequisites Before you use AWS CloudHSM Management Utility (CMU) to manage hardware security module (HSM) users in AWS CloudHSM, you must complete these prerequisites. The following topics describe getting started with the CMU. **Topics** + [ ## Get the IP address of an HSM in AWS CloudHSM ](#user-cmu-prereq-ip) + [ ## Using CMU with Client SDK 3.2.1 and earlier ](#downlevel-cmu) + [ ## Download CloudHSM Management Utility ](#get-cli-users-cmu) ## Get the IP address of an HSM in AWS CloudHSM To use CMU, you must use the configure tool to update the local configuration. CMU creates its own connection to the cluster and this connection is *not* cluster aware. To track cluster information, CMU maintains a local configuration file. This means that *each time* you use CMU, you should first update the configuration file by running the [configure](configure-tool.md) command line tool with the `--cmu` parameter. If you are using Client SDK 3.2.1 or earlier, you must use a different parameter than `--cmu`. For more information, see [Using CMU with Client SDK 3.2.1 and earlier](#downlevel-cmu). The `--cmu` parameter requires you to add the IP address of an HSM in your cluster. If you have multiple HSMs, you can use any IP address. This ensures CMU can propagate any changes you make across the entire cluster. Remember that CMU uses its local file to track cluster information. If the cluster has changed since the last time you used CMU from a particular host, you must add those changes to the local configuration file stored on that host. Never add or remove an HSM while you're using CMU. **To get an IP address for an HSM (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. To change the AWS Region, use the Region selector in the upper-right corner of the page. 1. To open the cluster detail page, in the cluster table, choose the cluster ID. 1. To get the IP address, go to the HSMs tab. For IPv4 clusters, choose an address listed under **ENI IPv4 address**. For dual-stack clusters use either the ENI IPv4 or the **ENI IPv6 address**. **To get an IP address for an HSM (AWS CLI)** + Get the IP address of an HSM by using the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command from the AWS CLI. In the output from the command, the IP address of the HSMs are the values of `EniIp` and `EniIpV6` (if it is a dual-stack cluster). ``` $ aws cloudhsmv2 describe-clusters { "Clusters": [ { ... } "Hsms": [ { ... "EniIp": "10.0.0.9", ... }, { ... "EniIp": "10.0.1.6", "EniIpV6": "2600:113f:404:be09:310e:ed34:3412:f733", ... ``` ## Using CMU with Client SDK 3.2.1 and earlier With Client SDK 3.3.0, AWS CloudHSM added support for the `--cmu` parameter, which simplifies the process of updating the configuration file for CMU. If you're using a version of CMU from Client SDK 3.2.1 or earlier, you must continue to use the `-a` and `-m` parameters to update the configuration file. For more information about these parameters, see [Configure Tool](configure-tool.md). ## Download CloudHSM Management Utility The latest version of CMU is available for HSM user management tasks whether you are using Client SDK 5 and Client SDK 3. **To download and install CMU** + Download and install CMU. ------ #### [ Amazon Linux ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-mgmt-util-latest.el6.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-mgmt-util-latest.el6.x86_64.rpm ``` ------ #### [ Amazon Linux 2 ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-mgmt-util-latest.el7.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-mgmt-util-latest.el7.x86_64.rpm ``` ------ #### [ CentOS 7.8\$1 ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-mgmt-util-latest.el7.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-mgmt-util-latest.el7.x86_64.rpm ``` ------ #### [ CentOS 8.3\$1 ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-mgmt-util-latest.el8.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-mgmt-util-latest.el8.x86_64.rpm ``` ------ #### [ RHEL 7 (7.8\$1) ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-mgmt-util-latest.el7.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-mgmt-util-latest.el7.x86_64.rpm ``` ------ #### [ RHEL 8 (8.3\$1) ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-mgmt-util-latest.el8.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-mgmt-util-latest.el8.x86_64.rpm ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-mgmt-util_latest_amd64.deb ``` ``` $ sudo apt install ./cloudhsm-mgmt-util_latest_amd64.deb ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-mgmt-util_latest_u18.04_amd64.deb ``` ``` $ sudo apt install ./cloudhsm-mgmt-util_latest_u18.04_amd64.deb ``` ------ #### [ Windows Server 2012 ] 1. Download [CloudHSM Management Utility](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMManagementUtil-latest.msi). 1. Run the CMU installer (**AWSCloudHSMManagementUtil-latest.msi**) with Windows administrative privilege. ------ #### [ Windows Server 2012 R2 ] 1. Download [CloudHSM Management Utility](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMManagementUtil-latest.msi). 1. Run the CMU installer (**AWSCloudHSMManagementUtil-latest.msi**) with Windows administrative privilege. ------ #### [ Windows Server 2016 ] 1. Download [CloudHSM Management Utility](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMManagementUtil-latest.msi). 1. Run the CMU installer (**AWSCloudHSMManagementUtil-latest.msi**) with Windows administrative privilege. ------ # HSM user types for AWS CloudHSM Management Utility User types Most operations that you perform on the hardware security module (HSM) require the credentials of an AWS CloudHSM *HSM user*. The HSM authenticates each HSM user and each HSM user has a *type* that determines which operations you can perform on the HSM as that user. **Note** HSM users are distinct from IAM users. IAM users who have the correct credentials can create HSMs by interacting with resources through the AWS API. After the HSM is created, you must use HSM user credentials to authenticate operations on the HSM. **Topics** + [ ## Precrypto officer (PRECO) ](#preco) + [ ## Crypto officer (CO) ](#crypto-officer) + [ ## Crypto user (CU) ](#crypto-user-cmu) + [ ## Appliance user (AU) ](#appliance-user-cmu) ## Precrypto officer (PRECO) In both the cloud management utility (CMU) and the key management utility (KMU), the PRECO is a temporary user that exists only on the first HSM in an AWS CloudHSM cluster. The first HSM in a new cluster contains an PRECO user indicating that this cluster has never been activated. To [activate a cluster](activate-cluster.md), you execute the cloudhsm-cli and run the **cluster activate** command. Log in to the HSM and change the PRECO's password. When you change the password, this user becomes the crypto officer (CO). ## Crypto officer (CO) In both the cloud management utility (CMU) and the key management utility (KMU), a crypto officer (CO) can perform user management operations. For example, they can create and delete users and change user passwords. For more information about CO users, see the [HSM user permissions table for AWS CloudHSM Management Utility](user-permissions-table-cmu.md). When you activate a new cluster, the user changes from a [Precrypto Officer](#preco) (PRECO) to a crypto officer (CO). ## Crypto user (CU) A crypto user (CU) can perform the following key management and cryptographic operations. + **Key management** – Create, delete, share, import, and export cryptographic keys. + **Cryptographic operations** – Use cryptographic keys for encryption, decryption, signing, verifying, and more. For more information, see the [HSM user permissions table for AWS CloudHSM Management Utility](user-permissions-table-cmu.md). ## Appliance user (AU) The appliance user (AU) can perform cloning and synchronization operations on your cluster's HSMs. AWS CloudHSM uses the AU to synchronize the HSMs in an AWS CloudHSM cluster. The AU exists on all HSMs provided by AWS CloudHSM, and has limited permissions. For more information, see the [HSM user permissions table for AWS CloudHSM Management Utility](user-permissions-table-cmu.md). AWS cannot perform any operations on your HSMs . AWS cannot view or modify your users or keys and cannot perform any cryptographic operations using those keys. # HSM user permissions table for AWS CloudHSM Management Utility Permissions table The following table lists hardware security module (HSM( operations sorted by the type of HSM user or session that can perform the operation in AWS CloudHSM. | | Crypto officer (CO) | Crypto User (CU) | Appliance User (AU) | Unauthenticated Session | | --- | --- | --- | --- | --- | | Get basic cluster info¹ | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | | Change own password | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | Not applicable | | Change any user's password | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | | Add, remove users | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | | Get sync status² | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | | Extract, insert masked objects³ | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | | Key management functions⁴ | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | | Encrypt, decrypt | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | | Sign, verify | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | | Generate digests and HMACs | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[Yes\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/icon-no.png) No | + [1] Basic cluster information includes the number of HSMs in the cluster and each HSM's IP address, model, serial number, device ID, firmware ID, etc. + [2] The user can get a set of digests (hashes) that correspond to the keys on the HSM. An application can compare these sets of digests to understand the synchronization status of HSMs in a cluster. + [3] Masked objects are keys that are encrypted before they leave the HSM. They cannot be decrypted outside of the HSM. They are only decrypted after they are inserted into an HSM that is in the same cluster as the HSM from which they were extracted. An application can extract and insert masked objects to synchronize the HSMs in a cluster. + [4] Key management functions include creating, deleting, wrapping, unwrapping, and modifying the attributes of keys. # Create HSM users using AWS CloudHSM Management Utility Create users Use **createUser** in AWS CloudHSM Management Utility (CMU) to create new users on the hardware security module (HSM). You must log in as a CO to create a user. **To create a new CO user** 1. Use the configure tool to update the CMU configuration. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure --cmu ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" --cmu ``` ------ 1. Start CMU. ------ #### [ 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 ``` ------ 1. Log in to the HSM as a CO user. ``` aws-cloudhsm > loginHSM CO admin co12345 ``` Make sure the number of connections CMU lists match the number of HSMs in the cluster. If not, log out and start over. 1. Use **createUser** to create a CO user named **example\$1officer** with a password of **password1**. ``` aws-cloudhsm > createUser CO example_officer 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. Type **y**. **To create a new CU user** 1. Use the configure tool to update the CMU configuration. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure --cmu ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" --cmu ``` ------ 1. Start CMU. ------ #### [ 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 ``` ------ 1. Log in to the HSM as a CO user. ``` aws-cloudhsm > loginHSM CO admin co12345 ``` Make sure the number of connections CMU lists match the number of HSMs in the cluster. If not, log out and start over. 1. Use **createUser** to create a CU user named **example\$1user** with a password of **password1**. ``` 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. Type **y**. For more information about **createUser**, see [createUser](cloudhsm_mgmt_util-createUser.md). # List all HSM users in the cluster using AWS CloudHSM Management Utility List all users Use **listUsers** command in the AWS CloudHSM Management Utility (CMU) to list all the users in the AWS CloudHSM cluster. You do not have to log in to run **listUsers** and all user types can list users. **To list all users on the cluster** 1. Use the configure tool to update the CMU configuration. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure --cmu ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" --cmu ``` ------ 1. Start CMU. ------ #### [ 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 ``` ------ 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:4 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 AU app_user NO 0 NO 2 CO example_officer NO 0 NO 3 CU example_user NO 0 NO Users on server 1(10.0.3.11): Number of users found:4 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 AU app_user NO 0 NO 2 CO example_officer NO 0 NO 3 CU example_user NO 0 NO Users on server 2(10.0.1.12): Number of users found:4 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 AU app_user NO 0 NO 2 CO example_officer NO 0 NO 3 CU example_user NO 0 NO ``` For more information about **listUsers**, see [listUsers](cloudhsm_mgmt_util-listUsers.md). # Change HSM user passwords using AWS CloudHSM Management Utility Change passwords Use **changePswd** in the AWS CloudHSM Management Utility (CMU) to change a hardware security module (HSM) user's password. User types and passwords are case sensitive, but user names are not case sensitive. CO, Crypto user (CU), and appliance user (AU) can change their own password. To change the password of another user, you must log in as a CO. You cannot change the password of a user who is currently logged in. **To change your own password** 1. Use the configure tool to update the CMU configuration. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure --cmu ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" --cmu ``` ------ 1. Start CMU. ------ #### [ 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 ``` ------ 1. Log in to the HSM. ``` aws-cloudhsm > loginHSM CO admin co12345 ``` Make sure the number of connections CMU lists match the number of HSMs in the cluster. If not, log out and start over. 1. Use **changePswd** to change your own password. ``` aws-cloudhsm > changePswd CO example_officer ``` CMU prompts you about the change password 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. Type **y**. CMU prompts you about the change password operation. ``` Changing password for example_officer(CO) on 3 nodes ``` **To change the password of another user** 1. Use the configure tool to update the CMU configuration. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure --cmu ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" --cmu ``` ------ 1. Start CMU. ------ #### [ 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 ``` ------ 1. Log in to the HSM as a CO user. ``` aws-cloudhsm > loginHSM CO admin co12345 ``` Make sure the number of connections CMU lists match the number of HSMs in the cluster. If not, log out and start over. 1. Use **changePswd** to change the password of another user. ``` aws-cloudhsm > changePswd CU example_user ``` CMU prompts you about the change password 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. Type **y**. CMU prompts you about the change password operation. ``` Changing password for example_user(CU) on 3 nodes ``` For more information about **changePswd**, see [changePswd](cloudhsm_mgmt_util-changePswd.md). # Delete HSM users using AWS CloudHSM Management Utility Delete users Use **deleteUser** in the AWS CloudHSM Management Utility (CMU) to delete a hardware security module (HSM) user. You must log in as a CO to delete another user. **Tip** You can't delete crypto users (CU) that own keys. **To delete a user** 1. Use the configure tool to update the CMU configuration. ------ #### [ Linux ] ``` $ sudo /opt/cloudhsm/bin/configure --cmu ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" --cmu ``` ------ 1. Start CMU. ------ #### [ 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 ``` ------ 1. Log in to the HSM as a CO user. ``` aws-cloudhsm > loginHSM CO admin co12345 ``` Make sure the number of connections CMU lists match the number of HSMs in the cluster. If not, log out and start over. 1. Use **deleteUser** to delete a user. ``` aws-cloudhsm > deleteUser CO example_officer ``` CMU deletes the user. ``` Deleting user example_officer(CO) on 3 nodes deleteUser success on server 0(10.0.2.9) deleteUser success on server 1(10.0.3.11) deleteUser success on server 2(10.0.1.12) ``` For more information about **deleteUser**, see [deleteUser](cloudhsm_mgmt_util-deleteUser.md). # Manage 2FA for users using AWS CloudHSM Management Utility Manage user 2FA For increased security, you can configure two-factor authentication (2FA) to help protect the AWS CloudHSM cluster. You can only enable 2FA for crypto officers (CO). When you log in to a cluster with a 2FA-enabled hardware service module (HSM) account, you provide cloudhsm\$1mgmt\$1util (CMU) with your password—the first factor, what you know—and CMU provides you with a token and prompts you to have the token signed. To provide the second factor—what you have—you sign the token with a private key from a key pair you've already created and associated with the HSM user. To access the cluster, you provide the signed token to CMU. **Note** You cannot enable 2FA for crypto users (CU) or applications. Two-factor authentication (2FA) is only for CO users. **Topics** + [Quorum authentication](quorum-2fa.md) + [Key pair requirements](enable-2fa-kms.md) + [Create users](create-2fa.md) + [Manage user 2FA](rotate-2fa.md) + [Disable 2FA](disable-2fa.md) + [Configuration reference](reference-2fa.md) # Quorum authentication and 2FA in AWS CloudHSM clusters using AWS CloudHSM Management Utility Quorum authentication The cluster uses the same key for quorum authentication and for two-factor authentication 2FA). This means a user with 2FA enabled is effectively registered for M-of-N-access-control (MofN). To successfully use 2FA and quorum authentication for the same HSM user, consider the following points: + If you are using quorum authentication for a user today, you should use the same key pair you created for the quorum user to enable 2FA for the user. + If you add the 2FA requirement for a non-2FA user that is not a quorum authentication user, then you register that user as an MofN user with 2FA authentication. + If you remove the 2FA requirement or change the password for a 2FA user that is also a quorum authentication user, you will also remove the registration of the quorum user as an MofN user. + If you remove the 2FA requirement or change the password for a 2FA user that is also a quorum authentication user, but you *still want that user to participate in quorum authentication*, then you must register that user again as an MofN user. For more information about quorum authentication, see [Using CMU to manage quorum authentication](quorum-authentication.md). # 2FA key pair requirements for AWS CloudHSM using AWS CloudHSM Management Utility Key pair requirements To enable two-factor authentication (2FA) for an AWS CloudHSM hardware security module (HSM) user, use a key that meets the following requirements. You can create a new key pair or use an existing key that meets the following requirements. + Key type: Asymmetric + Key usage: Sign and Verify + Key spec: RSA\$12048 + Signing algorithm includes: + `sha256WithRSAEncryption` **Note** If you are using quorum authentication or plan to use quorum authentication, see [Quorum authentication and 2FA in AWS CloudHSM clusters using AWS CloudHSM Management Utility](quorum-2fa.md). # Create users with 2FA enabled for AWS CloudHSM Management Utility users Create users Use AWS CloudHSM Management Utility CMU (CMU) and the key pair to create a new crypto office (CO) user with two-factor authentication (2FA) enabled. **To create CO users with 2FA enabled** 1. In one terminal, perform the following steps: 1. Access your HSM and log in to the CloudHSM Management utility: ``` /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` 1. Log in as a CO and use the following command to create a new user MFA with 2FA: ``` aws-cloudhsm > createUser CO MFA -2fa /home/ec2-user/authdata *************************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 Creating User exampleuser3(CO) on 1 nodesAuthentication data written to: "/home/ec2-user/authdata"Generate Base64-encoded signatures for SHA256 digests in the authentication datafile. To generate the signatures, use the RSA private key, which is the second factor ofauthentication for this user. Paste the signatures and the corresponding public keyinto the authentication data file and provide the file path below.Leave this field blank to use the path initially provided.Enter filename: ``` 1. Leave the above terminal in this state. Do not press enter or enter any filename. 1. In another terminal, perform the following steps: 1. Access your HSM and log in to the CloudHSM Management utility: ``` /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` 1. Generate a public-private key-pair using the following commands: ``` openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048 ``` ``` openssl rsa -pubout -in private_key.pem -out public_key.pem ``` 1. Run the following command to install a json querying feature for extracting the Digest from authdata file: ``` sudo yum install jq ``` 1. To extract the digest value, first find the following data in the authdata file: ``` { "Version":"1.0", "PublicKey":"", "Data":[ { "HsmId": <"HSM ID">, "Digest": <"DIGEST">, "Signature": "" } ] } ``` **Note** The obtained Digest is base64 encoded, however to sign the digest, you need the file to be decoded first and then signed. The following command will decode the digest and store the decoded content in ‘digest1.bin’ ``` cat authdata | jq '.Data[0].Digest' | cut -c2- | rev | cut -c2- | rev | base64 -d > digest1.bin ``` 1. Convert the public key content, adding "\$1n" and removing spaces as shown here: ``` -----BEGIN PUBLIC KEY-----\n\n-----END PUBLIC KEY----- ``` **Important** The above command shows how "\$1n" is added immediately after **BEGIN PUBLIC KEY-----**, spaces between "\$1n" and the first character of the public key are removed, "\$1n" is added before **-----END PUBLIC KEY**, and spaces are removed between "\$1n" and the end of the public key. This is the PEM format for public key which is accepted in the authdata file. 1. Paste the public key pem format content in the public key section in the authdata file. ``` vi authdata ``` ``` { "Version":"1.0", "PublicKey":"-----BEGIN PUBLIC KEY-----\n<"PUBLIC KEY">\n-----END PUBLIC KEY-----", "Data":[ { "HsmId":<"HSM ID">, "Digest":<"DIGEST">, "Signature": "" } ] } ``` 1. Sign the token file using the following command: ``` openssl pkeyutl -sign -in digest1.bin -inkey private_key.pem -pkeyopt digest:sha256 | base64 Output Expected: <"THE SIGNATURE"> ``` **Note** As shown in the above command, use **openssl pkeyutl** instead of **openssl dgst** for signing. 1. Add the signed digest in the Authdata File in "Signature" field. ``` vi authdata ``` ``` { "Version": "1.0", "PublicKey": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----", "Data": [ { "HsmId": <"HSM ID">, "Digest": <"DIGEST">, "Signature": <"Kkdl ... rkrvJ6Q=="> }, { "HsmId": <"HSM ID">, "Digest": <"DIGEST">, "Signature": <"K1hxy ... Q261Q=="> } ] } ``` 1. Go back to the first terminal and press **Enter**: ``` Generate Base64-encoded signatures for SHA256 digests in the authentication datafile. To generate the signatures, use the RSA private key, which is the second factor ofauthentication for this user. Paste the signatures and the corresponding public keyinto the authentication data file and provide the file path below. Leave this field blank to use the path initially provided. Enter filename: >>>>> Press Enter here createUser success on server 0(10.0.1.11) ``` # Manage 2FA for HSM users using AWS CloudHSM Management Utility Manage user 2FA Use **changePswd** in AWS CloudHSM Management Utility (CMU) to modify two-factor authentication (2FA) for a user. Each time you enable 2FA, you must provide a public key for 2FA logins. **changePswd** performs any of the following scenarios: + Change the password for a 2FA user + Change the password for a non-2FA user + Add 2FA to a non-2FA user + Remove 2FA from a 2FA user + Rotate the key for a 2FA user You can also combine tasks. For example, you can remove 2FA from a user and change the password at the same time, or you might rotate the 2FA key and change the user password. **To change passwords or rotate keys for CO users with 2FA enabled** 1. Use CMU to log in to the HSM as a CO with 2FA enabled. 1. Use **changePswd** to change the password or rotate the key from CO users with 2FA enabled. Use the `-2fa` parameter and include a location in the file system for the system to write the `authdata` file. This file includes a digest for each HSM in the cluster. ``` aws-cloudhsm > changePswd CO example-user -2fa /path/to/authdata ``` CMU prompts you to use the private key to sign the digests in the `authdata` file and return the signatures with the public key. 1. Use the private key to sign the digests in the `authdata` file, add the signatures and the public key to the JSON formatted `authdata` file and then provide CMU with the location of the `authdata` file. For more information, see [Configuration reference for 2FA with AWS CloudHSM Management Utility](reference-2fa.md). **Note** The cluster uses the same key for quorum authentication and 2FA. If you are using quorum authentication or plan to use quorum authentication, see [Quorum authentication and 2FA in AWS CloudHSM clusters using AWS CloudHSM Management Utility](quorum-2fa.md). # Disable 2FA for HSM users using AWS CloudHSM Management Utility Disable 2FA Use the AWS CloudHSM Management Utility (CMU) to disable two-factor authentication (2FA) for hardware security module HSM) users in AWS CloudHSM. **To disable 2FA for CO users with 2FA enabled** 1. Use CMU to log in to the HSM as a CO with 2FA enabled. 1. Use **changePswd** to remove 2FA from CO users with 2FA enabled. ``` aws-cloudhsm > changePswd CO example-user ``` CMU prompts you to confirm the change password operation. **Note** If you remove the 2FA requirement or change the password for a 2FA user that is also a quorum authentication user, you will also remove the registration of the quorum user as an MofN user. For more information about quorum users and 2FA, see [Quorum authentication and 2FA in AWS CloudHSM clusters using AWS CloudHSM Management Utility](quorum-2fa.md). 1. Type **y**. CMU confirms the change password operation. # Configuration reference for 2FA with AWS CloudHSM Management Utility Configuration reference The following is an example of the two-factor authentication (2FA) properties in the `authdata` file for both the AWS CloudHSM Management Utility (CMU) generated request and your responses. ``` { "Version": "1.0", "PublicKey": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----", "Data": [ { "HsmId": "hsm-lgavqitns2a", "Digest": "k5O1p3f6foQRVQH7S8Rrjcau6h3TYqsSdr16A54+qG8=", "Signature": "Kkdl ... rkrvJ6Q==" }, { "HsmId": "hsm-lgavqitns2a", "Digest": "IyBcx4I5Vyx1jztwvXinCBQd9lDx8oQe7iRrWjBAi1w=", "Signature": "K1hxy ... Q261Q==" } ] } ``` **Data** Top-level node. Contains a subordinate node for each HSM in the cluster. Appears in requests and responses for all 2FA commands. **Digest** This is what you must sign to provide the second factor of authentication. CMU generated in requests for all 2FA commands. **HsmId** The ID of your HSM. Appears in requests and responses for all 2FA commands. **PublicKey** The public key portion of the key pair you generated inserted as PEM-formatted string. You enter this in responses for **createUser** and **changePswd**. **Signature** The Base 64 encoded signed digest. You enter this in responses for all 2FA commands. **Version** The version of the authentication data JSON formatted file. Appears in requests and responses for all 2FA commands. # Using CloudHSM Management Utility (CMU) to manage quorum authentication (M of N access control) Using CMU to manage quorum authentication The HSMs in your AWS CloudHSM cluster support quorum authentication, which is also known as M of N access control. With quorum authentication, no single user on the HSM can do quorum-controlled operations on the HSM. Instead, a minimum number of HSM users (at least 2) must cooperate to do these operations. With quorum authentication, you can add an extra layer of protection by requiring approvals from more than one HSM user. Quorum authentication can control the following operations: + HSM user management by [crypto officers (COs)](understanding-users-cmu.md#crypto-officer) – Creating and deleting HSM users, and changing a different HSM user's password. For more information, see [User management with quorum authentication enabled for AWS CloudHSM Management Utility](quorum-authentication-crypto-officers.md). Note the following additional information about using quorum authentication in AWS CloudHSM. + An HSM user can sign their own quorum token—that is, the requesting user can provide one of the required approvals for quorum authentication. + You choose the minimum number of quorum approvers for quorum-controlled operations. The smallest number you can choose is two (2), and the largest number you can choose is eight (8). + The HSM can store up to 1024 quorum tokens. If the HSM already has 1024 tokens when you try to create a new one, the HSM purges one of the expired tokens. By default, tokens expire ten minutes after their creation. + The cluster uses the same key for quorum authentication and for two-factor authentication (2FA). For more information about using quorum authentication and 2FA, see [Quorum Authentication and 2FA](quorum-2fa.md). The following topics provide more information about quorum authentication in AWS CloudHSM. **Topics** + [Quorum authentication process](quorum-authentication-overview.md) + [First time setup](quorum-authentication-crypto-officers-first-time-setup.md) + [User management with quorum (M of N)](quorum-authentication-crypto-officers.md) + [Change the minimum value](quorum-authentication-crypto-officers-change-minimum-value.md) # Quorum authentication process for AWS CloudHSM Management Utility Quorum authentication process The following steps summarize the quorum authentication processes. For the specific steps and tools, see [User management with quorum authentication enabled for AWS CloudHSM Management Utility](quorum-authentication-crypto-officers.md). 1. Each HSM user creates an asymmetric key for signing. They do this outside of the HSM, taking care to protect the key appropriately. 1. Each HSM user logs in to the HSM and registers the public part of their signing key (the public key) with the HSM. 1. When an HSM user wants to do a quorum-controlled operation, each user logs in to the HSM and gets a *quorum token*. 1. The HSM user gives the quorum token to one or more other HSM users and asks for their approval. 1. The other HSM users approve by using their keys to cryptographically sign the quorum token. This occurs outside the HSM. 1. When the HSM user has the required number of approvals, the same user logs in to the HSM and gives the quorum token and approvals (signatures) to the HSM. 1. The HSM uses the registered public keys of each signer to verify the signatures. If the signatures are valid, the HSM approves the token. 1. The HSM user can now do a quorum-controlled operation. # Set up quorum authentication for AWS CloudHSM crypto officers First time setup The following topics describe the steps that you must complete to configure your hardware security module (HSM) so that AWS CloudHSM [crypto officers (COs)](understanding-users-cmu.md#crypto-officer) can use quorum authentication. You need to do these steps only once when you first configure quorum authentication for COs. After you complete these steps, see [User management with quorum authentication enabled for AWS CloudHSM Management Utility](quorum-authentication-crypto-officers.md). **Topics** + [ ## Prerequisites ](#quorum-crypto-officers-prerequisites) + [ ## Step 1. Create and register a key for signing ](#quorum-crypto-officers-create-and-register-key) + [ ## Step 2. Set the quorum minimum value on the HSM ](#quorum-crypto-officers-set-quorum-minimum-value) ## Prerequisites To understand this example, you should be familiar with the [cloudhsm\$1mgmt\$1util (CMU) command line tool](cloudhsm_mgmt_util.md). In this example, the AWS CloudHSM cluster has two HSMs, each with the same COs, as shown in the following output from the **listUsers** command. For more information about creating users, see [HSM users](manage-hsm-users.md). ``` aws-cloudhsm > listUsers Users on server 0(10.0.2.14): Number of users found:7 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PRECO admin NO 0 NO 2 AU app_user NO 0 NO 3 CO officer1 NO 0 NO 4 CO officer2 NO 0 NO 5 CO officer3 NO 0 NO 6 CO officer4 NO 0 NO 7 CO officer5 NO 0 NO Users on server 1(10.0.1.4): Number of users found:7 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PRECO admin NO 0 NO 2 AU app_user NO 0 NO 3 CO officer1 NO 0 NO 4 CO officer2 NO 0 NO 5 CO officer3 NO 0 NO 6 CO officer4 NO 0 NO 7 CO officer5 NO 0 NO ``` ## Step 1. Create and register a key for signing To use quorum authentication, each CO must do *all* of the following steps: **Topics** + [ ### Create an RSA key pair ](#mofn-key-pair-create) + [ ### Create and sign a registration token ](#mofn-registration-token) + [ ### Register the public key with the HSM ](#mofn-register-key) ### Create an RSA key pair There are many different ways to create and protect a key pair. The following examples show how to do it with [OpenSSL](https://www.openssl.org/). **Example – Create a private key with OpenSSL** The following example demonstrates how to use OpenSSL to create a 2048-bit RSA key that is protected by a pass phrase. To use this example, replace *officer1.key* with the name of the file where you want to store the key. ``` $ openssl genrsa -out -aes256 2048 Generating RSA private key, 2048 bit long modulus .....................................+++ .+++ e is 65537 (0x10001) Enter pass phrase for officer1.key: Verifying - Enter pass phrase for officer1.key: ``` Next, generate the public key using the private key that you just created. **Example – Create a public key with OpenSSL** The following example demonstrates how to use OpenSSL to create a public key from the private key you just created. ``` $ openssl rsa -in officer1.key -outform PEM -pubout -out officer1.pub Enter pass phrase for officer1.key: writing RSA key ``` ### Create and sign a registration token You create a token and sign it with the private key you just generated in the previous step. **Example – Create a token** The registration token is just a file with any random data that doesn't exceed the maximum size of 245 bytes. You sign the token with the private key to demonstrate that you have access to the private key. The following command uses echo to redirect a string to a file. ``` $ echo > officer1.token ``` Sign the token and save it to a signature file. You will need the signed token, the unsigned token, and the public key to register the CO as an MofN user with the HSM. **Example – Sign the token** Use OpenSSL and the private key to sign the registration token and create the signature file. ``` $ openssl dgst -sha256 \ -sign officer1.key \ -out officer1.token.sig officer1.token ``` ### Register the public key with the HSM After creating a key, the CO must register the public part of the key (the public key) with the HSM. **To register a public key with the HSM** 1. Use the following command to start the cloudhsm\$1mgmt\$1util command line tool. ``` $ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` 1. Use the **loginHSM** command to log in to the HSM as a CO. For more information, see [HSM user management with CloudHSM Management Utility (CMU)](manage-hsm-users-cmu.md). 1. Use the **[registerQuorumPubKey](cloudhsm_mgmt_util-registerQuorumPubKey.md)** command to register the public key. For more information, see the following example or use the **help registerQuorumPubKey** command. **Example – Register a public key with the HSM** The following example shows how to use the **registerQuorumPubKey** command in the cloudhsm\$1mgmt\$1util command line tool to register a CO's public key with the HSM. To use this command, the CO must be logged in to the HSM. Replace these values with your own: ``` 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.2.14) ``` **** The path to a file that contains an unsigned registration token. Can have any random data of max file size of 245 bytes. Required: Yes **** The path to a file that contains the SHA256\$1PKCS mechanism signed hash of the registration token. Required: Yes **** The path to the file that contains the public key of an asymmetric RSA-2048 key pair. Use the private key to sign the registration token. Required: Yes After all COs register their public keys, the output from the **listUsers** command shows this in the `MofnPubKey` column, as shown in the following example. ``` aws-cloudhsm > listUsers Users on server 0(10.0.2.14): Number of users found:7 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PRECO admin NO 0 NO 2 AU app_user NO 0 NO 3 CO officer1 YES 0 NO 4 CO officer2 YES 0 NO 5 CO officer3 YES 0 NO 6 CO officer4 YES 0 NO 7 CO officer5 YES 0 NO Users on server 1(10.0.1.4): Number of users found:7 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PRECO admin NO 0 NO 2 AU app_user NO 0 NO 3 CO officer1 YES 0 NO 4 CO officer2 YES 0 NO 5 CO officer3 YES 0 NO 6 CO officer4 YES 0 NO 7 CO officer5 YES 0 NO ``` ## Step 2. Set the quorum minimum value on the HSM To use quorum authentication for COs, a CO must log in to the HSM and then set the *quorum minimum value*, also known as the *m value*. This is the minimum number of CO approvals that are required to perform HSM user management operations. Any CO on the HSM can set the quorum minimum value, including COs that have not registered a key for signing. You can change the quorum minimum value at any time; for more information, see [Change the minimum value](quorum-authentication-crypto-officers-change-minimum-value.md). **To set the quorum minimum value on the HSM** 1. Use the following command to start the cloudhsm\$1mgmt\$1util command line tool. ``` $ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` 1. Use the **loginHSM** command to log in to the HSM as a CO. For more information, see [HSM user management with CloudHSM Management Utility (CMU)](manage-hsm-users-cmu.md). 1. Use the **setMValue** command to set the quorum minimum value. For more information, see the following example or use the **help setMValue** command. **Example – Set the quorum minimum value on the HSM** This example uses a quorum minimum value of two. You can choose any value from two (2) to eight (8), up to the total number of COs on the HSM. In this example, the HSM has six COs, so the maximum possible value is six. To use the following example command, replace the final number (*2*) with the preferred quorum minimum value. ``` aws-cloudhsm > setMValue 3 <2> *************************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 Setting M Value(2) for 3 on 2 nodes ``` In the preceding example, the first number (3) identifies the *HSM service* whose quorum minimum value you are setting. The following table lists the HSM service identifiers along with their names, descriptions, and the commands that are included in the service. | Service Identifier | Service Name | Service Description | HSM Commands | | --- | --- | --- | --- | | 3 | USER\$1MGMT | HSM user management | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-authentication-crypto-officers-first-time-setup.html) | | 4 | MISC\$1CO | Miscellaneous CO service | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-authentication-crypto-officers-first-time-setup.html) | To get the quorum minimum value for a service, use the **getMValue** command, as in the following example. ``` aws-cloudhsm > getMValue 3 MValue of service 3[USER_MGMT] on server 0 : [2] MValue of service 3[USER_MGMT] on server 1 : [2] ``` The output from the preceding **getMValue** command shows that the quorum minimum value for HSM user management operations (service 3) is now two. After you complete these steps, see [User management with quorum authentication enabled for AWS CloudHSM Management Utility](quorum-authentication-crypto-officers.md). # User management with quorum authentication enabled for AWS CloudHSM Management Utility User management with quorum (M of N) An AWS CloudHSM [crypto officer (CO)](understanding-users-cmu.md#crypto-officer) on the hardware security module (HSM) can configure quorum authentication for the following operations on the HSM: + Creating HSM users + Deleting HSM users + Changing another HSM user's password After the HSM is configured for quorum authentication, COs cannot perform HSM user management operations on their own. The following example shows the output when a CO attempts to create a new user on the HSM. The command fails with a `RET_MXN_AUTH_FAILED` error, which indicates that quorum authentication failed. ``` aws-cloudhsm > createUser CU user1 password *************************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 Creating User user1(CU) on 2 nodes createUser failed: RET_MXN_AUTH_FAILED creating user on server 0(10.0.2.14) failed Retry/Ignore/Abort?(R/I/A): A ``` To perform an HSM user management operation, a CO must complete the following tasks: 1. [Get a *quorum token*](#quorum-crypto-officers-get-token). 1. [Get approvals (signatures) from other COs](#quorum-crypto-officers-get-approval-signatures). 1. [Approve the token on the HSM](#quorum-crypto-officers-approve-token). 1. [Perform the HSM user management operation](#quorum-crypto-officers-use-token). If you have not yet configured the HSM for quorum authentication for COs, do that now. For more information, see [First time setup](quorum-authentication-crypto-officers-first-time-setup.md). ## Step 1. Get a quorum token First the CO must use the cloudhsm\$1mgmt\$1util command line tool to request a *quorum token*. **To get a quorum token** 1. Use the following command to start the cloudhsm\$1mgmt\$1util command line tool. ``` $ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` 1. Use the **loginHSM** command to log in to the HSM as a CO. For more information, see [HSM user management with CloudHSM Management Utility (CMU)](manage-hsm-users-cmu.md). 1. Use the **getToken** command to get a quorum token. For more information, see the following example or use the **help getToken** command. **Example – Get a quorum token** This example gets a quorum token for the CO with user name officer1 and saves the token to a file named `officer1.token`. To use the example command, replace these values with your own: + *officer1* – The name of the CO who is getting the token. This must be the same CO who is logged in to the HSM and is running this command. + *officer1.token* – The name of the file to use for storing the quorum token. In the following command, `3` identifies the *service* for which you can use the token that you are getting. In this case, the token is for HSM user management operations (service 3). For more information, see [Step 2. Set the quorum minimum value on the HSM](quorum-authentication-crypto-officers-first-time-setup.md#quorum-crypto-officers-set-quorum-minimum-value). ``` aws-cloudhsm > getToken 3 officer1 officer1.token getToken success on server 0(10.0.2.14) Token: Id:1 Service:3 Node:1 Key Handle:0 User:officer1 getToken success on server 1(10.0.1.4) Token: Id:1 Service:3 Node:0 Key Handle:0 User:officer1 ``` ## Step 2. Get signatures from approving COs A CO who has a quorum token must get the token approved by other COs. To give their approval, the other COs use their signing key to cryptographically sign the token. They do this outside the HSM. There are many different ways to sign the token. The following example shows how to do it with [OpenSSL](https://www.openssl.org/). To use a different signing tool, make sure that the tool uses the CO's private key (signing key) to sign a SHA-256 digest of the token. **Example – Get signatures from approving COs** In this example, the CO that has the token (officer1) needs at least two approvals. The following example commands show how two COs can use OpenSSL to cryptographically sign the token. In the first command, officer1 signs his or her own token. To use the following example commands, replace these values with your own: + *officer1.key* and *officer2.key* – The name of the file that contains the CO's signing key. + *officer1.token.sig1* and *officer1.token.sig2* – The name of the file to use for storing the signature. Make sure to save each signature in a different file. + *officer1.token* – The name of the file that contains the token that the CO is signing. ``` $ openssl dgst -sha256 -sign officer1.key -out officer1.token.sig1 officer1.token Enter pass phrase for officer1.key: ``` In the following command, officer2 signs the same token. ``` $ openssl dgst -sha256 -sign officer2.key -out officer1.token.sig2 officer1.token Enter pass phrase for officer2.key: ``` ## Step 3. Approve the signed token on the HSM After a CO gets the minimum number of approvals (signatures) from other COs, he or she must approve the signed token on the HSM. **To approve the signed token on the HSM** 1. Create a token approval file. For more information, see the following example. 1. Use the following command to start the cloudhsm\$1mgmt\$1util command line tool. ``` $ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` 1. Use the **loginHSM** command to log in to the HSM as a CO. For more information, see [HSM user management with CloudHSM Management Utility (CMU)](manage-hsm-users-cmu.md). 1. Use the **approveToken** command to approve the signed token, passing the token approval file. For more information, see the following example. **Example – Create a token approval file and approve the signed token on the HSM** The token approval file is a text file in a particular format that the HSM requires. The file contains information about the token, its approvers, and the approvers' signatures. The following shows an example token approval file. ``` # For "Multi Token File Path", type the path to the file that contains # the token. You can type the same value for "Token File Path", but # that's not required. The "Token File Path" line is required in any # case, regardless of whether you type a value. Multi Token File Path = officer1.token; Token File Path = ; # Total number of approvals Number of Approvals = 2; # Approver 1 # Type the approver's type, name, and the path to the file that # contains the approver's signature. Approver Type = 2; # 2 for CO, 1 for CU Approver Name = officer1; Approval File = officer1.token.sig1; # Approver 2 # Type the approver's type, name, and the path to the file that # contains the approver's signature. Approver Type = 2; # 2 for CO, 1 for CU Approver Name = officer2; Approval File = officer1.token.sig2; ``` After creating the token approval file, the CO uses the cloudhsm\$1mgmt\$1util command line tool to log in to the HSM. The CO then uses the **approveToken** command to approve the token, as shown in the following example. Replace *approval.txt* with the name of the token approval file. ``` aws-cloudhsm > approveToken approval.txt approveToken success on server 0(10.0.2.14) approveToken success on server 1(10.0.1.4) ``` When this command succeeds, the HSM has approved the quorum token. To check the status of a token, use the **listTokens** command, as shown in the following example. The command's output shows that the token has the required number of approvals. The token validity time indicates how long the token is guaranteed to persist on the HSM. Even after the token validity time elapses (zero seconds), you can still use the token. ``` aws-cloudhsm > listTokens ===================== Server 0(10.0.2.14) ===================== -------- Token - 0 ---------- Token: Id:1 Service:3 Node:1 Key Handle:0 User:officer1 Token Validity: 506 sec Required num of approvers : 2 Current num of approvals : 2 Approver-0: officer1 Approver-1: officer2 Num of tokens = 1 ===================== Server 1(10.0.1.4) ===================== -------- Token - 0 ---------- Token: Id:1 Service:3 Node:0 Key Handle:0 User:officer1 Token Validity: 506 sec Required num of approvers : 2 Current num of approvals : 2 Approver-0: officer1 Approver-1: officer2 Num of tokens = 1 listTokens success ``` ## Step 4. Use the token for user management operations After a CO has a token with the required number of approvals, as shown in the previous section, the CO can perform one of the following HSM user management operations: + Create an HSM user with the [createUser](cloudhsm_mgmt_util-createUser.md) command + Delete an HSM user with the **deleteUser** command + Change a different HSM user's password with the **changePswd** command For more information about using these commands, see [HSM users](manage-hsm-users.md). The CO can use the token for only one operation. When that operation succeeds, the token is no longer valid. To do another HSM user management operation, the CO must get a new quorum token, get new signatures from approvers, and approve the new token on the HSM. **Note** The MofN token is only valid as long as your current login session is open. If you log out of cloudhsm\$1mgmt\$1util or the network connection disconnects, the token is no longer valid. Similarly, an authorized token can only be used within cloudhsm\$1mgmt\$1util, it cannot be used to authenticate in a different application. In the following example command, the CO creates a new user on the HSM. ``` aws-cloudhsm > createUser CU user1 *************************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 Creating User user1(CU) on 2 nodes ``` After the previous command succeeds, a subsequent **listUsers** command shows the new user. ``` aws-cloudhsm > listUsers Users on server 0(10.0.2.14): Number of users found:8 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin NO 0 NO 2 AU app_user NO 0 NO 3 CO officer1 YES 0 NO 4 CO officer2 YES 0 NO 5 CO officer3 YES 0 NO 6 CO officer4 YES 0 NO 7 CO officer5 YES 0 NO 8 CU user1 NO 0 NO Users on server 1(10.0.1.4): Number of users found:8 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin NO 0 NO 2 AU app_user NO 0 NO 3 CO officer1 YES 0 NO 4 CO officer2 YES 0 NO 5 CO officer3 YES 0 NO 6 CO officer4 YES 0 NO 7 CO officer5 YES 0 NO 8 CU user1 NO 0 NO ``` If the CO tries to perform another HSM user management operation, it fails with a quorum authentication error, as shown in the following example. ``` aws-cloudhsm > deleteUser CU user1 Deleting user user1(CU) on 2 nodes deleteUser failed: RET_MXN_AUTH_FAILED deleteUser failed on server 0(10.0.2.14) Retry/rollBack/Ignore?(R/B/I): I deleteUser failed: RET_MXN_AUTH_FAILED deleteUser failed on server 1(10.0.1.4) Retry/rollBack/Ignore?(R/B/I): I ``` The **listTokens** command shows that the CO has no approved tokens, as shown in the following example. To perform another HSM user management operation, the CO must get a new quorum token, get new signatures from approvers, and approve the new token on the HSM. ``` aws-cloudhsm > listTokens ===================== Server 0(10.0.2.14) ===================== Num of tokens = 0 ===================== Server 1(10.0.1.4) ===================== Num of tokens = 0 listTokens success ``` # Change the quorum minimum value with AWS CloudHSM Management Utility Change the minimum value After you [set the quorum minimum value](quorum-authentication-crypto-officers-first-time-setup.md#quorum-crypto-officers-set-quorum-minimum-value) so that AWS CloudHSM [crypto officers (COs)](understanding-users-cmu.md#crypto-officer) can use quorum authentication, you might want to change the quorum minimum value. The HSM allows you to change the quorum minimum value only when the number of approvers is the same or higher than the current quorum minimum value. For example, if the quorum minimum value is two, at least two COs must approve to change the quorum minimum value. To get quorum approval to change the quorum minimum value, you need a *quorum token* for the **setMValue** command (service 4). To get a quorum token for the **setMValue** command (service 4), the quorum minimum value for service 4 must be higher than one. This means that before you can change the quorum minimum value for COs (service 3), you might need to change the quorum minimum value for service 4. The following table lists the HSM service identifiers along with their names, descriptions, and the commands that are included in the service. | Service Identifier | Service Name | Service Description | HSM Commands | | --- | --- | --- | --- | | 3 | USER\$1MGMT | HSM user management | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-authentication-crypto-officers-change-minimum-value.html) | | 4 | MISC\$1CO | Miscellaneous CO service | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-authentication-crypto-officers-change-minimum-value.html) | **To change the quorum minimum value for crypto officers** 1. Use the following command to start the cloudhsm\$1mgmt\$1util command line tool. ``` $ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg ``` 1. Use the **loginHSM** command to log in to the HSM as a CO. For more information, see [HSM user management with CloudHSM Management Utility (CMU)](manage-hsm-users-cmu.md). 1. Use the **getMValue** command to get the quorum minimum value for service 3. For more information, see the following example. 1. Use the **getMValue** command to get the quorum minimum value for service 4. For more information, see the following example. 1. If the quorum minimum value for service 4 is lower than the value for service 3, use the **setMValue** command to change the value for service 4. Change the value for service 4 to one that is the same or higher than the value for service 3. For more information, see the following example. 1. [Get a *quorum token*](quorum-authentication-crypto-officers.md#quorum-crypto-officers-get-token), taking care to specify service 4 as the service for which you can use the token. 1. [Get approvals (signatures) from other COs](quorum-authentication-crypto-officers.md#quorum-crypto-officers-get-approval-signatures). 1. [Approve the token on the HSM](quorum-authentication-crypto-officers.md#quorum-crypto-officers-approve-token). 1. Use the **setMValue** command to change quorum minimum value for service 3 (user management operations performed by COs). **Example – Get quorum minimum values and change the value for service 4** The following example command shows that the quorum minimum value for service 3 is currently two. ``` aws-cloudhsm > getMValue 3 MValue of service 3[USER_MGMT] on server 0 : [2] MValue of service 3[USER_MGMT] on server 1 : [2] ``` The following example command shows that the quorum minimum value for service 4 is currently one. ``` aws-cloudhsm > getMValue 4 MValue of service 4[MISC_CO] on server 0 : [1] MValue of service 4[MISC_CO] on server 1 : [1] ``` To change the quorum minimum value for service 4, use the **setMValue** command, setting a value that is the same or higher than the value for service 3. The following example sets the quorum minimum value for service 4 to two (2), the same value that is set for service 3. ``` aws-cloudhsm > setMValue 4 2 *************************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 Setting M Value(2) for 4 on 2 nodes ``` The following commands show that the quorum minimum value is now two for service 3 and service 4. ``` aws-cloudhsm > getMValue 3 MValue of service 3[USER_MGMT] on server 0 : [2] MValue of service 3[USER_MGMT] on server 1 : [2] ``` ``` aws-cloudhsm > getMValue 4 MValue of service 4[MISC_CO] on server 0 : [2] MValue of service 4[MISC_CO] on server 1 : [2] ```