How do I share keys with others users to only allow certain crypto functions in CloudHSM?

Last updated: 2019-05-28

How can I allow a user to wrap a key, and allow another user to unwrap only that same key?

Short Description

You can share user's access to keys stored in HSMs in your AWS CloudHSM cluster. However, this allows your users access for all permissions, such as wrap, unwrap, encrypt, and decrypt.

Resolution

Export a key and then re-import it, twice. The imported key attributes change with permissions to wrap or unwrap. Then, the key is shared with different users to perform the wrap or unwrap functions.

List all users in your cluster using the cloudhsm_mgmt_util command line tool

Before you begin using the cloudhsm_mgmt_util tool, see Getting Started with cloudhsm_mgmt_util.

Run the listUsers command similar to the following:

Number of users found:8

    User Id             User Type       User Name                          MofnPubKey    LoginFailureCnt         2FA
         1              CO              admin                                    NO               0               NO
         2              AU              app_user                                 NO               0               NO
         3              CO              officer1                                 NO               0               NO
         4              CO              crypto_user1                             NO               0               NO
         5              CO              crypto_user2                             NO               0               NO
         6              CU              crypto_user3                             NO               0               NO
         7              CU              crypto_user4                             NO               0               NO
         8              CU              crypto_user5                             NO               0               NO

Because crypto_user1 and crypto_user2 are crypto officers, they can't own keys. This example uses crypto user's crypto_user3, crypto_user4, and crypto_user5.

Use the genSymKey command with the key_mgmt_util command line tool to create an AES symmetric key in your HSM

Log into your HSM using crypto_user3, then use the key_mgmt_util tool to create a symmetric key to encrypt and decrypt. Use the genSymKey command to create an AES 256 bit key with the label masterKey similar to the following:

Command:  genSymKey -t 31 -s 32 -l masterKey

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 786512

        Cluster Error Status
        Node id 3 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 4 and err state 0x00000000 : HSM Return: SUCCESS

This example uses key handle 786512.

Create a session key using the genSymKey command to wrap the key to disk, and unwrap back to your HSM

Create a session key using the -sess parameter. Be sure that the session window remains open, the connection is established, and that crypto_user3 remains logged in. Use the genSymKey command with the label sessionKey to identify this key later.

Command:  genSymKey -t 31 -s 32 -sess -l sessionKey

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 786511

        Cluster Error Status
        Node id 3 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 4 and err state 0x00000000 : HSM Return: SUCCESS

In this example, the session key 786511 performs the operations wrapKey and unWrapKey.

Note: The session key is deleted after the session closes.

Use the wrapKey command to write the key to disk and keep the key secret

Export the symmetric key 786512 to a file on your local drive. The symmetric key 786512 encrypts with the session key 786511. This encryption assures that you never store the symmetric key 786512 in plaintext outside of your HSM. After you wrap the masterKey to your local drive, use the unWrapKey command to import the masterKey 786512 back to the HSM. Create a copy of the masterKey inside the HSM with a different key handle. Then, change the attributes of the masterKey copy to restrict how the key is used.

In this example, the sessionKey 786511 wraps the masterKey 786512, and saves it to the local drive in as the master.key file:

Command:  wrapKey -k 786512 -w 786511 -out master.key

        Key Wrapped.

        Wrapped Key written to file "master.key length 312
        
        Cfm2WrapKey returned: 0x00 : HSM Return: SUCCESS

Note: You can view the wrapped key in your local directory using the ls command.

Use the unWrapKey command to import the key back to your HSM with a new handle

Import the key master.key back into the HSM using the unWrapKey command. This example creates the new key handles 786523 and 786524.

Important: Do this step twice.

Command:  unWrapKey -f master.key -w 786511

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Key Unwrapped.  Key Handle: 786523

        Cluster Error Status
        Node id 3 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 4 and err state 0x00000000 : HSM Return: SUCCESS

Command:  unWrapKey -f master.key -w 786511

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Key Unwrapped.  Key Handle: 786524

        Cluster Error Status
        Node id 3 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 4 and err state 0x00000000 : HSM Return: SUCCESS

Verify key handles and assign attributes

Use the cloudhsm_mgmt_util command to check all the key handles owned by the crypto_user3. In this example, note the masterKey 786512, the imported key handle 786523, and the imported key handle 786524. You enter user ID 6 and 0 for crypto_user3 to show that you don't want the hash of all the keys calculated. This allows you to see the key handles that you use in the HSM. The key handles shown by the findAllKeys command are cryptographically identical, with the same attributes as the masterKey 786512.

