Managing External Key Store Resources

Permissions to Manage External Custom Key Stores

By default, users in the CCKM Admins group can manage external custom key stores. This group includes the root admin account on CipherTrust Data Security Platform Service.

CCKM administrators can grant users assigned to the CCKM users group permission to manage external custom key stores. CCKM manage these permissions through the Access Control List associated with the AWS KMS account.

Linked and Unlinked States

External custom key stores are created in either a Linked or Unlinked state.

When you create a linked key store on CCKM, a corresponding external key store is automatically created on AWS KMS.

After you create an unlinked key store on CCKM, you must either link it to automatically create a corresponding key store on AWS KMS, or you must manually create the key store on AWS KMS.

If you manually create an external key store on AWS KMS, you can later detect and link it to a CCKM local external custom key store by refreshing external custom key stores, or refreshing AWS keys.

While an external custom key store is unlinked, some operations to later update an unlinked external custom key store require manual configuration on AWS. These update operations include:

• Creating Keys

• Rotating Credentials

Prepare an External Custom Key Store

Before you create an external custom key store, decide whether it will be linked or unlinked.

To prepare an external custom key store and provide access to AWS KMS, you follow the following stages in order:

1. Establish an AWS Connection.

2. Create an External Custom Key Store on CCKM.

3. Set up the corresponding AWS KMS external key store to communicate with the new CCKM external custom key store. Steps depend on whether the external custom key store is linked or unlinked.

   • Linked key stores: Connect the new external key store.

   • Unlinked key stores: Create the Corresponding Key Store on AWS KMS.

4. Create Keys for the External Custom Key Store.

Establishing an AWS Connection

If you are using CipherTrust Data Security Platform Service as a key source, be sure to establish a connection between AWS and CipherTrust Data Security Platform Service for HYOK integrations.

1. Establish an AWS connection.

2. Test the connection by finding the new AWS connection in the Connections Table, clicking the ellipsis button in the row, and selecting Test Connection.

   A Ready status indicates that the connection is working correctly.

3. Add an AWS account, as described in Managing AWS Accounts.

   Caution

   When you select regions, make sure they are compatible for external key stores. Compatible regions are described in AWS Key Management Service Deployment Guide.

   Tip

   CCKM Admins can allow CCKM users to manage external custom key stores through the Access Control List associated with the AWS account.

Creating an External Custom Key Store on CCKM

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that will own the key store. The account details page is displayed.

4. Under External Custom Key Stores, click the + Add External Key Store button. You might have to expand the External Custom Key Stores section to view the button.

