# Manage quorum authentication (M of N access control) using CloudHSM CLI Manage quorum authentication (M of N) AWS CloudHSM clusters support quorum authentication, also known as M of N access control. This feature requires HSM users to cooperate for certain operations, adding an extra layer of protection. With quorum authentication, no single user on the HSM can perform quorum-controlled operations on the HSM. Instead, a minimum number of HSM users (at least 2) must cooperate to do these operations. Quorum authentication can control the following operations: + HSM user management by [admin](understanding-users.md#admin): Creating and deleting HSM users or changing a different HSM user's password. For more information, see [User management with quorum authentication enabled for AWS CloudHSM using CloudHSM CLI](quorum-auth-chsm-cli-admin.md). Key points about quorum authentication in AWS CloudHSM. + An HSM user can sign their own quorum token—that is, providing one of the required approvals for quorum authentication. + You choose the minimum number of quorum approvers, which ranges from two (2) to eight (8). + HSMs can store up to 1024 quorum tokens. When this limit is reached, the HSM purges an expired token to create a new one. + Tokens expire ten minutes after creation by default. + For clusters with MFA enabled, the same key is used for quorum authentication and multi-factor authentication (MFA). See [Using CloudHSM CLI to manage MFA](login-mfa-token-sign.md) for more information. + Each HSM can contain one token per Admin service and multiple tokens per Crypto User service. The following topics provide more information about quorum authentication in AWS CloudHSM. **Topics** + [ # Quorum authentication process for CloudHSM CLI ](quorum-auth-chsm-cli-overview.md) + [ # Supported AWS CloudHSM service names and types for quorum authentication with CloudHSM CLI ](quorum-auth-chsm-cli-service-names.md) + [ # Set up quorum authentication for AWS CloudHSM admins using CloudHSM CLI ](quorum-auth-chsm-cli-first-time.md) + [ # User management with quorum authentication enabled for AWS CloudHSM using CloudHSM CLI ](quorum-auth-chsm-cli-admin.md) + [ # Change the quorum minimum value for AWS CloudHSM using CloudHSM CLI ](quorum-auth-chsm-cli-min-value.md) # Quorum authentication process for CloudHSM CLI Quorum authentication process The following steps summarize the quorum authentication processes for CloudHSM CLI. For the specific steps and tools, see [User management with quorum authentication enabled for AWS CloudHSM using CloudHSM CLI](quorum-auth-chsm-cli-admin.md). 1. Each hardware security module (HSM) user creates an asymmetric key for signing. Users 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, the same 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 runs the quorum-controlled operation with the **--approval** argument, supplying the signed quorum token file, which contains all necessary approvals (signatures). 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 and the quorum-controlled operation is performed. # Supported AWS CloudHSM service names and types for quorum authentication with CloudHSM CLI Supported services and types **Admin Services**: Quorum authentication is used for admin privileged services like creating users, deleting users, changing user passwords, setting quorum values, and deactivating quorum and MFA capabilities. **Crypto User Services**: Quorum authentication is used for crypto-user privileged services associated with a specific key like signing with a key, sharing/unsharing a key, wrapping/unwrapping a key, and setting a key's attribute. The quorum value of an associated key is configured when the key is generated, imported, or unwrapped. The quorum value must be equal to or less than the number of users that the key is associated with, which includes users that the key is shared with and the key owner. Each service type is further broken down into a qualifying service name, which contains a specific set of quorum supported service operations that can be performed. **** | Service name | Service type | Service operations | | --- | --- | --- | | user | Admin | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-service-names.html) | | quorum | Admin | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-service-names.html) | | cluster1 | Admin | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-service-names.html) | | key-management | Crypto User | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-service-names.html) | | key-usage | Crypto User | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-service-names.html) | [1] Cluster service is exclusively available on hsm2m.medium # Set up quorum authentication for AWS CloudHSM admins using CloudHSM CLI First time setup The following topics describe the steps that you must complete to configure your hardware security module (HSM) so that AWS CloudHSM [admins](understanding-users.md#admin) can use quorum authentication. You need to do these steps only once when you first configure quorum authentication for admins. After you complete these steps, see [User management with quorum authentication enabled for AWS CloudHSM using CloudHSM CLI](quorum-auth-chsm-cli-admin.md). **Topics** + [ ## Prerequisites ](#quorum-admin-prerequisites) + [ ## Step 1. Create and register a key for signing ](#quorum-admin-create-and-register-key) + [ ## Step 2. Set the quorum minimum value on the HSM ](#quorum-admin-set-quorum-minimum-value-chsm-cli) + [ ## Quorum minimum values ](#cloudhsm_cli-qm-list-minimum) ## Prerequisites To understand this example, you should be familiar with [CloudHSM CLI](cloudhsm_cli.md). ## Step 1. Create and register a key for signing To use quorum authentication, each admin must complete *all* of the following steps: **Topics** + [ ### Create an RSA key pair ](#mofn-key-pair-create-chsm-cli) + [ ### Create and sign a registration token ](#mofn-registration-token-chsm-cli) + [ ### Register the public key with the HSM ](#mofn-register-key-chsm-cli) ### 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. To use this example, replace ** with the name of the file where you want to store the key. ``` $ openssl genrsa -out Generating RSA private key, 2048 bit long modulus .....................................+++ .+++ e is 65537 (0x10001) ``` 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 admin.key -outform PEM -pubout -out admin1.pub 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 registration token** 1. Use the following command to start the CloudHSM CLI: ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm-cli interactive ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive ``` ------ 1. Create a registration token by running the [quorum token-sign generate](cloudhsm_cli-qm-token-gen.md) command: ``` aws-cloudhsm > quorum token-sign generate --service registration --token /path/tokenfile { "error_code": 0, "data": { "path": "/path/tokenfile" } } ``` 1. The [quorum token-sign generate](cloudhsm_cli-qm-token-gen.md) command generates a registration token at the specified file path. Inspect the token file: ``` $ cat /path/tokenfile { "version": "2.0", "tokens": [ { "approval_data": , "unsigned": , "signed": "" } ] } ``` The token file consists of the following: + **approval\$1data**: A base64 encoded randomized data token whose raw data doesn’t exceed the maximum of 245 bytes. + **unsigned**: A base64 encoded and SHA256 hashed token of the approval\$1data. + **signed**: A base64 encoded signed token (signature) of the unsigned token, using the RSA 2048-bit private key previously generated with OpenSSL. You sign the unsigned token with the private key to demonstrate that you have access to the private key. You will need the registration token file fully populated with a signature and the public key to register the admin as a quorum user with the AWS CloudHSM cluster. **Example – Sign the unsigned registration token** 1. Decode the base64 encoded unsigned token and place it into a binary file: ``` $ echo -n '6BMUj6mUjjko6ZLCEdzGlWpR5sILhFJfqhW1ej3Oq1g=' | base64 -d > admin.bin ``` 1. Use OpenSSL and the private key to sign the now binary unsigned registration token and create a binary signature file: ``` $ openssl pkeyutl -sign \ -inkey admin.key \ -pkeyopt digest:sha256 \ -keyform PEM \ -in admin.bin \ -out admin.sig.bin ``` 1. Encode the binary signature into base64: ``` $ base64 -w0 admin.sig.bin > admin.sig.b64 ``` 1. Copy and paste the base64 encoded signature into the token file: ``` { "version": "2.0", "tokens": [ { "approval_data": , "unsigned": , "signed": } ] } ``` ### Register the public key with the HSM After creating a key, the admin must register the public key with the AWS CloudHSM cluster. **To register a public key with the HSM** 1. Use the following command to start CloudHSM CLI: ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm-cli interactive ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive ``` ------ 1. Using CloudHSM CLI, log in as an admin. ``` aws-cloudhsm > login --username --role admin Enter password: { "error_code": 0, "data": { "username": "", "role": "admin" } } ``` 1. Use the **[Register a user's token-sign quorum strategy using CloudHSM CLI](cloudhsm_cli-user-chqm-token-reg.md)** command to register the public key. For more information, see the following example or use the **help user change-quorum token-sign register** command. **Example – Register a public key with AWS CloudHSM cluster** The following example shows how to use the **user change-quorum token-sign register** command in CloudHSM CLI to register an admin' public key with the HSM. To use this command, the admin must be logged in to the HSM. Replace these values with your own: ``` aws-cloudhsm > user change-quorum token-sign register --public-key --signed-token { "error_code": 0, "data": { "username": "admin", "role": "admin" } } ``` **/path/admin.pub**: The filepath to the public key PEM file **Required**: Yes **/path/tokenfile**: The filepath with token signed by user private key **Required**: Yes After all admins register their public keys, the output from the **user list** command shows this in the quorum field, stating the enabled quorum strategy in use, as shown below: ``` aws-cloudhsm > user list { "error_code": 0, "data": { "users": [ { "username": "admin", "role": "admin", "locked": "false", "mfa": [], "quorum": [ { "strategy": "token-sign", "status": "enabled" } ], "cluster-coverage": "full" }, { "username": "admin2", "role": "admin", "locked": "false", "mfa": [], "quorum": [ { "strategy": "token-sign", "status": "enabled" } ], "cluster-coverage": "full" }, { "username": "admin3", "role": "admin", "locked": "false", "mfa": [], "quorum": [ { "strategy": "token-sign", "status": "enabled" } ], "cluster-coverage": "full" }, { "username": "admin4", "role": "admin", "locked": "false", "mfa": [], "quorum": [ { "strategy": "token-sign", "status": "enabled" } ], "cluster-coverage": "full" }, { "username": "app_user", "role": "internal(APPLIANCE_USER)", "locked": "false", "mfa": [], "quorum": [], "cluster-coverage": "full" } ] } } ``` In this example, the AWS CloudHSM cluster has two HSMs, each with the same admins, as shown in the following output from the **user list** command. For more information about creating users, see [User management with CloudHSM CLI](manage-hsm-users-chsm-cli.md) ## Step 2. Set the quorum minimum value on the HSM To use quorum authentication, an admin must log in to the HSM and then set the *quorum minimum value*. This is the minimum number of admin approvals that are required to perform HSM user management operations. Any admin on the HSM can set the quorum minimum value, including admins who 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-auth-chsm-cli-min-value.md). **To set the quorum minimum value on the HSM** 1. Use the following command to start CloudHSM CLI: ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm-cli interactive ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive ``` ------ 1. Using CloudHSM CLI, log in as an admin. ``` aws-cloudhsm > login --username --role admin Enter password: { "error_code": 0, "data": { "username": "", "role": "admin" } } ``` 1. Use the **[Update a quorum value using CloudHSM CLI](cloudhsm_cli-qm-token-set-qm.md)** command to set the quorum minimum value. The `--service` flag identifies the HSM service that you're setting values for. See the following example or use the **help quorum token-sign set-quorum-value** command for more information. **Example – Set the quorum minimum value on the HSM** This example uses a quorum minimum value of two (2). You can choose any value from two (2) to eight (8), up to the total number of admins on the HSM. In this example, the HSM has four (4) admins, so the maximum possible value is four (4). To use the following example command, replace the final number (*<2>*) with the preferred quorum minimum value. ``` aws-cloudhsm > quorum token-sign set-quorum-value --service user --value <2> { "error_code": 0, "data": "Set quorum value successful" } ``` In this example, the **[Show quorum values using CloudHSM CLI](cloudhsm_cli-qm-token-list-qm.md)** command lists the HSM service types, names, and descriptions that are included in the service. ## Quorum minimum values To get the quorum minimum value for a service, use the **quorum token-sign list-quorum-values** command: ``` aws-cloudhsm > quorum token-sign list-quorum-values { "error_code": 0, "data": { "user": 2, "quorum": 1 } } ``` The output from the preceding **quorum token-sign list-quorum-values** command shows that the quorum minimum value for HSM user service, responsible for user management operations, is now two (2). After you complete these steps, see [User management with quorum (M of N)](quorum-auth-chsm-cli-admin.md). **Admin Services**: Quorum authentication is used for admin privileged services like creating users, deleting users, changing user passwords, setting quorum values, and deactivating quorum and MFA capabilities. **Crypto User Services**: Quorum authentication is used for crypto-user privileged services associated with a specific key like signing with a key, sharing/unsharing a key, wrapping/unwrapping a key, and setting a key's attribute. The quorum value of an associated key is configured when the key is generated, imported, or unwrapped. The quorum value must be equal to or less than the number of users that the key is associated with, which includes users that the key is shared with and the key owner. Each service type is further broken down into a qualifying service name, which contains a specific set of quorum supported service operations that can be performed. **** | Service name | Service type | Service operations | | --- | --- | --- | | user | Admin | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-first-time.html) | | quorum | Admin | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-first-time.html) | | cluster1 | Admin | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-first-time.html) | | key-management | Crypto User | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-first-time.html) | | key-usage | Crypto User | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/quorum-auth-chsm-cli-first-time.html) | [1] Cluster service is exclusively available on hsm2m.medium # User management with quorum authentication enabled for AWS CloudHSM using CloudHSM CLI User management with quorum (M of N) An AWS CloudHSM [admin](understanding-users.md#admin) on the hardware security module (HSM) can configure quorum authentication for the following operations in the AWS CloudHSM cluster: + **[Create an AWS CloudHSM user with CloudHSM CLI](cloudhsm_cli-user-create.md)** + **[Delete an AWS CloudHSM user with CloudHSM CLI](cloudhsm_cli-user-delete.md)** + **[Change a user's password with CloudHSM CLI](cloudhsm_cli-user-change-password.md)** + **[The user change-mfa category in CloudHSM CLI](cloudhsm_cli-user-change-mfa.md)** After the AWS CloudHSM cluster is configured for quorum authentication, admins cannot perform HSM user management operations on their own. The following example shows the output when an admin attempts to create a new user on the HSM. The command fails with an error, stating that quorum authentication is required. ``` aws-cloudhsm > user create --username user1 --role crypto-user Enter password: Confirm password: { "error_code": 1, "data": "Quorum approval is required for this operation" } ``` To perform an HSM user management operation, an admin must complete the following tasks: **Topics** + [ ## Step 1. Get a quorum token ](#quorum-admin-gen-token-chsm-cli) + [ ## Step 2. Get signatures from approving admins ](#quorum-admin-get-approval-signatures-chsm-cli) + [ ## Step 3. Approve the token on the AWS CloudHSM cluster and execute a user management operation ](#quorum-admin-approve-token-chsm-cli) ## Step 1. Get a quorum token First, the admin must use CloudHSM CLI to request a *quorum token*. **To get a quorum token** 1. Use the following command to start CloudHSM CLI. ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm-cli interactive ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive ``` ------ 1. Using CloudHSM CLI, log in as an admin. ``` aws-cloudhsm > login --username --role admin Enter password: { "error_code": 0, "data": { "username": "", "role": "admin" } } ``` 1. Use the **quorum token-sign generate** command to generate a quorum token. For more information, see the following example or use the **help quorum token-sign generate** command. **Example – Generate a quorum token** This example gets a quorum token for the admin with user name `admin` and saves the token to a file named `admin.token`. To use the example command, replace these values with your own: + ** – The name of the admin who is getting the token. This must be the same admin who is logged in to the HSM and is running this command. + ** – The name of the file to use for storing the quorum token. In the following command, `user` identifies the *service name* for which you can use the token that you are generating. In this case, the token is for HSM user management operations (`user` service). . ``` aws-cloudhsm > login --username --role admin --password { "error_code": 0, "data": { "username": "", "role": "admin" } } ``` ``` aws-cloudhsm > quorum token-sign generate --service user --token { "error_code": 0, "data": { "path": "/home/tfile" } } ``` The **quorum token-sign generate** command generates a user service quorum token at the specified file path. The token file can be inspected: ``` $ cat { "version": "2.0", "service": "user-management", "approval_data": "AAEAAwAAABgAAAAAAAAAAJ9eFkfcP3mNzJAlfK+OWbNhZG1pbgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABj5vbeAAAAAAAAAAAAAQADAAAAFQAAAAAAAAAAW/v5Euk83amq1fij0zyvD2FkbWluAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGPm9t4AAAAAAAAAAAABAAMAAAAUAAAAAAAAAABDw2XDwfK4hB8a15Xh1E0nYWRtaW4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY+b23gAAAAAAAAAA", "token": "0l2LZkmAHZyAc1hPhyckOoVW33aGrgG77qmDHWQ3CJ8=", "signatures": [] } ``` The token file consists of the following: + **service**: An identifier for the quorum service the token is associated with. + **approval\$1data**: A base64 encoded raw data token generated by the HSM. + **token**: A base64 encoded and SHA-256 hashed token of the approval\$1data + **signatures**: An array of base64 encoded signed tokens (signatures) of the unsigned token, where each signature of an approver is in the form of a JSON object literal: ``` { "username": "", "role": "", "signature": "" } ``` Each signature is created from the result of an approver using their corresponding RSA 2048-bit private key whose public key was registered with the HSM. The generated user service quorum token can be confirmed to exist on the CloudHSM cluster by running the **quorum token-sign list** command: ``` aws-cloudhsm > quorum token-sign list { "error_code": 0, "data": { "tokens": [ { "username": "admin", "service": "user", "approvals-required": { "value": 2 }, "number-of-approvals": { "value": 0 }, "token-timeout-seconds": { "value": 597 }, "cluster-coverage": "full" } ] } } ``` The `token-timeout-seconds` time indicates the timeout period in seconds for a generated token to be approved before it expires. ## Step 2. Get signatures from approving admins An admin who has a quorum token must get the token approved by other admins. To give their approval, the other admins 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 admin's private key (signing key) to sign a SHA-256 digest of the token. **Example – Get signatures from approving admins** In this example, the admin that has the token (`admin`) needs at least two (2) approvals. The following example commands show how two (2) admins can use OpenSSL to cryptographically sign the token. 1. Decode the base64 encoded unsigned token and place it into a binary file: ``` $ echo -n '0l2LZkmAHZyAc1hPhyckOoVW33aGrgG77qmDHWQ3CJ8=' | base64 -d > admin.bin ``` 1. Use OpenSSL and the respective private key of the approver `(admin3)` to sign the now binary quorum unsigned token for the user service and create a binary signature file: ``` $ openssl pkeyutl -sign \ -inkey admin3.key \ -pkeyopt digest:sha256 \ -keyform PEM \ -in admin.bin \ -out admin.sig.bin ``` 1. Encode the binary signature into base64: ``` $ base64 -w0 admin.sig.bin > admin.sig.b64 ``` 1. Finally, copy and paste the base64 encoded signature into the token file, following the JSON object literal format specified earlier for approver signature: ``` { "version": "2.0", "approval_data": "AAEAAwAAABgAAAAAAAAAAJ9eFkfcP3mNzJAlfK+OWbNhZG1pbgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABj5vbeAAAAAAAAAAAAAQADAAAAFQAAAAAAAAAAW/v5Euk83amq1fij0zyvD2FkbWluAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGPm9t4AAAAAAAAAAAABAAMAAAAUAAAAAAAAAABDw2XDwfK4hB8a15Xh1E0nYWRtaW4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY+b23gAAAAAAAAAA", "token": "0l2LZkmAHZyAc1hPhyckOoVW33aGrgG77qmDHWQ3CJ8=", "signatures": [ { "username": "admin2", "role": "admin", "signature": "O6qx7/mUaVkYYVr1PW7l8JJko+Kh3e8zBIqdk3tAiNy+1rW+OsDtvYujhEU4aOFVLcrUFmyB/CX9OQmgJLgx/pyK+ZPEH+GoJGqk9YZ7X1nOXwZRP9g7hKV+7XCtg9TuDFtHYWDpBfz2jWiu2fXfX4/jTs4f2xIfFPIDKcSP8fhxjQ63xEcCf1jzGha6rDQMu4xUWWdtDgfT7um7EJ9dXNoHqLB7cTzphaubNaEFbFPXQ1siGmYKmvETlqe/ssktwyruGFLpXs1n0tJOEglGhx2qbYTs+omKWZdORl5WIWEXW3IXw/Dg5vVObrNpvG0eZKO8nSMc27+cyPySc+ZbNw==" }, { "username": "admin3", "role": "admin", "signature": "O6qx7/mUaVkYYVr1PW7l8JJko+Kh3e8zBIqdk3tAiNy+1rW+OsDtvYujhEU4aOFVLcrUFmyB/CX9OQmgJLgx/pyK+ZPEH+GoJGqk9YZ7X1nOXwZRP9g7hKV+7XCtg9TuDFtHYWDpBfz2jWiu2fXfX4/jTs4f2xIfFPIDKcSP8fhxjQ63xEcCf1jzGha6rDQMu4xUWWdtDgfT7um7EJ9dXNoHqLB7cTzphaubNaEFbFPXQ1siGmYKmvETlqe/ssktwyruGFLpXs1n0tJOEglGhx2qbYTs+omKWZdORl5WIWEXW3IXw/Dg5vVObrNpvG0eZKO8nSMc27+cyPySc+ZbNw==" } ] } ``` ## Step 3. Approve the token on the AWS CloudHSM cluster and execute a user management operation After an admin has the necessary approvals/signatures, as detailed in the previous section, the admin can supply that token to the AWS CloudHSM cluster along with one of the following user management operations: + **[create](cloudhsm_cli-user-create.md)** + **[delete](cloudhsm_cli-user-delete.md)** + **[change-password](cloudhsm_cli-user-change-password.md)** + **[user change-mfa](cloudhsm_cli-user-change-mfa.md)** For more information about using these commands, see [User management with CloudHSM CLI](manage-hsm-users-chsm-cli.md). During the transaction, the token will be approved within the AWS CloudHSM cluster and execute the requested user management operation. The success of the user management operation is contingent upon both a valid approved quorum token and a valid user management operation. The admin 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 admin must repeat the above outlined process. That is, the admin must generate a new quorum token, get new signatures from approvers, and then approve and consume the new token on the HSM with the requested user management operation. **Note** The quorum token is only valid as long as your current login session is open. If you log out of CloudHSM CLI or if the network disconnects, the token is no longer valid. Similarly, an authorized token can only be used within CloudHSM CLI. It cannot be used to authenticate in a different application. **Example Creating a new user as an admin** In the following example, a logged in admin creates a new user on the HSM: ``` aws-cloudhsm > user create --username user1 --role crypto-user --approval /path/admin.token Enter password: Confirm password: { "error_code": 0, "data": { "username": "user1", "role": "crypto-user" } } ``` The admin then enters the **user list** command to confirm the creation of the new user: ``` aws-cloudhsm > user list { "error_code": 0, "data": { "users": [ { "username": "admin", "role": "admin", "locked": "false", "mfa": [], "quorum": [ { "strategy": "token-sign", "status": "enabled" } ], "cluster-coverage": "full" }, { "username": "admin2", "role": "admin", "locked": "false", "mfa": [], "quorum": [ { "strategy": "token-sign", "status": "enabled" } ], "cluster-coverage": "full" }, { "username": "admin3", "role": "admin", "locked": "false", "mfa": [], "quorum": [ { "strategy": "token-sign", "status": "enabled" } ], "cluster-coverage": "full" }, { "username": "admin4", "role": "admin", "locked": "false", "mfa": [], "quorum": [ { "strategy": "token-sign", "status": "enabled" } ], "cluster-coverage": "full" }, { "username": "user1", "role": "crypto-user", "locked": "false", "mfa": [], "quorum": [], "cluster-coverage": "full" }, { "username": "app_user", "role": "internal(APPLIANCE_USER)", "locked": "false", "mfa": [], "quorum": [], "cluster-coverage": "full" } ] } } ``` If the admin tries to perform another HSM user management operation, it fails with a quorum authentication error: ``` aws-cloudhsm > user delete --username user1 --role crypto-user { "error_code": 1, "data": "Quorum approval is required for this operation" } ``` As shown below, the **quorum token-sign list** command shows that the admin has no approved tokens. To perform another HSM user management operation, the admin must generate a new quorum token, get new signatures from approvers, and execute the desired user management operation with the --approval argument to supply the quorum token to be approved and consumed during execution of the user management operation. ``` aws-cloudhsm > quorum token-sign list { "error_code": 0, "data": { "tokens": [] } } ``` # Change the quorum minimum value for AWS CloudHSM using CloudHSM CLI Change the minimum value After [setting the quorum minimum value](quorum-auth-chsm-cli-first-time.md#quorum-admin-set-quorum-minimum-value-chsm-cli) for CloudHSM [admins](understanding-users.md#admin), you might need to adjust the quorum minimum value. The HSM allows changes to the quorum minimum value only when the number of approvers meets or exceeds the current value. For example, with a quorum minimum value of two (2), at least two (2) admins must approve any changes. **Note** The quorum value of the user service must always be less than or equal to the quorum value of the quorum service. For information on service names, see [Supported AWS CloudHSM service names and types for quorum authentication with CloudHSM CLI](quorum-auth-chsm-cli-service-names.md). To get quorum approval to change the quorum minimum value, you need a *quorum token* for the **quorum service** using the **quorum token-sign set-quorum-value** command. To generate a quorum token for the for the **quorum service** using the **quorum token-sign set-quorum-value** command, the quorum service must be higher than one (1). This means that before you can change the quorum minimum value for *user service*, you might need to change the quorum minimum value for *quorum service*. **Steps to change the quorum minimum value for admins** 1. Start the CloudHSM CLI interactive mode. ------ #### [ Linux ] ``` $ /opt/cloudhsm/bin/cloudhsm-cli interactive ``` ------ #### [ Windows ] ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive ``` ------ 1. Using CloudHSM CLI, log in as an admin. ``` aws-cloudhsm > login --username --role admin Enter password: { "error_code": 0, "data": { "username": "", "role": "admin" } } ``` 1. Check current quorum minimum values: ``` aws-cloudhsm > quorum token-sign list-quorum-values ``` 1. If the quorum minimum value for the quorum service is lower than the value for the user service, change the *quorum service* value: ``` aws-cloudhsm > quorum token-sign set-quorum-value --service quorum --value <3> ``` 1. [Generate a quorum token](quorum-auth-chsm-cli-admin.md#quorum-admin-gen-token-chsm-cli) for the quorum service. 1. [Get approvals (signatures) from other admins](quorum-auth-chsm-cli-admin.md#quorum-admin-get-approval-signatures-chsm-cli). 1. [Approve the token on the CloudHSM cluster and execute a user management operation.](quorum-auth-chsm-cli-admin.md#quorum-admin-approve-token-chsm-cli). 1. Change the quorum minimum value for the *user service*: ``` aws-cloudhsm > quorum token-sign set-quorum-value ``` **Example Adjusting *quorum service* minimum values** 1. **Check current values**. The example shows that the quorum minimum value for *user service* is currently two (2). ``` aws-cloudhsm > quorum token-sign list-quorum-values { "error_code": 0, "data": { "user": 2, "quorum": 1 } } ``` 1. **Change quorum service value**. Set the quorum minimum value for *quorum service* to a value that is the same or higher than the value for *user service*. This example sets the quorum minimum value for *quorum service* to two (2), the same value that was set for *user service* in the previous example. ``` aws-cloudhsm > quorum token-sign set-quorum-value --service quorum --value 2 { "error_code": 0, "data": "Set quorum value successful" } ``` 1. **Verify the changes**. This example shows that the quorum minimum value is now two (2) for *user service* and *quorum service*. ``` aws-cloudhsm > quorum token-sign list-quorum-values { "error_code": 0, "data": { "user": 2, "quorum": 2 } } ```