Shield Kms Byok Setup

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.

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

1. 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.

2. 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?

3. 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.

4. 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 references/gotchas.md.

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 references/gotchas.md.

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 references/examples.md, 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

Recommended Workflow

1. 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.
2. 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.
3. Execute in production at the start of a maintenance window, so a 24-hour cooldown after a failure does not overlap a business day.
4. 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.
5. 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.
6. Rehearse destruction quarterly in a sandbox, capturing the actual failure evidence rather than a confirmation that it worked.
7. 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 references/gotchas.md.

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

Output Artifacts

Related Skills

• 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