Managing Salesforce Cache-Only Key Endpoints

CipherTrust Cloud Key Manager (CCKM) can act as a key service for Salesforce Shield Platform Encryption's Cache-Only Key Service. Salesforce fetches keys from CCKM endpoints on demand to immediately encrypt and decrypt data. The key material is securely transmitted through an authenticated channel. Salesforce then retains the key in the encrypted key cache until the cache is flushed.

You can provide a cache only key sourced from local CipherTrust Manager or Data Security Manager (DSM). Salesforce requires that the key algorithm is AES 256.

CCKM / CipherTrust Manager Prerequisites

• The CipherTrust Manager network location must be publicly accessible, with a Fully Qualified Domain Name (FQDN).

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

• You must have a configured Salesforce Connection and associated Salesforce organization.

Salesforce Prerequisite

Enable "Allow Cache-only Keys" in Platform Encryption Advanced Settings. Replay Detection is optional.

Prepare the Cache-Only Key Integration

1. Configure a Salesforce Connection and associated Salesforce organization if you have not already.

2. Create the endpoint. This endpoint is tied to a Salesforce organization, as identified by the organization ID generated and applied by CCKM. You must choose a username and password, which serve as the Named Credential for Salesforce communication to the endpoint, and a friendly name for the endpoint. As well, you must provide the base hostname for CipherTrust Manager.

   ksctl cckm salesforce endpoints create --sfdc_organization_resource_id <CCKM-organization-id>  --url_hostname <base-hostname-for-CipherTrust-Manager> --name <friendly-name> --epusername <username-for-Salesforce-communication> --eppassword <password-for-Salesforce-communication>
   

   This functionality is also available in the CipherTrust Manager web console under Cloud Key Manager > Salesforce Organizations. Click a particular Organization, and expand Endpoints. Click Add Cache-Only Key Endpoint.

   When the endpoint is created, a unique ID is generated, and the endpoint is available for Salesforce at a URL of https://<ciphertrust-hostname>/api/v1/cckm/sfdc/endpoints/<unique-id>/keys/

3. Associate at least one certificate with the Salesforce organization in CCKM.

   • To create a new certificate.

     ksctl cckm salesforce certificates add --name <certificate-name> --sfdc_organization_resource_id <CCKM-organization-ID>
     

     This functionality is also available in the CipherTrust Manager web console under Cloud Key Manager > Salesforce Organizations. Click a particular Organization, and expand Certificates. Click Add Certificate and provide a Name.

   • To use a certificate already present in Salesforce, synchronize the certificates from the Salesforce organization.

     ksctl cckm salesforce certificates synchronization-jobs start --sfdc_organization_resource_ids <CCKM-organization-id> --synchronize_all false
     

     This functionality is also available in the CipherTrust Manager web console under Cloud Key Manager > Salesforce Organizations. Click a particular Organization, and expand Certificates. Click Refresh All.

4. Add the Named Credential in Salesforce console:

   1. Specify the endpoint URL.

   2. For Authentication, specify Identity Type as Named Principal and Authentication Protocol as Password Authentication.

   3. Add the username and password you associated with the endpoint in CCKM.

5. Return to CCKM to upload a cache-only key associated with the Named Credential to Salesforce. This cache-only key becomes a tenant secret on Salesforce, with meta data retained.

6. To use the CLI to upload an existing key from local CipherTrust Manager or Data Security Manager (DSM).

   1. Fetch the named credential from Salesforce. You require the organization ID generated and applied by CCKM.

      ksctl cckm salesforce endpoints get-named-credentials --sfdc_organization_resource_id <organization-id>
      

      The 18-digit value returned in the id field is the relevant value. For example, 0XA3h000000L0D5GAK is the named credential ID in the following response.

      {
          "totalSize": 1,
          "done": true,
          "records": [
              {
                  "attributes": {
                      "type": "NamedCredential",
                      "url": "/services/data/v52.0/sobjects/NamedCredential/0XA6h000000L0D7GAK"
              },
          "Endpoint": "https://test.com/kmaas/byok/00D7X000000EM3TEA8/",
          "id": "0XA3h000000L0D5GAK",
          "IsDeleted": false,
          "MasterLabel": "test-namedcredential-1",
          "DeveloperName": "test-namedcredential-1"
              }
          ],
          "organizationId": "a916ba75-242b-4f29-b886-52bf51d70e16"
      }
      

   2. Upload the key. You must provide the following values:

      • Organization ID. This is the organization ID generated and applied by CCKM.

      • Type: Type for tenant secret. One of Data, EventBus, SearchIndex, DeterministicData and Analytics. This depends on the Salesforce encryption purpose for the cache-only key.

      • Source for the key: One of local (from CipherTrust Manager) or dsm (from Data Security Manager).

      • The key ID

      • The certificate ID

      • The named credential ID from step A.

        ksctl cckm salesforce keys upload-cache-only-key --sfdc_organization_resource_id <organization-id> --name <key-name> --type <tenant-secret-type> --source-key-tier <source-of-cache-only-key> --source-key-identifier <key-id> --certificate-id <certificate-associated-with-organization> --sfdc-namedcredential-id <named-credential-id>
        

