Managing External Key Store Resources

Deployment Prerequisites

• The CipherTrust Manager must be reachable through a Fully Qualified Domain Name (FQDN).

  • In VPC deployments, you provide this value to set the Private DNS Name in the VPC endpoint service. If you are operating an unlinked key store and manually creating an external key store on AWS KMS, you also provide this value as the Proxy URI endpoint.

  • You provide this as the Proxy URI endpoint for public routable deployments without a load balancer.

• The web interface must have a TLS certificate signed by an external Certificate Authority (CA) trusted by AWS. AWS trusts certificates issued by well-known public CAs such as Verisign.

• The Common Name (CN) in the web interface certificate must be set to a specific value.

  • A good default value for the CN is the CipherTrust Manager FQDN.

  • For VPC deployments with more than one AWS KMS external key store, the CN should include the wildcard * asterisk character.

  • If you are using a load balancer with a publicly routable deployment, and the load balancer is set to do SSL passthrough, include the wildcard * asterisk character in the CN.

• We recommend setting up all networking elements before creating the external custom key store on CCKM. This is especially important when you create an external custom key store in the linked state. Successful validation of the connection between AWS KMS and the new external custom key store must take place before a linked key store can be created. For example, for CipherTrust Manager hosted on premise with VPC connection, configure VPC endpoints as described in AWS documentation, before creating the external custom key store on CCKM.

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

  Depending on the location of the key store, the health check is initiated.

  • If the key store is on Luna HSM, the Health Check Key must have the following attributes:

    • CKA_EXTRACTABLE = FALSE

    • CKA_SENSITIVE = TRUE

    • CKA_ENCRYPT = TRUE

    • CKA_DECRYPT = TRUE

    • CKA_WRAP = TRUE

    • CKA_UNWRAP = TRUE

  • If the key store is on CipherTrust Manager, the Health Check Key must have the following attributes:

    • Key Not Exportable

    • Key Not Deletable

    • Usage Masks - Encrypt, Decrypt, Wrap, Unwrap

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 Manager.

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. If using CipherTrust Manager as a key source, establish an AWS Connection. If using Luna HSM as a key source, establish both AWS and Luna HSM Connections.

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.

The configuration and new objects you create on CCKM, connections to AWS and Luna HSM or CipherTrust Manager, AWS account information, the external custom key store, and AWS keys are replicated across a cluster. For multiple CipherTrust Managers in cluster, you need to only perform this configuration on one node.

Establishing an AWS Connection

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

1. Establish an AWS connection.

   Note

   If your CipherTrust Manager is deployed inside a VPC, and the AWS account is in a region other than us-east-1, there is an AWS STS Regional Endpoints setting required.

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.

Establishing AWS and Luna HSM Connections

If you are using Luna HSM as a key source, be sure to establish AWS and Luna HSM connections for HYOK integrations.

The Connection Manager page gives more details about managing the AWS and Luna HSM connections.

1. Establish an AWS connection.

   Note

   If your CipherTrust Manager is deployed inside a VPC, and the AWS account is in a region other than us-east-1, there is an AWS STS Regional Endpoints setting required.

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 a HSM Server connection and a Luna Network HSM Connection to establish access to a Luna Network HSM partition.

4. Add another HSM server connection and Luna Network HSM connection to add a partition from a second Luna Network HSM.

5. Test the HSM connections 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.

