Home / security / shield-kms-byok-setup

shield-kms-byok-setup

Configure Shield Platform Encryption with customer-supplied (BYOK) or customer-held (Cache-Only Key Service) tenant secrets, rotate them, and recover. NOT for Classic Encryption or field masking — use security/platform-encryption.

v1.0.1
Salesforce Spring '25+
Updated 2026-08-14
Security
Reliability

shield
encryption
byok
kms

Open the skill folder on GitHub

Shield Platform Encryption — BYOK / KMS Setup

Shield Platform Encryption derives a data encryption key from a tenant secret. This skill is about where that tenant secret comes from, what each option obliges you to operate, and how to rotate, destroy, and recover it.

Model	Key material lives	Runtime dependency on your KMS
Salesforce-managed	Derived inside Salesforce	No
BYOK	You generate and wrap it; Salesforce holds the uploaded material	No
Cache-Only Key Service	Your key service; fetched on demand. "Salesforce doesn't retain or persist your cache-only keys in any system of record or backups."	Yes

Field-level encryption itself is fixed regardless of model: "FLE uses the Advanced Encryption Standard (AES) with 256-bit keys by using Cipher Block Chaining (CBC) mode and a random initialization vector (IV)."

The framing that matters: these are not tiers. Each answers a different compliance sentence and carries a different operational obligation. Most orgs that reach for Cache-Only Keys should be on BYOK.

For the encryption policy itself — which fields, deterministic versus probabilistic, what breaks — see security/platform-encryption. This skill assumes that decision is made.

Before Starting

Cite the requirement. Which specific clause drives the choice? "Encrypted at
rest," "customer must originate the key material," and "key material must never persist in the vendor's systems" are three different requirements with three different answers.
If Cache-Only is being considered, get an availability commitment. Your key
service becomes a hard dependency of reading encrypted data, on a refresh schedule Salesforce controls. Who operates it, to what SLO, with what on-call?
Measure one re-encryption. Rotation cadence should be set against the
measured duration of re-encrypting your largest encrypted object, not against a policy template.
Separate the access-control workstream now. The key model does not change who
can read a field. If need-to-know is also a requirement, that is an FLS matrix and it is a different piece of work.

Core Concepts

Rotation applies to subsequent writes

Uploading a customer-supplied tenant secret changes only subsequent encryption — quoted, with what that means for already-encrypted data, in 0.

Existing data stays under the previous secret until re-encryption runs and completes. Verify on Encryption Statistics, not on the key management screen — the latter tells you which secret is active, not which secret your data is under.

Upload frequency is rate-limited

"Customer-supplied key material can be uploaded once every 24 hours in production and Developer Edition orgs, and every 4 hours in sandbox orgs."

A failed production rotation cannot be retried the same day. Rehearse in a sandbox until it succeeds twice consecutively without hand-editing, and script the wrapping.

Cache-Only Keys do not call out per decryption

Cache-Only Key Service re-fetches key material after a flush — every 72 hours routinely, and about every 24 hours under certain operations. Quoted in 0.

Steady-state latency is unaffected. The requirement this creates is availability at an arbitrary instant, not throughput.

The key service contract

Compatible with "256-bit AES keys returned in a JSON response, and then wrapped using JSON Web Encryption (JWE)". With replay detection enabled, Salesforce "inserts an autogenerated, unique marker called a RequestIdentifier into every callout, which includes the key identifier, a nonce generated for that callout instance, and the nonce required from the endpoint" — your service must participate, or every callout fails once detection is on.

Destruction is irreversible

Destroying a tenant secret renders data encrypted under it permanently unreadable. That is the crypto-shredding property BYOK and Cache-Only exist to provide, and it is why the operation is rehearsed only in a sandbox.

The key model is not an access control

Shield is transparent above the storage layer. Under every model, every user with FLS Read sees the same plaintext. Manage Encryption Keys (with Customize Application) governs administering the feature — including irreversible destruction — not reading a value.

Common Patterns

Pattern A — BYOK with quarterly rotation

Generate 256 bits externally, wrap with the Salesforce-provided certificate, upload, activate, then re-encrypt existing data as a separate signed-off step. Full flow in 0, Example 1.

Pattern B — Cache-Only with a designed key service

Multi-region, health-checked, independently monitored, with the replay-detection path implemented and tested at build time and a rehearsed fallback to BYOK. Example 2 covers the runbook this design obliges.

Pattern C — quarterly sandbox destroy rehearsal

Destroy, capture the actual failure evidence (UI error, Apex exception type, integration response, elapsed time), restore, verify the old data stays unreadable. The evidence is the deliverable. Example 3.