5. Under Config and Add Key Store, provide the following settings:

   • Key Store Name. A friendly name for the Key Store.

   • Region. Compatible regions are listed in AWS Key Management Service Deployment Guide.

   • Enable success audit events. Use this toggle to enable or disable audit recording of successful operations within an external key store. The toggle is turned off by default.

     Note

     This toggle displays only if the key store is of type "local".

     Note

     Enabling the Enable success audit events toggle significantly impacts the performance of the key store. Enable this feature only for the purpose of troubleshooting or presenting a demo.

   • Enable Mutual TLS. Use this toggle to enable or disable TLS client-side certificate verification where the CipherTrust Data Security Platform Service authenticates the AWS KMS client. The toggle is turned off by default.

   • Source. Either CipherTrust Data Security Platform Service or Luna HSM.

     Caution

     The source you select at this time permanently affects the Hold Your Own Key (HYOK) and health check keys you can add to the external custom key store later. If you select Luna HSM, only Luna HSM keys can be used for health check, and as source keys to HYOK keys. If you select CipherTrust Data Security Platform Service, only CipherTrust Data Security Platform Service keys can be used for health check, and as source keys to HYOK keys. You cannot mix Luna HSM and CipherTrust Data Security Platform Service source keys or health check keys within the same external custom key store.

   • Key Store Container. If using Luna HSM, select the desired partition that will store the source key(s) for the key store.

   • Source. CipherTrust Data Security Platform Service.

   • Link State. Select Unlinked to create a key in the AWS External Key Store that is in an unlinked state. This means that the corresponding key store is not automatically created in AWS KMS, and you must create it. Select Linked to create an AWS External Key Store that is linked to the CCKM external custom key store. If you select Linked, and there is at least one credential rotation schedule already added within Schedules, then you have the option to assign any of the available credential rotation schedules to this key store. Proceed to Step 6 and then Step 7 to assign a credential rotation schedule to this key store after entering all of the settings in this step. Otherwise, skip to Step 8 after entering all of the settings in this step. See Linked and Unlinked States for more information on the effects of these choices. See Adding Credential Rotation Schedule (AWS XKS only) for more information about adding a credential rotation schedule for an AWS External Key Store.

   • XKS Location: Public.

   • Health Check Key. From the drop-down list, select the Key ID of the symmetric AES-256 key to use for performing the health checks on the given key store. AWS initiates this health check on a given key store to checks whether the store is up and running and can perform cryptographic operations. When CCKM receives this health check request from AWS, it performs the health check using the Key ID.

     Note

     The Health Check Key must be created before creating a key store.

     The health check key must have the following attributes:

     * `Key Not Exportable`
     
     * `Key Not Deletable`
     
     * Usage Masks - `Encrypt`, `Decrypt`, `Wrap`, `Unwrap`
     

   • Max Credentials. Enter the maximum number of valid credentials allowed at any given time. These credentials are used to authenticate KMS accessing the external custom key store. The valid values are from 2 to 20 (inclusive). Once a key store reaches the maximum number of credentials, the oldest credential is deleted. For more information about the use of the AWS credentials to access external key stores, refer to AWS Key Management Service Deployment Guide.

6. Click Next.

7. (Optional) Under Add Credential Rotation Schedule and from the drop-down list, select the credential rotation schedule to assign to this key store.

8. Click Add Key Store to continue.

   For linked key stores, CCKM tests that the AWS KMS account can reach CCKM with the provided connection and network parameters. If this connection test fails, you cannot create the new key store.

   A summary of the settings is displayed on the Retrieve Credentials page.

   Note

   If you added a credential rotation schedule for the new key store, the job config ID associated with the schedule displays under CREDENTIALS.

9. Click Download to download the credentials file required by AWS KMS.

   Caution

   This credentials file includes a secret access key string which AWS KMS requires, and you cannot access again. You must download the file, or copy the secret access key string before closing the Add External Key Store wizard, or you will need to rotate credentials to generate new credentials for AWS.

10. Click Close.

    The new external custom key store is displayed under External Custom Key Stores.

11. Set up the corresponding AWS KMS external key store to communicate with the new CCKM external custom key store. Steps depend on whether the external custom key store is linked or unlinked.

    • Linked key stores: connect the new external key store.

    • Unlinked key stores create the Corresponding Key Store on AWS KMS.

Creating the Corresponding External Key Store on AWS KMS for Unlinked Key Stores

If your new external customer key store is unlinked, this means that you must either link the external custom key store to create the corresponding external key store on AWS, or manually create the key store on AWS KMS through its console, API, or CLI.

Link an Unlinked External Custom Key Store

If you created an unlinked external custom key store, you can link it after creation. Linking an external custom key store automatically creates a corresponding external key store in AWS KMS.

To link an unlinked external custom key store:

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Under External Custom Key Stores, find the desired external custom key store name.

5. From the External Key Stores display, click the ellipsis icon associated with the desired external custom key store.

6. Select Link.

   The Link Key Store dialog displays.

7. Review the auto-populated networking details.

8. Click Link to confirm.

   An external key store is created on AWS KMS.

9. Proceed to connect the newly linked key store.

Manually Create Key Store on AWS KMS

The following CipherTrust Data Security Platform Service and CCKM values are required for creating the external key store on AWS KMS:

• The credentials file downloaded during External Custom Key Store Creation on CCKM or when rotating credentials. This file contains Proxy URI path prefix, Access key ID, and Secret access key values, which you can directly upload to AWS console.