Note: The session key handle 786511 isn't shown because it only remains for the lifetime of the session.

aws-cloudhsm>findAllKeys 6 0
Keys on server 0(172.31.3.131):
Number of keys found 3
number of keys matched from start index 0::3
786512,786523,786524
findAllKeys success on server 0(172.31.3.131)
Keys on server 1(172.31.4.209):
Number of keys found 3
number of keys matched from start index 0::3
786512,786523,786524
findAllKeys success on server 1(172.31.4.209)

This example assigns one key handle for wrapping key 786524, and the other key handle for unwrapping key 786523.

Use the cloudhsm_mgmt_util with the command setAttribute to configure wrapping/unwrapping attributes of keys

The setAttribute command needs the key handle and the attribute id. The attribute id refers to an integer that correlates to a key attribute. List these using the listAttibutes command. Use the aws-cloudhsm>setAttribute command with key 786523 to have the OBJ_ATTR_WRAP attribute values 262 and 0.

aws-cloudhsm>setAttribute 786523 262 0
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes 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
setAttribute success on server 0(172.31.3.131)
setAttribute success on server 1(172.31.4.209)

Then, use the setAttribute command with key 786524 to set the OBJ_ATTR_UNWRAP attribute values to 263 and 0. The OBJ_ATTR_WRAP attribute is 263.

aws-cloudhsm>setAttribute 786524 263 0
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes 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
setAttribute success on server 0(172.31.3.131)
setAttribute success on server 1(172.31.4.209)

You now have the masterKey 786512 that can both wrap and unwrap, key 786524 that can only wrap, and key 786523 that can only unwrap.

In this example, crypto_user3 owns keys 786512, 786523, 786524 and the keys aren't shared.

Test wrapping the key to confirm that all attributes are set correctly

Run the wrapKey command with the key_mgmt_util command line tool.

Wrap the masterKey 786512 to your local drive with the key handle 786523 you assigned for unwrapping.

Then, wrap the masterKey 786512 to your local drive with the key handle 786524 you assigned for wrapping.

Command:  wrapKey -k 786512 -w 786523 -out wrapped.key

        Cfm2WrapKey returned: 0xb3

        HSM Error: This operation violates the current configured/FIPS policies

Command:  wrapKey -k 786512 -w 786524 -out wrapped.key

        Key Wrapped.

        Wrapped Key written to file "wrapped.key.test length 309

        Cfm2WrapKey returned: 0x00 : HSM Return: SUCCESS

In this example, the command fails for the wrapping key 786523 as noted in the HSM error. The HSM error is because the attribute to wrap OBJ_ATTR_WRAP is set to 0.

Run the getAttribute command to verify that the key attribute value is set to false

The getAttribute command uses the key_mgmt_util and cloudhsm_mgmt_util tools. Although the syntax is different for both command line tools, they each show the result of the attributes. This example uses the cloudhsm_mgmt_util because it doesn't require attributes to save to file.

aws-cloudhsm>getAttribute 786523 262
Attribute Value on server 0(172.31.3.131):
OBJ_ATTR_WRAP
0x00000000

Attribute Value on server 1(172.31.4.209):
OBJ_ATTR_WRAP
0x00000000

Share keys with other users

Share keys using the cloudhsm_mgm_util command to crypto_user4 (with User ID 7) and crypto_user5 (User ID 8). Share the unwrapping key 786523 to crypto_user4 and the wrapping key 786524 to crypto_user5. This allows these users crypto_user4 and crypto_user5 to use the key for cryptographic functions, but not delete, export, share, unshare, or change the key attributes. This assures that user's crypto_user4 and crypto_user5 can use the key only for the operations specified by crypto_user3 when assigning the key attributes.

aws-cloudhsm>shareKey 786523 7 1
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes 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
shareKey success on server 0(172.31.3.131)
shareKey success on server 1(172.31.4.209)


aws-cloudhsm>shareKey 786524 8 1
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes 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
shareKey success on server 0(172.31.3.131)
shareKey success on server 1(172.31.4.209)

Test functionality of wrap vs. unwrap using the wrapKey command between the disk and your HSM

Test that crypto_user4 (User ID 7) can unwrap the key rapped with crypto_user3.

The keys crypto_user3 and crypto_user_4 are the same cryptographically and are used to perform the functions for wrapping and unwrapping separately.

Command:  unWrapKey -f wrapped.key -w 786523

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Key Unwrapped.  Key Handle: 1048669

        Cluster Error Status
        Node id 3 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 4 and err state 0x00000000 : HSM Return: SUCCESS

Did this article help you?

Anything we could improve?


Need more help?