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

- Skill: `aibot88/shield-kms-byok-setup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aibot88/shield-kms-byok-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aibot88/shield-kms-byok-setup/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aibot88 (https://skillmd.com/u/aibot88)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/aibot88/shield-kms-byok-setup

---


# Shield Platform Encryption — BYOK / KMS Setup

Shield BYOK lets you upload your own 256-bit tenant secret; Cache-Only Key Service keeps the key in your own KMS, fetched by Salesforce on demand. Both require Shield Platform Encryption and careful operational processes: rotation, destroy tests, and KMS availability SLOs.

## When to Use

Regulated data (HIPAA, PCI, regulated financial records) where compliance mandates customer-controlled keys. Not for general PII that Classic Encryption or field-level security already protects.

Typical trigger phrases that should route to this skill: `shield byok setup`, `cache only key service`, `rotate tenant secret`, `customer managed keys salesforce`.

## Recommended Workflow

1. Enable Shield Platform Encryption and identify fields/files/chatter that require probabilistic vs. deterministic encryption.
2. Generate a 256-bit key in your KMS; for BYOK, derive and upload; for Cache-Only, configure named credential + callback.
3. Rotate tenant secret quarterly via Setup → Platform Encryption → Key Management.
4. Run a destroy-key test in a sandbox to prove you can revoke access (records become unreadable).
5. Document KMS availability SLO — if your KMS is down, Salesforce cannot decrypt in the Cache-Only flow.

## Key Considerations

- BYOK key material never leaves Salesforce after upload; Cache-Only keys never enter Salesforce's durable storage.
- Deterministic encryption is required for filter equals queries — trades strength for functionality.
- Rotation re-encrypts newly written data only; historical data stays under the previous tenant secret until you run Encryption Key Rotation batch.
- Cache-Only: callback latency adds to every decrypt; measure in load tests.

## Worked Examples (see `references/examples.md`)

- *BYOK tenant secret upload* — Healthcare provider, HIPAA.
- *Cache-Only Key Service with AWS* — Financial services firm refuses to upload key material.

## Common Gotchas (see `references/gotchas.md`)

- **Destroy-key not tested** — On a real incident nobody can prove revocation works.
- **KMS outage = decrypt failure** — User pages go blank; agents cannot read records.
- **Mix of deterministic and probabilistic** — SOQL filter on a field silently fails to return results.

## Top LLM Anti-Patterns (full list in `references/llm-anti-patterns.md`)

- Using default tenant secret indefinitely
- Encrypting a field and then using SOQL LIKE on it
- No runbook for KMS outage

## Official Sources Used

- Apex Developer Guide — Sharing — https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_bulk_sharing_understanding.htm
- Salesforce Security Guide — https://help.salesforce.com/s/articleView?id=sf.security.htm
- Shield Platform Encryption — https://help.salesforce.com/s/articleView?id=sf.security_pe_overview.htm
- Session Security Levels — https://help.salesforce.com/s/articleView?id=sf.security_hap_session.htm
- CSP and Trusted URLs — https://help.salesforce.com/s/articleView?id=sf.security_csp_overview.htm
- API Only User Profile — https://help.salesforce.com/s/articleView?id=sf.users_profiles_api_only.htm
- Privacy Center and DSR — https://help.salesforce.com/s/articleView?id=sf.privacy_center_overview.htm