Salesforce Security Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Salesforce Security Guide
Salesforce Security Basics
Authenticate Users
Give Users Access to Data
Share Objects and Fields
Strengthen Your Data’s Security with Shield Platform Encryption
What You Can Encrypt
Platform Encryption Q&A
How Encryption Works
Set Up Your Encryption Policy
Filter Encrypted Data with Deterministic Encryption
Key Management and Rotation
Work with Salesforce Key Material
Get Statistics About Your Encryption Coverage
Synchronize Your Data Encryption
Work with External Key Material
Bring Your Own Key (BYOK)
External Key Management
Cache-Only Key Service
How Cache-Only Keys Works
Prerequisites and Terminology for Cache-Only Keys
Optimize Security Using Named Credentials and Cache-Only Keys
Create and Assemble Your Key Material
Add Replay Detection for Cache-Only Keys
Check Your Cache-Only Key Connection
Destroy a Cache-Only Key
Reactivate a Cache-Only Key
Considerations for Cache-Only Keys
Troubleshoot Cache-Only Keys
Configure Your Cache-Only Key Callout Connection
Shield Platform Encryption Customizations
Encryption Trade-Offs
Audit and Monitor Your Organization’s Security
Real-Time Event Monitoring
Security Guidelines for Apex and Visualforce Development
API End-of-Life Policy
PDF

Troubleshoot Cache-Only Keys

One or more of these frequently asked questions can help you troubleshoot any problems that arise with Shield Platform Encryption’s Cache-Only Key Service.
Available in both Salesforce Classic (not available in all orgs) and Lightning Experience.
Available as an add-on subscription in: Enterprise, Performance, and Unlimited Editions. Requires purchasing Salesforce Shield or Shield Platform Encryption. Available in Developer Edition at no charge.

The callout to my key service isn’t going through. What can I do?

Callouts can fail for various reasons. Review the error message that displays and follow these tips for resolving the problem. All callouts are recorded in the RemoteKeyCalloutEvent object.

Table 1. Cache-Only Key Service Errors and Status Codes
RemoteKeyCalloutEvent Status Code Error Tips for Fixing the Problem
AUTHENTICATION_FAILURE_RESPONSE Authentication with the remote key service failed with the following error: {error}. Check the authentication settings for your chosen named credential.
DESTROY_HTTP_CODE The remote key service returned an HTTP error: {000}. A successful HTTP response returns a 200 code. To find out what went wrong, review the HTTP response code.
EMPTY_RESPONSE The remote key service callout returned an empty response. Contact your remote key service for help. Contact your remote key service.
ERROR_HTTP_CODE The remote key service returned an unsupported HTTP response code: {000}. A successful HTTP response returns a 200 code. To find out what went wrong, review the HTTP response code.
ILLEGAL_PARAMETERS_IN_JWE_HEADER Your JWE header must use {0}, but no others. Found: {1}. Remove the unsupported parameters from your JWE header.
INCORRECT_ALGORITHM_IN_JWE_HEADER The remote key service returned a JWE header that specified an unsupported algorithm (alg): {algorithm}. The algorithm for encrypting the content encryption key in your JWE header must be in RSA-OAEP format.
INCORRECT_DATA_ENCRYPTION_KEY_SIZE Data encryption keys encoded in a JWE must be 32 bytes. Yours is {value} bytes. Make sure that your data encryption key is 32 bytes.
INCORRECT_ENCRYPTION_ALGORITHM_IN_JWE_HEADER The remote key service returned a JWE header that specified an unsupported encryption algorithm (enc): {your enc}. The algorithm for encrypting the data encryption key in your JWE header must be in A256GCM format.
INCORRECT_KEYID_IN_JSON The remote key service returned JSON with an incorrect key ID. Expected: {valid keyID}. Actual: {invalid keyID}. Check that you set up your named credential properly and are using the correct BYOK-compatible certificate.
INCORRECT_KEYID_IN_JWE_HEADER The remote key service returned a JWE header with an incorrect key ID. Expected: {valid keyID}. Actual: {invalid keyID}. Check that you set up your named credential properly and are using the correct BYOK-compatible certificate.
MALFORMED_CONTENT_ENCRYPTION_KEY The remote key service returned a content encryption key in the JWE that couldn’t be decrypted with the certificate’s private key. Either the JWE is corrupted, or the content encryption key is encrypted with a different key. Check that you set up your named credential properly and are using the correct BYOK-compatible certificate.
MALFORMED_DATA_ENCRYPTION_KEY The content encryption key couldn’t decrypt the data encryption key that was returned in the remote key service’s JWE. The data encryption key is either malformed, or encrypted with a different content encryption key. Check that you set up your named credential properly and are using the correct BYOK-compatible certificate. Named credentials must call out to an HTTPS endpoint.
MALFORMED_JSON_RESPONSE We can’t parse the JSON returned by your remote key service. Contact your remote key service for help. Contact your remote key service.
MALFORMED_JWE_RESPONSE The remote key service returned a malformed JWE token that can’t be decoded. Contact your remote key service for help. Contact your remote key service.
MISSING_PARAMETERS_IN_JWE_HEADER Your JWE header is missing one or more parameters. Required: {0}. Found:{1}. Make sure that your JWE header includes all required values. For example, if Replay Detection is enabled, the JWE header must include the nonce value extracted from the cache-only key callout.
POTENTIAL_REPLAY_ATTACK_DETECTED The remote key service returned a JWE header with an incorrect nonce value. Expected: {0}. Actual: {1} Make sure that your JWE header includes the RequestID included in the callout.
ACCESS TO NC DENIED We couldn't access the credential. You don't havethe required permissions, or the external credential you specified doesn't exist. Make sure that you specified the correct named credential. Also, this error occurs if you haven’t added the autoproc user to the external credential principal permission set. See Use a Named Principal-Based Credential for a Cache-Only Key.
RESPONSE_TIMEOUT The remote key service callout took too long and timed out. Try again. If your key service is unavailable after multiple callout attempts, contact your remote key service.
UNKNOWN_ERROR The remote key service callout failed and returned an error: {000}. Contact your remote key service.
UNKNOWN_ERROR The remote key service callout failed and returned an error: java.security.cert.CertificateExpiredException: NotAfter: {date and time of expiration} The certificate for your cache-only key has expired. Update your cache-only key material to use an active BYOK-compatible certificate.
UNKNOWN_EXCEPTION: Urgent Your Cache-Only key is unavailable. Refer to the “UNKNOWN_EXCEPTION: Urgent” information later on this page.
The following key service errors can prevent the callout from completing. If you see errors related to these problems, contact your key service administrator for help.
  • The JWE is corrupt or malformed.
  • The data encryption key is malformed.
  • The key service returned a malformed JWE token.
  • The key service returned an empty response.
