Using quorum authentication for admins
An admin on the HSM can configure quorum authentication for the following operations in the AWS CloudHSM cluster:
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
Get a quorum token
First, the admin must use CloudHSM CLI to request a quorum token.
To get a quorum token
-
Use the following command to start CloudHSM CLI.
-
Use the login command and log in to the cluster as an admin.
aws-cloudhsm>
login --username
admin
--role admin -
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:
-
<admin>
– 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. -
<admin.token>
– 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
<ADMIN>
--role<ADMIN>
--password<PASSWORD>
{ "error_code": 0, "data": { "username": "admin", "role": "admin" } }
aws-cloudhsm >
quorum token-sign generate --service user --token
</path/admin.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
</path/admin.token>
{ "version": "2.0", "approval_data": "AAEAAwAAABgAAAAAAAAAAJ9eFkfcP3mNzJAlfK+OWbNhZG1pbgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABj5vbeAAAAAAAAAAAAAQADAAAAFQAAAAAAAAAAW/v5Euk83amq1fij0zyvD2FkbWluAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGPm9t4AAAAAAAAAAAABAAMAAAAUAAAAAAAAAABDw2XDwfK4hB8a15Xh1E0nYWRtaW4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY+b23gAAAAAAAAAA", "token": "0l2LZkmAHZyAc1hPhyckOoVW33aGrgG77qmDHWQ3CJ8=", "signatures": [] }
The token file consists of the following:
approval_data: A base64 encoded raw data token generated by the HSM.
token: A base64 encoded and SHA-256 hashed token of the approval_data
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": "
<APPROVER_USERNAME>
", "signature": "<APPROVER_RSA2048_BIT_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.
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
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.
-
Decode the base64 encoded unsigned token and place it into a binary file:
$
echo -n '0l2LZkmAHZyAc1hPhyckOoVW33aGrgG77qmDHWQ3CJ8=' | base64 -d > admin.bin
-
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
-
Encode the binary signature into base64:
$
base64 -w0 admin.sig.bin > admin.sig.b64
-
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", "signature": "O6qx7/mUaVkYYVr1PW7l8JJko+Kh3e8zBIqdk3tAiNy+1rW+OsDtvYujhEU4aOFVLcrUFmyB/CX9OQmgJLgx/pyK+ZPEH+GoJGqk9YZ7X1nOXwZRP9g7hKV+7XCtg9TuDFtHYWDpBfz2jWiu2fXfX4/jTs4f2xIfFPIDKcSP8fhxjQ63xEcCf1jzGha6rDQMu4xUWWdtDgfT7um7EJ9dXNoHqLB7cTzphaubNaEFbFPXQ1siGmYKmvETlqe/ssktwyruGFLpXs1n0tJOEglGhx2qbYTs+omKWZdORl5WIWEXW3IXw/Dg5vVObrNpvG0eZKO8nSMc27+cyPySc+ZbNw==" }, { "username": "admin3", "signature": "O6qx7/mUaVkYYVr1PW7l8JJko+Kh3e8zBIqdk3tAiNy+1rW+OsDtvYujhEU4aOFVLcrUFmyB/CX9OQmgJLgx/pyK+ZPEH+GoJGqk9YZ7X1nOXwZRP9g7hKV+7XCtg9TuDFtHYWDpBfz2jWiu2fXfX4/jTs4f2xIfFPIDKcSP8fhxjQ63xEcCf1jzGha6rDQMu4xUWWdtDgfT7um7EJ9dXNoHqLB7cTzphaubNaEFbFPXQ1siGmYKmvETlqe/ssktwyruGFLpXs1n0tJOEglGhx2qbYTs+omKWZdORl5WIWEXW3IXw/Dg5vVObrNpvG0eZKO8nSMc27+cyPySc+ZbNw==" } ] }
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:
For more information about using these commands, see Using CloudHSM CLI.
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": [] } }