Get a quorum token Get signatures from approving admins Approve the token on the AWS CloudHSM cluster and execute a user management operation

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
Get signatures from approving admins
Approve the token on the AWS CloudHSM cluster and execute a user management operation

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. 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.

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": []
  }
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

First time setup

Change the minimum value