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

How can I allow a user to wrap a key, and allow another user to unwrap only that same key?Short descriptionYou 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.

ResolutionExport 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 toolBefore you begin using the cloudhsm_mgmt_util tool, see Getting started with CloudHSM Management Utility (CMU).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               NOBecause 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 HSMLog 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 rootKey similar to the following:Command:  genSymKey -t 31 -s 32 -l rootKey        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: SUCCESSThis example uses key handle 786512.Create a session key using the genSymKey command to wrap the key to disk, and unwrap back to your HSMCreate 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: SUCCESSIn 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 secretExport the symmetric key 786512 to a file on your local drive. The symmetric key 786512 encrypts with the session key 786511. This encryption makes sure that you never store the symmetric key 786512 in plaintext outside of your HSM. After you wrap the rootKey to your local drive, use the unWrapKey command to import the rootKey 786512 back to the HSM. Create a copy of the rootKey inside the HSM with a different key handle. Then, change the attributes of the rootKey copy to restrict how the key is used.In this example, the sessionKey 786511 wraps the rootKey 786512, and saves it to the local drive in as the root.key file:Command:  wrapKey -k 786512 -w 786511 -out root.key        Key Wrapped.        Wrapped Key written to file "root.key length 312                Cfm2WrapKey returned: 0x00 : HSM Return: SUCCESSNote: 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 handleImport the key root.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 root.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: SUCCESSCommand:  unWrapKey -f root.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: SUCCESSVerify key handles and assign attributesUse the cloudhsm_mgmt_util command to check all the key handles owned by the crypto_user3. In this example, note the rootKey 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. Doing 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 rootKey 786512.Note: The session key handle 786511 isn't shown because it only remains for the lifetime of the session.aws-cloudhsm>findAllKeys 6 0Keys on server 0(172.31.3.131):Number of keys found 3number of keys matched from start index 0::3786512,786523,786524findAllKeys success on server 0(172.31.3.131)Keys on server 1(172.31.4.209):Number of keys found 3number of keys matched from start index 0::3786512,786523,786524findAllKeys 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 keysThe 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 thecluster. Cav server does NOT synchronize these changes with thenodes on which this operation is not executed or failed, pleaseensure this operation is executed on all nodes in the cluster.****************************************************************Do you want to continue(y/n)?ysetAttribute 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 262.aws-cloudhsm>setAttribute 786524 263 0*************************CAUTION********************************This is a CRITICAL operation, should be done on all nodes in thecluster. Cav server does NOT synchronize these changes with thenodes on which this operation is not executed or failed, pleaseensure this operation is executed on all nodes in the cluster.****************************************************************Do you want to continue(y/n)?ysetAttribute success on server 0(172.31.3.131)setAttribute success on server 1(172.31.4.209)You now have the rootKey 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 correctlyRun the wrapKey command with the key_mgmt_util command line tool.Wrap the rootKey 786512 to your local drive with the key handle 786523 you assigned for unwrapping.Then, wrap the rootKey 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 policiesCommand:  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: SUCCESSIn 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 falseThe 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 262Attribute Value on server 0(172.31.3.131):OBJ_ATTR_WRAP0x00000000Attribute Value on server 1(172.31.4.209):OBJ_ATTR_WRAP0x00000000Share keys with other usersShare 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 makes sure 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 thecluster. Cav server does NOT synchronize these changes with thenodes on which this operation is not executed or failed, pleaseensure this operation is executed on all nodes in the cluster.****************************************************************Do you want to continue(y/n)?yshareKey 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 thecluster. Cav server does NOT synchronize these changes with thenodes on which this operation is not executed or failed, pleaseensure this operation is executed on all nodes in the cluster.****************************************************************Do you want to continue(y/n)?yshareKey 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 HSMTest 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: SUCCESSRelated informationActivate the CloudHSM cluster