Prerequisites and Terminology for Cache-Only Keys

Prerequisites

• The Cache-Only Key Service is available for tenant secrets only. It isn’t compatible with root keys, such as those used with Search Index Encryption.
• Prepare your Salesforce org. Make sure that your org has at least one active Data in Salesforce key, either Salesforce-generated or one that you supply. You can create a tenant secret by clicking Generate Tenant Secret on the Key Management page in Setup.
• Generate and host key material. The cache-only key exchange protocol and format requires that keys are wrapped in an opinionated JSON Web Encryption (JWE). This format uses RSAES-OAEP for key encryption and AES GCM for content encryption.
• Use a secure, trusted service to generate, store, and back up your key material.
• Use and maintain a reliable high-availability key service. To mitigate any potential impact to business continuity, choose a high-availability key service with an acceptable service level agreement (SLA), predefined maintenance procedures, and processes.
• When the connection between Salesforce and your key service is broken, the Cache-Only Key Service can encrypt and decrypt data as long as your key material is in the cache. However, keys don’t stay in the cache for long.
  

  Note On average, the cache is flushed about every 72 hours. Some internal operations flush the cache every 24 hours.
• If your key material isn’t in the cache and the connection to your key service is broken, users can’t encrypt or decrypt records. Make sure that you use a key service that Salesforce can connect to at any time, especially during busy times, such as the end of the year or quarter.
• Maintain a secure callout endpoint. The cache-only key exchange protocol requires that keys are wrapped in an opinionated JSON format. Host your wrapped key inside the key response at a location Salesforce can request.
• The Cache-Only Key Service uses named credentials to establish a secure, authenticated connection to allowed IP addresses and domains. You can configure your named credentials to use popular authentication formats, such as Mutual TLS and OAuth. You can change these authentication protocols at any time.
  

  Note A named credential for cache-only keys must specify a named principal. Creating a cache-only keys named credential requires the basic Named Credentials process with the added step of adding the autoproc user to a permission set. See Use a Named Principal-Based Credential for a Cache-Only Key for full details.
• Actively monitor your key service logs for errors. While Salesforce is here to help you with the Shield Platform Encryption service, you’re responsible for maintaining the high-availability key service that you use to host your key material. You can use the RemoteKeyCalloutEvent object to review or track cache-only key events.
  

  Warning Because you’re in control of your keys, you’re responsible for securing and backing up your key material. Salesforce can’t retrieve lost key material stored outside of our encrypted key cache.
• Know how to format and assemble your key material. Format key material hosted outside of Salesforce in a way that’s compatible with the Cache-Only Key Service. Make sure that you can generate these components in the required formats.

  Cache-Only Key Components

  Component	Format
  Data encryption key (DEK)	AES 256-bit
  Content encryption key (CEK)	AES 256-bit
  BYOK-compatible certificate	A 4096-bit RSA certificate whose private key is encrypted with a derived, org-specific tenant secret key. Important Salesforce is complying with an industry-wide reduction of the time to expiration for CA certificates. Please read the information in Certificates in Salesforce and plan accordingly.
  JSON Web Encryption content and header	See a sample in Github.
  Algorithm for encrypting the CEK	RSA-OAEP
  Algorithm for encrypting the DEK	A256GCM
  Unique key identifier	Allows numbers, uppercase and lowercase letters, periods, hyphens, and underscores
  Initialization vector	Encoded in base64url
  JSON web token ID (JTI)	A 128-bit hex encoded, randomly generated identifier

Read more about assembling your key material in Create and Assemble Your Key Material. See Cache-Only Key Wrapper in GitHub for examples and a sample utility.

Terminology

Here are some terms that are specific to the Cache-Only Key Service.

Content Encryption Key

For each key request, your key service endpoint generates a unique content encryption key. The content encryption key wraps the data encryption key, which is then encrypted by the key encrypting key. After that it’s placed in the JWE header of the key response.

JSON Web Encryption

The JSON-based structure that the Shield Platform Encryption service uses to encrypt content. JSON Web Encryption, or JWE, uses RSAES-OAEP for key encryption and AES GCM for content encryption.

JSON Web Token ID

A unique identifier for the JSON web token, which enables identity and security information to be shared across security domains.

Key Identifier

The Key ID (KID) is the unique identifier for your key. The KID is used as the suffix in the named credential and for validation of the KID in the response. In Setup, enter this identifier in the Unique Key Identifier field.