Using CloudHSM Management Utility (CMU) to manage two-factor authentication (2FA) for crypto officers

For increased security, you can configure two-factor authentication (2FA) to help protect the cluster. You can only enable 2FA for crypto officers (CO).

Note

You cannot enable 2FA for crypto users (CU) or applications. Two-factor authentication (2FA) is only for CO users.

Understanding 2FA for HSM users

When you log in to a cluster with a 2FA-enabled hardware service module (HSM) account, you provide cloudhsm_mgmt_util (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.

Quorum authentication and 2FA

The cluster uses the same key for quorum authentication and for 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.

Working with 2FA for HSM users

This section describes how to work with 2FA for HSM users, including creating 2FA HSM users, rotating keys, and logging in to the HSM as 2FA-enabled users. For more information about working with HSM users, see Managing HSM users in AWS CloudHSM, Using CloudHSM Management Utility (CMU) to manage users, createUser, loginHSM and logoutHSM, and changePswd.

Creating 2FA users

To enable 2FA for an 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_2048
Signing algorithm includes:
- sha256WithRSAEncryption

Note

If you are using quorum authentication or plan to use quorum authentication, see Quorum authentication and 2FA.

Use CMU and the key pair to create a new CO user with 2FA enabled.

To create CO users with 2FA enabled

In one terminal, perform the following steps:

Access your HSM and log in to the CloudHSM Management utility:


/opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg


aws-cloudhsm>createUser CO MFA <CO USER NAME> -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)?

yCreating 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:

Leave the above terminal in this state. Do not press enter or enter any filename.

In another terminal, perform the following steps:

Access your HSM and log in to the CloudHSM Management utility:


/opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg

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

Run the following command to install a json querying feature for extracting the Digest from authdata file:
```
sudo yum install jq
```
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
```
Convert the public key content, adding "\n" and removing spaces as shown here:
```
-----BEGIN PUBLIC KEY-----\n<PUBLIC KEY>\n-----END PUBLIC KEY----- 
```
Important
The above command shows how "\n" is added immediately after BEGIN PUBLIC KEY-----, spaces between "\n" and the first character of the public key are removed, "\n" is added before -----END PUBLIC KEY, and spaces are removed between "\n" and the end of the public key.

This is the PEM format for public key which is accepted in the authdata file.

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

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.

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=="
        }
    ]
}

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)

Managing 2FA for HSM users

Use change password to change the password for a 2FA user, or to enable or disable 2FA, or to rotate the 2FA key. Each time you enable 2FA, you must provide a public key for 2FA logins.

Change password 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

Use CMU to log in to the HSM as a CO with 2FA enabled.
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 <new-password> -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.
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.

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.

To disable 2FA for CO users with 2FA enabled

Use CMU to log in to the HSM as a CO with 2FA enabled.
Use changePswd to remove 2FA from CO users with 2FA enabled.
```
aws-cloudhsm>changePswd CO example-user <new password>
```
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.
Type y.

CMU confirms the change password operation.

Configuration reference

The following is an example of the 2FA properties in the authdata file for both the 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.

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

Using CMU to manage users

Using CMU to manage quorum authentication

Using CloudHSM Management Utility (CMU) to manage two-factor authentication (2FA) for crypto officers

Note

Topics

Understanding 2FA for HSM users

Quorum authentication and 2FA

Working with 2FA for HSM users

Creating 2FA users

Note

To create CO users with 2FA enabled

Note

Important

Note

Managing 2FA for HSM users

To change passwords or rotate keys for CO users with 2FA enabled

Note

To disable 2FA for CO users with 2FA enabled

Note

Configuration reference