afv-library/skills/platform-encryption-configure/references/key-models.md

Key Management Models

Shield Platform Encryption supports several ways to source and control the key material that protects encrypted data. They differ in where the key material lives and who controls it.

The models

Model	Where key material lives	Who controls it	Metadata / setting
Salesforce-derived (default)	Salesforce, derived from a tenant secret	Salesforce derivation	none — default
BYOK (Bring Your Own Key)	Salesforce, but from customer-supplied material	Customer uploads key material; Salesforce stores it	canOptOutOfDerivationWithBYOK controls per-key derivation opt-out
BYOKMS / EKM (External Key Management)	An external key store the customer runs	Customer; Salesforce calls out to the KMS	canExternalKeyManagement (API 63.0+)
Cache-Only Keys	Outside Salesforce entirely; fetched on demand per callout	Customer hosts a key service; Salesforce caches, never persists	enableCacheOnlyKeys, enableReplayDetection
Data 360 keys	Salesforce, dedicated Data 360 root key	Customer-managed root key	canManageDataCloudKeys (API 63.0+)
Transactional DB	Salesforce	Org policy	canEncryptTransactionalDatabase (API 63.0+)

BYOK vs BYOKMS/EKM — the distinction users get wrong

• BYOK: you generate key material and upload it. Salesforce stores it and uses it like a derived key. The trust boundary still includes Salesforce storing the material.
• BYOKMS / EKM: key material never leaves your external KMS. Salesforce makes a callout to the KMS to wrap/unwrap. This keeps the material entirely under your control.

Cache-Only Keys and replay detection

Cache-Only Keys go further than EKM: Salesforce fetches key material on every use and never persists it — only caches it transiently.

enableReplayDetection protects those callouts against replay attacks using a nonce. The contract is a one-way dependency:

Requires enableCacheOnlyKeys=true before setting enableReplayDetection to true.

Two consequences the agent must respect:

1. Enabling Cache-Only Keys does not auto-enable replay detection. You must set enableReplayDetection=true explicitly.
2. An org can validly run Cache-Only Keys with replay detection off. It is not required.

Setting enableReplayDetection=true without enableCacheOnlyKeys=true is an invalid combination and will be rejected.