6. 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 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.

   • Source. Either CipherTrust Manager 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 Manager, only CipherTrust Manager keys can be used for health check, and as source keys to HYOK keys. You cannot mix Luna HSM and CipherTrust Manager 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.

   • 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. See Linked and Unlinked States for more information on the effects of these choices.

   • XKS Location. Select Amazon VPC, if you will use an Amazon VPC to connect to the key store. Then enter the VPC Endpoint Service Name and the XKS Proxy URI Endpoint. Select Public, if you will use the Internet to connect to the key store. Enter the XKS Proxy URI Endpoint thereafter.

     Note

     VPC Endpoint Service Name can be obtained from AWS configuration.

     XKS Proxy URI Endpoint refers to the hostname of the server entity which AWS KMS first connects to for cryptographic requests.

     • For Amazon VPC deployments, this is the Private DNS Name set for the VPC endpoint service.

     • For Public deployments, this is usually the load balancer host name.

     • If AWS is connecting to CipherTrust Manager directly, this is the CipherTrust Manager fully qualified domain name.

   • 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.

     Depending on the location of the key store, the health check is initiated.

     • If the key store is on Luna HSM, the Health Check Key must have the following attributes:

       • CKA_EXTRACTABLE = FALSE

       • CKA_SENSITIVE = TRUE

       • CKA_ENCRYPT = TRUE

       • CKA_DECRYPT = TRUE

       • CKA_WRAP = TRUE

       • CKA_UNWRAP = TRUE

     • If the key store is on CipherTrust Manager, 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 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.

7. If desired, you can copy the Health Check URI Path value (using the copy button) at this time to check the health of a given CipherTrust Manager node. For each of your CipherTrust Manager nodes, create a routable endpoint URL by adding "https://(ip address or hostname of node) as a prefix to this URI path. You can then use this end point to validate whether a custom key store is ready to handle requests. Load balancers can also be configured to call this endpoint for a health check. To obtain the status of a CipherTrust Manager node that is behind a load balancer, configure the node's health check URL in the load balancer. You can also retrieve the Health Check URI Path value later from the details page of the external custom key store.

   Note

   The Health Check URI Path value is only available for a custom key store that is a local key store (meaning the store is locally hosted on the given CCKM instance).

8. 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.

9. Click Close

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

10. 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 storescreate 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.

If you want to set up CipherTrust Manager hosted on premise with VPC connection, configure VPC endpoints as described in AWS Key Management Service Deployment Guide if you have not already. VPC endpoints are associated with an external custom key store.

To link an unlinked external custom key store:

1. Open the Cloud Key Manager application.

2. In the left pane, click 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.

   These include the XKS Location selected during key store creation.

8. Edit networking details if needed.

   For Public XKS Location, you can edit the XKS URI Proxy Endpoint.

   For Amazon VPC XKS Location, you can edit VPC Endpoint Service Name and the XKS Proxy URI Endpoint

9. Click Link to confirm.

   An external key store is created on AWS KMS.

10. Proceed to connect the newly linked key store.

Manually Create Key Store on AWS KMS

If you want to set up CipherTrust Manager hosted on premise with VPC connection, configure VPC endpoints as described in AWS Key Management Service Deployment Guide if you have not already. VPC endpoints are associated with an external custom key store.

The following CipherTrust Manager and CCKM values are required for creating the external key store on AWS KMS:

• The CipherTrust Manager FQDN, in most deployments.

  For VPC deployments, the CipherTrust Manager FQDN is provided for the Proxy URI Endpoint when you create the External Key Store on AWS KMS.

  If you have a non-VPC deployment, and are not operating behind a load balancer, this is the value needed for Proxy URI Endpoint in AWS console.

• The load balancer hostname, if applicable for non-VPC deployments. This is used as the Proxy URI Endpoint.

• 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.

  Note

  There is an additional field in the AWS console to create the external key store, VPC endpoint service name, for VPC deployments. This is the VPC endpoint service which you have associated with the CipherTrust Manager and custom external key store.

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

• XKS Location

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)

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 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. Change the XKS Location settings if desired to update networking details.

   • Select Amazon VPC, if you will use an Amazon VPC to connect to the key store. Then enter the VPC Endpoint Service Name and the XKS Proxy URI Endpoint.

   Caution

   To avoid interruption in service, configure VPC endpoints in AWS before updating Amazon VPC details on an external custom key store in CCKM.

   • Select Public, if you will use the Internet to connect to the key store. Enter the XKS Proxy URI Endpoint.

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

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

   The health check key must come from the key store's existing Key Source Container, CipherTrust Manager or Luna HSM connection.

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

10. 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".

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 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.