mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-02 21:34:30 +08:00
35 lines
2.4 KiB
Markdown
35 lines
2.4 KiB
Markdown
# 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.
|