Using trusted keys in AWS CloudHSM

AWS CloudHSM supports trusted key wrapping to protect data keys from insider threats. This topic describes how to create trusted keys to secure data.

Understanding trusted keys

A trusted key is a key that is used to wrap other keys and that admins and cryptographic officers (COs) specifically identify as trusted using the attribute CKA_TRUSTED. Additionally, admins and cryptographic officers (COs) use CKA_UNWRAP_TEMPLATE and related attributes to specify what actions data keys can do once they are unwrapped by a trusted key. Data keys that are unwrapped by the trusted key must also contain these attributes for the unwrap operation to succeed, which helps ensure that unwrapped data keys are only permitted for the use you intend.

Use the attribute CKA_WRAP_WITH_TRUSTED to identify all of the data keys you want to wrap with trusted keys. Doing this allows you to restrict data keys so applications can only use trusted keys to unwrap them. Once you set this attribute on the data keys, the attribute becomes read-only and you cannot change it. With these attributes in place, applications can only unwrap your data keys with the keys you trust, and unwraps always result in data keys with attributes that limit how these keys can be used.

Trusted key attributes

The following attributes allow you to mark a key as trusted, specify a data key can only be wrapped and unwrapped with a trusted key, and control what a data key can do after it is unwrapped:

• CKA_TRUSTED: Apply this attribute (in addition to CKA_UNWRAP_TEMPLATE) to the key that will wrap data keys to specify that an admin or crypto officer (CO) has done the necessary diligence and trusts this key. Only an admin or CO can set CKA_TRUSTED. The crypto user (CU) owns the key, but only a CO can set its CKA_TRUSTED attribute.

• CKA_WRAP_WITH_TRUSTED: Apply this attribute to an exportable data key to specify that you can only wrap this key with keys marked as CKA_TRUSTED. Once you set CKA_WRAP_WITH_TRUSTED to true, the attribute becomes read-only and you cannot change or remove the attribute.

• CKA_UNWRAP_TEMPLATE: Apply this attribute to the wrapping key (in addition to CKA_TRUSTED) to specify which attribute names and values the service must automatically apply to data keys that the service unwraps. When an application submits a key for unwrapping, the application can also provide its own unwrap template. If you specify an unwrap template and the application provides its own unwrap template, the HSM uses both templates to apply attribute names and values to the key. However, if a value in the CKA_UNWRAP_TEMPLATE for the wrapping key conflicts with an attribute provided by the application during the unwrap request, then the unwrap request fails.

For more information about attributes, refer to the following topics:

• PKCS #11 key attributes

• JCE key attributes

• CloudHSM CLI key attributes

How to use trusted keys to wrap data keys

To use a trusted key to wrap a data key, you must complete three basic steps:

1. For the data key you plan to wrap with a trusted key, set its CKA_WRAP_WITH_TRUSTED attribute to true.

2. For the trusted key you plan to wrap the data key with, set its CKA_TRUSTED attribute to true.

3. Use the trusted key to wrap the data key.

Step 1: Set the data key's CKA_WRAP_WITH_TRUSTED to true

For the data key you want to wrap, choose one of the following options to set the key’s CKA_WRAP_WITH_TRUSTED attribute to true. Doing this restricts the data key so applications can only use trusted keys to wrap it.

Option 1: If generating a new key, set CKA_WRAP_WITH_TRUSTED to true

Generate a key using PKCS #11, JCE, or CloudHSM CLI. See the following examples for more details.

PKCS #11

To generate a key with PKCS #11, you need to set the key's CKA_WRAP_WITH_TRUSTED attribute to true. As shown in the following example, do this by including this attribute in the key’s CK_ATTRIBUTE template and then setting the attribute to true:

CK_BYTE_PTR label = "test_key";
CK_ATTRIBUTE template[] = {
        {CKA_WRAP_WITH_TRUSTED, &true_val,         sizeof(CK_BBOOL)},
        {CKA_LABEL,             label,             strlen(label)},
        ...
};

For more information, see our public samples demonstrating key generation with PKCS #11.

JCE

To generate a key with JCE, you need to set the key's WRAP_WITH_TRUSTED attribute to true. As shown in the following example, do this by including this attribute in the key’s KeyAttributesMap and then setting the attribute to true:

final String label = "test_key";
final KeyAttributesMap keySpec = new KeyAttributesMap();
keySpec.put(KeyAttribute.WRAP_WITH_TRUSTED, true);
keySpec.put(KeyAttribute.LABEL, label);
...

For more information, see our public samples demonstrating key generation with JCE.

CloudHSM CLI

To generate a key with CloudHSM CLI, you need to set the key's wrap-with-trusted attribute to true. Do this by including wrap-with-trusted=true in the appropriate argument for the key generation command:

• For symmetric keys, add wrap-with-trusted to the attributes argument.

• For public keys, add wrap-with-trusted to the public-attributes argument.

• For private keys, add wrap-with-trusted to the private-attributes argument.

For more information on key pair generation, see key generate-asymmetric-pair .

For more information on symmetric key generation, see key generate-symmetric .

Option 2: If using an existing key, use CloudHSM CLI to set its CKA_WRAP_WITH_TRUSTED to true

To set an existing key's CKA_WRAP_WITH_TRUSTED attribute to true, follow these steps:

1. Use the login command to log in as a crypto user (CU).

2. Use the key set-attribute command to set the key's wrap-with-trusted attribute to true.

   aws-cloudhsm > key set-attribute --filter attr.label=test_key --name wrap-with-trusted --value true
   {
     "error_code": 0,
     "data": {
       "message": "Attribute set successfully"
     }
   }

Step 2: Set the trusted key's CKA_TRUSTED to true

To make a key a trusted key, its CKA_TRUSTED attribute must be set to true. You can either use CloudHSM CLI or the CloudHSM Management Utility (CMU) to do this.

• If using CloudHSM CLI to set a key's CKA_TRUSTED attribute, see How to mark a key as trusted with CloudHSM CLI.

• If using the CMU to set a key's CKA_TRUSTED attribute, see How to mark a key as trusted with the CMU.

Step 3. Use the trusted key to wrap the data key

To wrap the data key referenced in Step 1 with the trusted key you set in Step 2, refer to the following links for code samples. Each demonstrates how to wrap keys.

• AWS CloudHSM PKCS #11 examples

• AWS CloudHSM JCE examples

How to unwrap a data key with a trusted key

To unwrap a data key, you need a trusted key that has CKA_UNWRAP set to true. To be such a key, it must also meet the following criteria:

• The key’s CKA_TRUSTED attribute must be set to true.

• The key must use CKA_UNWRAP_TEMPLATE and related attributes to specify what actions data keys can perform once they are unwrapped. If, for example, you want an unwrapped key to be non-exportable, you set CKA_EXPORTABLE = FALSE as part of the CKA_UNWRAP_TEMPLATE.

Note

CKA_UNWRAP_TEMPLATE is only available with PKCS #11.

When an application submits a key to be unwrapped, the application can also provide its own unwrap template. If you specify an unwrap template and the application provides its own unwrap template, the HSM uses both templates to apply attribute names and values to the key. However, if during the unwrap request a value in the trusted key’s CKA_UNWRAP_TEMPLATE conflicts with an attribute provided by the application, the unwrap request fails.

To see an example on unwrapping a data key with a trusted key, refer to this PKCS #11 example.