Pattern D — the written model decision

Model chosen, requirement cited, models rejected and why, rotation cadence, rehearsal owner, fallback. Without the citation, the next reviewer cannot tell whether Cache-Only was rejected on analysis or on effort. Example 4.

Decision Guidance

The requirement says	Model	You take on
"Encrypted at rest"	Salesforce-managed	Rotation + re-encryption
"Customer must originate the key material"	BYOK	Generation, wrapping, secure storage of your copy, 24-hour production upload window
"Customer must be able to destroy the key unilaterally"	BYOK	As above; destruction is irreversible and needs a second approver
"Key material must never persist in the vendor's systems"	Cache-Only	A key service with an availability SLO ≥ your Salesforce target, replay detection, rehearsed fallback
"Revocation must be unilateral and immediate"	Cache-Only	As above
Need-to-know restriction on the field	None of these — FLS matrix	A separate workstream

Recommended Workflow

Cite the compliance requirement and select the model, recording the models
rejected and why. If no clause requires non-persistence or immediate unilateral revocation, BYOK is the answer.
Rehearse the full key operation in a sandbox — generate, wrap, upload,
activate — until it succeeds twice consecutively from a script. The sandbox window is four hours; production is 24.
Execute in production at the start of a maintenance window, so a 24-hour
cooldown after a failure does not overlap a business day.
Run re-encryption as a distinct, separately signed-off step, per object,
verified on Encryption Statistics, and budget wall-clock time proportional to data volume.
For Cache-Only, design and monitor the key service independently of
Salesforce, implement the RequestIdentifier / nonce path at build time, and rehearse the fallback to BYOK or Salesforce-managed.
Rehearse destruction quarterly in a sandbox, capturing the actual failure
evidence rather than a confirmation that it worked.
Review the model annually against the requirement, since the operational
obligation is ongoing and the clause that justified it may have changed.

Review Checklist

[ ] The compliance clause driving the model choice is cited in writing
[ ] Cache-Only is not chosen without a non-persistence or immediate-revocation clause
[ ] Key service (if Cache-Only) has an SLO, an owner, on-call, and multi-region design
[ ] Replay-detection path implemented and tested before detection is enabled
[ ] Wrapping and upload are scripted, not hand-executed
[ ] Rotation runbook has re-encryption as a separate signed-off step
[ ] Re-encryption verified on Encryption Statistics, per object
[ ] Production rotation scheduled at the start of a window, not the end
[ ] Destroy rehearsal is quarterly, in a sandbox, with captured failure evidence
[ ] Production destruction requires a second approver and an explicit data-abandonment statement
[ ] Manage Encryption Keys scoped to a small named group with an approval trail
[ ] Access control handled as a separate FLS workstream, not claimed by the key model
[ ] Fallback to BYOK or Salesforce-managed documented and rehearsed

Salesforce-Specific Gotchas

Full detail with quotes in 0.

You can upload key material once every 24 hours in production — four in a
sandbox. A failed rotation cannot be retried the same day.
Rotation encrypts new writes only. Re-encryption is separate and explicit.
Cache-Only Keys do not call out per decryption — the dependency is
availability at an arbitrary instant, on Salesforce's flush schedule.
Replay detection requires your key service to participate, or every callout
fails.
Destroying a tenant secret is not reversible, and that is the point.
The key model does not change who can read the field.
Choosing Cache-Only without a contractual requirement buys an availability
dependency for a property nobody asked for.
Encryption is not retroactive, whatever the key model.
Manage Encryption Keys is not the read permission — it is the
destroy permission.

Output Artifacts

Artifact	Description
Key model decision record	Model chosen, requirement cited, models rejected with reasons, and the operational obligations accepted
Rotation runbook	Scripted wrap and upload, activation, re-encryption per object with its own sign-off, and the verification surface for each
Key service design (Cache-Only only)	SLO, topology, monitoring independent of Salesforce, replay-detection implementation, on-call ownership
Destroy rehearsal evidence	Per quarter: the UI error, Apex exception type, integration response, and elapsed time per step
Fallback procedure	The rehearsed path back to BYOK or Salesforce-managed, with the date it was last exercised

security/platform-encryption — which fields to encrypt, deterministic versus
probabilistic, and what encryption breaks. Decide that before this skill applies.
security/salesforce-shield-deployment — sequencing the whole Shield rollout,
of which key management is one workstream
security/certificate-and-key-management — the org's certificate store, which
the BYOK wrapping certificate and any key service client certificate live in