For uniform resource use, Salesforce limits the amount of time for each key service callout to 3 seconds. If the callout takes more than the allotted time, Salesforce fails the callout with a timeout error. Check that your key service is available. Make sure that your named credential references the correct endpoint—check the URL, including the IP address.
Can I execute a remote callout in Apex?

Yes. Salesforce manages all authentication for Apex callouts that specify a named credential as the callout endpoint so that your code doesn’t have to. To reference a named credential from a callout definition, use the named credential URL. A named credential URL contains the scheme callout, the name of the named credential, and an optional path. For example: callout:My_Named_Credential/some_path.

See Named Credentials as Callout Endpoints in the Apex Developer Guide.

Can I monitor my callout history?

If you want to review or track cache-only key events, use the RemoteKeyCalloutEvent standard object. Either use the describeSObjects() call to view event information, or an after insert Apex trigger to perform custom actions after each callout. For example, you can write a trigger that stores RemoteKeyCallout events in a custom object. When you store RemoteKeyCallout events in a custom object, you can monitor your callout history. See the RemoteKeyCalloutEvent entry in the Salesforce Object Reference for more information.

The Setup Audit Trail tracks changes in key material state and named credential settings. Callout history isn’t recorded in log files.

I see “?????”, !!!!!, 08/08/1888, or 01/01/1777 instead of my data when I try to access data encrypted with a cache-only key, Why?
The value that you see is a string reserved for masking notifications. The presence of a reserved masked value means one of two things. Either the connection to your key service is broken and we can’t fetch your key, or the data is encrypted with a destroyed key. Check that your key service is available and that your named credential references the correct endpoint. If any key versions are marked as Destroyed as a result of a key service failure, recover the connection and activate the key version by hand. The topic Why Isn’t My Encrypted Data Masked? lists all the reserved masking notification strings.
I see either “????? ?????” or the error "UNKNOWN_EXCEPTION, Urgent: your key service unavailable. You can’t edit, view, or create encrypted records without the encryption key provided by this service. Contact your Salesforce security admin.” whenever I open records that contain previously encrypted data, Why?
This error can result if your Cache-Only key Key Management Server is unavailable. If you’re confident that your cache-only key exists, check that the connections from AWS to Hyperforce are allowed. Your AWS KMS must permit access to the required the Salesforce Hyperforce IP addresses.

We recommend that Hyperforce customers adopt best practices as documented in the topic Preferred Alternatives to IP Allowlisting on Hyperforce.

My certificate is about to expire. What do I do?
An expired certificate doesn’t affect the active state of the secret that it wraps. Your certificate gives assurance to the recipient that the received secret was sent and wrapped by you. If you use an expired certificate, your secret is still protected, but the receiving party is notified that the certificate is expired. Salesforce does not block your secret if it’s wrapped with an expired certificate.
Do I have to make a new named credential every time I rotate a key?
Nope. You can use a named credential with multiple keys. As long as you host your key material at the endpoint specified in an existing named credential, you’re all set. When you rotate your key material, change the key ID in the Unique Key Identifier field. Double-check that your new key is stored at the specified endpoint URL in your named credential.
Can I use legacy named credentials with cache-only keys?
Yes. You can use whichever type is supported by your external key service.
I’m still having problems with my key. Who should I talk to?
If you still have questions, contact your account executive or Salesforce Customer Support. They’ll put you in touch with a support team specific to this feature.