If you do not wish to provide the credentials configuration file, you can manually input the following values into AWS Console:

• The Secret access key.

  This value is only available on first creating the external custom key store creation on CCKM, or when you rotate credentials for an external custom key store. There are options during those operations to copy the secret access key string.

• The XKS Proxy URI Path. This value is available through the External Custom Key Stores details:

  1. Open the Cloud Key Manager application.

  2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

  3. Click the name of the account that owns the external custom key stores.

  4. Under External Custom Key Stores, find the desired external custom key store name.

  5. For the XKS Proxy URI Path for the external custom key store, click the copy button to copy the path.

     The full path is copied. The AWS console already includes the /kms/xks/v1 suffix, so you must delete that part of the path when pasting.

• The Access key ID

  1. From the External Key Stores display, click the ellipsis icon associated with the desired external custom key store.

  2. Select View/Edit Details.

  3. Click the copy button next to the desired Access Key ID to copy this value.

After creating the external key store on KMS, you must connect it on KMS to begin sending cryptographic requests to CCKM.

Connect or Disconnect an External Custom Key Store

You can connect or disconnect AWS KMS external key stores. Linked external key stores are created in the Disconnected state, and must be connected either through CCKM or AWS console to begin sending requests to the CCKM external custom key store.

As a convenience, you can connect or disconnect linked external custom key stores on CCKM:

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Under External Custom Key Stores, find the desired external custom key store name.

5. From the External Key Stores display, click the ellipsis icon associated with the desired external custom key store.

6. Select Connect to connect or Disconnect to disconnect.

Connecting or disconnecting an external custom key store through CCKM results in the corresponding external key store on AWS changing state to connected or disconnected. The transient states of connecting and disconnecting display during the transition. Consult AWS Key Management Service Deployment Guide for details on the allowed operations associated with these states.

Creating Keys for the External Custom Key Store

After configuring external custom key stores in both CCKM and AWS, you can create the keys necessary to perform cryptographic operations in response to AWS KMS. This is described in Creating Hold Your Own Key (HYOK) Keys.

Block or Unblock an External Custom Key Store

Blocking and unblocking an external custom key store is a way to temporarily suspend and restore AWS KMS's access to the key store and its keys.

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Under External Custom Key Stores, find the desired external custom key store name.

5. From the External Key Stores display, click the ellipsis icon associated with the desired external custom key store.

6. Click Block or Unblock, depending on whether the key store is in a blocked or unblocked state.

7. You are asked to confirm the action. Click Block or Unblock again.

   The status in the Blocked column updates on the table.

Rotate Credentials

Periodically rotating credentials for the external custom key store is a security best practice. CCKM retains and recognizes the number of credentials set as the Max Credentials for the key store, which is between 2 and 20 credentials (default 20 credentials). Once a key store reaches the maximum number of credentials, the oldest credential is deleted. At this time, AWS only retains one set of credentials for each external key store.

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Under External Custom Key Stores, find and click the desired external custom key store name.

   The details page of the external custom key store is displayed.

5. Check that the key store is unblocked. For linked key stores, also check that the state is either connected or disconnected. If the state is in one of the transient states of connecting or disconnecting, wait until the transition is completed before proceeding to the next step.

6. Click Add Credential to add a new credential.

7. Click Download to download the file containing the new credentials, including the Access key ID and Secret access key.

   Caution

   This credentials file includes a secret access key string which you cannot access again. You must download the file, or copy the secret access key string before closing the Add Credential dialog, or you cannot add the credentials to AWS console.

   A new credential is displayed.

8. If you have a linked key store, connect the key store.

9. If you have an unlinked key store, edit the corresponding external key store on AWS console to upload the new credentials as described in AWS Key Management Service Deployment Guide.

10. If desired, you can delete existing credentials with the Delete Credential button. CCKM will no longer accept requests using these older credentials.

Assign Credential Rotation Schedule

