Add Replay Detection for Cache-Only Keys

Replay detection protects your cache-only keys if a callout is fraudulently intercepted. When enabled, replay detection inserts an autogenerated, unique marker called a RequestIdentifier into every callout. The RequestIdentifier includes the key identifier, a nonce generated for that callout instance, and the nonce required from the endpoint. The RequestIdentifier serves as a random, one-time identifier for each valid callout request. After you set up your key service to accept and return the RequestIdentifier, any callout with missing or mismatched RequestIdentifiers is aborted.

Required Editions

User Permissions Needed
To create, edit, and delete named credentials:	Customize Application
To allow cache-only keys with BYOK:	Customize Application AND Manage Encryption Keys
To generate, destroy, export, import, upload, and configure tenant secrets and customer-supplied key material:	Manage Encryption Keys

1. Update your key service to extract the nonce generated for the callout instance from the RequestIdentifier. Here’s what the nonce looks like.
   e5ab58fd2ced013f2a46d5c8144dd439
2. Echo this nonce in the JWE protected header, along with the algorithm used to encrypt the content encryption key, the algorithm used to encrypt the data encryption key, and the unique ID of the cache-only key. Here’s an example.

   {"alg":"RSA-OAEP","enc":"A256GCM","kid":"982c375b-f46b-4423-8c2d-4d1a69152a0b","jti":"e5ab58fd2ced013f2a46d5c8144dd439"}

3. From Setup, in the Quick Find box, enter Encryption Settings, and then click Encryption Settings.
4. In the Advanced Encryption Settings section, turn on Enable Replay Detection for Cache-Only Keys.
   You can also enable replay detection programmatically. For more information, see EncryptionKeySettings in the Metadata API Developer Guide.
   From now on, every callout to an external key service includes a unique RequestIdentifier.

Warning If you enable replay detection but don’t return the nonce with your cache-only key material, Salesforce aborts the callout connection and displays a POTENTIAL_REPLAY_ATTACK_DETECTED error.

See Also

• Object Reference for Salesforce and Lightning Platform: RemoteKeyCalloutEvent