7. Alternatively, you can use the CipherTrust Manager web console to create a new key or upload an existing key from CipherTrust Manager or DSM. Follow the steps to create a tenant secret for CipherTrust Manager or DSM, making sure to select the option to Make this a cache-only key, and provide Certificate and Named Credential.

   The option presented in the CipherTrust Manager GUI to create a Salesforce (Native) key cannot create cache-only keys.

   At this point, you can manage the cache-only key using CCKM's Salesforce Tenant Secret menus and commands.

View a Salesforce Cache-Only Key Endpoint

You can view a Salesforce cache-only key endpoint through the CipherTrust Manager GUI, CLI, or REST API. An endpoint's URL is needed for Salesforce to make requests to the endpoint.

• In the GUI, Salesforce cache-only key endpoints are grouped under their organizations. Navigate to Cloud Key Manager > Salesforce Organizations. Click a particular Organization, and expand Endpoints.

• In the CLI, Salesforce cache-only key endpoint details can be retrieved using a variety of identifiers.

  To view a single endpoint:

  ksctl cckm salesforce endpoints get --id <endpoint-id>
  

  To view all endpoints:

  ksctl cckm salesforce endpoints list
  

  To return multiple endpoints filtered on name, organization name, organization ID, or organization resource ID.

  ksctl cckm salesforce endpoints list [--name <endpoint-id> --organization-name <org-name> --sfdc_organization_id <organization-ID> --sfdc_organization_resource_id <organization-resource-id> ]
  

• In the REST API, use GET /v1/cckm/sfdc/endpoints to list details for all endpoints, and GET /v1/cckm/sfdc/endpoints/{id} to list details for a specific endpoint.

Edit a Salesforce Cache-Only Key Endpoint

You can edit a Salesforce cache-only key endpoint through the CipherTrust Manager GUI, CLI, or REST API. You can change the base hostname, and the username and password that correspond to the Named Credential in Salesforce. In the GUI, you can also update the friendly name corresponding to the password.

• In the GUI, Salesforce cache-only key endpoints are grouped under their organizations.

  1. Navigate to Cloud Key Manager > Salesforce Organizations.

  2. Click a particular Organization, and expand Endpoints.

  3. Click the overflow icon () corresponding to the desired endpoint, and click Edit.

• In the CLI, Salesforce cache-only key endpoints can be edited using the endpoint ID.

  ksctl cckm salesforce endpoints update --id <endpoint-id> [ --url_hostname <base-hostname> --epusername <named-credential-username> --eppassword <named-credential-password>]
  

• In the REST API, use PATCH /v1/cckm/sfdc/endpoints/{id} to edit the endpoint.

Delete a Salesforce Cache-Only Key Endpoint

You can delete a Salesforce cache-only key endpoint through the CipherTrust Manager GUI, CLI, or REST API. This makes the endpoint inaccessible to Salesforce, and the cache-only key becomes unusable on Salesforce. Make sure that Salesforce applications are no longer using a cache-only key before deleting a Salesforce cache-only key endpoint.

• In the GUI, Salesforce cache-only key endpoints are grouped under their organizations.

  1. Navigate to Cloud Key Manager > Salesforce Organizations.

  2. Click a particular Organization, and expand Endpoints.

  3. Click the overflow icon () corresponding to the desired endpoint, and click Delete.

• In the CLI, Salesforce cache-only key endpoints can be deleted using the endpoint ID.

  ksctl cckm salesforce endpoints delete --id <endpoint-id>
  

• In the REST API, use DELETE /v1/cckm/sfdc/endpoints/{id} to delete the endpoint.