You have the ability to assign a credential rotation schedule for the credentials of a given external custom key store in CCKM. The store must be a local and linked key store. With a linked key store, the auto rotated (new) credentials are updated in AWS KMS.

To assign a credential rotation schedule to a store, you must first create one or more rotation schedules for the key store's credentials in the Add New Schedule wizard within Schedules of the Cloud Key Manager application. Thereafter, these schedules are made available within a list under Schedules of the details page for the given custom key store.

1. Open the Cloud Key Manager application credentials to be updated in AWS KMS.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Under External Custom Key Stores, find and click the desired external custom key store name.

   The details page of the external custom key store is displayed.

5. Under Schedules, click Credential Rotation Schedule drop-down list and select a rotation schedule to assign to the key store.

6. Click Update to apply the schedule to the key store.

The selected rotation schedule is displayed showing when the next credentials rotation is to take place.

Unassign Credential Rotation Schedule

In CCKM, you also have the ability to unassign a credential rotation schedule for a given external custom key store.

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Under External Custom Key Stores, find and click the desired external custom key store name.

   The details page of the external custom key store is displayed.

5. Under Schedules, select the X icon (Unassign button) to unassign the selected rotation schedule for the key store.

Delete an External Custom Key Store

You must delete all HYOK keys in an external custom key store before you can delete the external custom key store.

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Under External Custom Key Stores, find the desired external custom key store name.

5. From the External Key Stores display, click the ellipsis icon associated with the desired external custom key store.

6. Click Delete Store.

7. You are asked to confirm the action. Enable the I wish to delete this Key Store checkbox and click Delete.

Update General Information for an External Custom Key Store

From the details page of an external custom key store, you can update general information for the key store.

You can update the following attributes of all external custom key store:

• Key Store Name

You can update the following attributes for local external custom key stores only:

• Health Check Key

• Max Credentials

• Enable success audit events (by enabling or disabling this toggle depending on the current setting)

• Enable Mutual TLS (by enabling or disabling this toggle depending on the current setting)

You cannot edit health check key or max credentials for a remote type external custom key stores, which can appear after refreshing external custom key stores for an AWS account.

The steps to update this information depends on whether the external custom key store is linked or unlinked.

To update the key store

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Under External Custom Key Stores, find and click the desired external custom key store name.

   The details page of the external custom key store is displayed.

5. Check that the state is unblocked. For linked key stores, also check that the state is disconnected.

6. In the General Info section, enter a new Key Store Name, if desired.

7. Select a new Health Check Key, if desired.

   The health check key must be a symmetric AES-256 key.

8. Select a new number of Max Credentials, if desired. Valid values are between 2-20.

9. Change the setting of the Enable success audit events toggle to either enable or disable this feature, if desired. This toggle displays only if the key store is of type "local".

10. Change the setting of the Enable Mutual TLS toggle to either enable or disable this feature, if desired.

11. Click Update to apply the new settings.

12. If you have a linked key store, connect the key store.

Refresh All External Custom Key Stores and Keys for an AWS Account

This operation detects and imports all external key stores and external keys present on the KMS account.

This can include external key stores that don't have an external custom key store on the local CCKM. These could be associated with an external custom key store on another CCKM that is not clustered to the local CCKM, or to another vendor's external key manager. These key stores are display with the type Remote.

Refreshing all external custom key stores can set unlinked external custom key stores to a linked state. This happens when CCKM detects a corresponding KMS external key store for an local unlinked external custom key store. This operation can also set unlinked HYOK keys to a linked state.

1. Open the Cloud Key Manager application.

2. In the left pane, click KMS Containers > AWS KMS Accounts. The AWS KMS Accounts page is displayed.

3. Click the name of the account that owns the key store. The account details page is displayed.

4. Next to the External Custom Key Store table, click Refresh All.

   The This may take a while... message is displayed.

5. Click Refresh All to continue.

   A message Refresh started... is displayed on the screen. To cancel the refresh, click Cancel Refresh.