Home / architect / salesforce-shield-architecture

salesforce-shield-architecture

Salesforce Shield as an architectural choice — Platform Encryption + Event Monitoring + Field Audit Trail as three SEPARATELY-LICENSED components, none of which ship in any standard edition.

• v1.0.0
• Salesforce Spring '25+
• Updated 2026-05-04
• Security
• Reliability
• Operational Excellence

• shield
• platform-encryption
• event-monitoring
• field-audit-trail
• byok
• cache-only-keys
• compliance-architecture

Open the skill folder on GitHub

Salesforce Shield Architecture

Shield is the wrong size of question to answer with "go to Setup → enable encryption". It's three separately-priced add-on products — Platform Encryption, Event Monitoring, Field Audit Trail — sold per-org, none included in any standard edition. The architectural decision is which components, with what posture, against which fields, and that has to happen before anyone clicks anything in Setup.

This skill is the architectural decision layer. The setup mechanics for each component live in their own skills: security/platform-encryption, security/event-monitoring, security/field-audit-trail. Compliance certification mapping (specifically what HIPAA / FedRAMP-High / PCI require from Shield) lives in a separate skill — Shield is part of the answer to those, not the whole answer.

Before Starting

• Confirm every Shield license you're about to assume. Setup → Company

  Information → Permission Set Licenses. Three distinct lines: Platform Encryption, Event Monitoring, Field Audit Trail. The most common Shield-architecture failure is recommending a feature against an org that doesn't have the license — a 3-month procurement cycle becomes visible in the design review, not afterwards.

• Inventory the fields. For each candidate-encryption field: data

  type (some types can't be encrypted at all), whether filter / sort / group-by is required, whether full-text search is required, and whether external IDs depend on it.

• Decide the key-management posture before picking components. A

  Cache-Only Key Service design has implications for every Shield component (single point of unavailability) — choosing it after picking components forces rework.

• Decide retention up-front. Field Audit Trail retention is set per

  object in metadata XML, with a maximum of 10 years. Plan storage cost and the 18-month-tier vs longer-tier transition.

Core Concepts

Shield's three components, each with its own license

Standard Salesforce ships with classic encryption (a different product — single-key, weaker, fewer field types) and 18-month field history retention in <Object>History (no separate license). Shield upgrades both, plus adds Event Monitoring.

Platform Encryption: probabilistic vs deterministic

The most consequential per-field decision under Shield Platform Encryption. Salesforce supports two schemes:

Sorting is not a capability either scheme buys you. Salesforce states you can't sort records in list views by fields that contain encrypted data, and the same restriction applies to encrypted fields in flows, orchestrations and processes. The mechanism makes this unsurprising: deterministic encryption guarantees only that equal plaintexts produce equal ciphertexts — it says nothing about order. Ciphertext collates in an order unrelated to the plaintext, so a lexicographic sort on ciphertext would return rows in an order that is not the business order even where the platform allowed it. Treat any claim that deterministic encryption "enables sorting" as false regardless of how it is justified.

Deterministic is therefore the only path if SOQL needs to filter by exact match on the encrypted field. It does not unlock ranges, LIKE/wildcard, or ordering. If the design needs to sort or range-scan on a value, the answer is not a different encryption scheme — it is to keep a separate unencrypted sortable surrogate (a bucketed or masked field), or to not encrypt that field. Probabilistic is the right default for everything else. You cannot change scheme on a populated field without re-encrypting every row.

Field types you cannot encrypt

The blocklist matters because authors often promise encryption of fields that physically cannot be encrypted:

• Formula fields — encryption would break the formula evaluation engine.
• Roll-Up Summary fields — same reason; aggregation requires plaintext.
• External ID fields with Unique checked AND backed by a unique index — the unique index requires plaintext for collision detection.
• Auto-Number fields — generated server-side, value is the index.
• A handful of standard fields (Id, IsDeleted, RecordTypeId, etc.) — system fields.

If a field on the encryption candidate list is one of these, the architectural answer is to encrypt the underlying field that the formula / roll-up reads from, not the derived field.

BYOK vs Cache-Only Key Service (CCKM)

The two customer-supplied-key models have very different operational shapes:

CCKM is the right answer for high-compliance shops (regulator-audited key custody). BYOK is the right middle ground for "we want to control rotation but don't want to operate an HSM for Salesforce traffic". Salesforce-managed is fine for orgs whose compliance posture doesn't require customer custody.

Field Audit Trail retention

Not a single dial — set per object in metadata XML:

<HistoryRetentionPolicy>
    <archiveAfterMonths>18</archiveAfterMonths>
    <archiveRetentionYears>10</archiveRetentionYears>
    <description>HIPAA-archived patient records</description>
</HistoryRetentionPolicy>

archiveAfterMonths controls when records move from the standard <Object>History table (queryable in reports) to FieldHistoryArchive (queryable via SOQL only). archiveRetentionYears controls deletion from the archive — capped at 10 years.

Decision Guidance

Recommended Workflow

1. Pre-flight: license confirmation. Permission Set Licenses page. Three lines, three independent purchases. If any is missing, the conversation pauses for procurement.
2. Compliance driver inventory. What forces Shield to be in scope (regulator, contract, internal control)? Map each requirement to the minimum Shield component that addresses it.
3. Field inventory + scheme decision. For Platform Encryption: list every candidate field with its filter / sort / search requirement; pick probabilistic vs deterministic per field. Identify any encryption-blocked field types and reroute to source fields.
4. Key-management posture. Salesforce-managed / BYOK / CCKM. Document the outage tradeoff for CCKM.
5. Audit retention design. For Field Audit Trail: per-object HistoryRetentionPolicy XML, with archiveAfterMonths and archiveRetentionYears decided per object.
6. Event Monitoring scope. Log-files-only vs Log-files + Real-Time Event Monitoring + Transaction Security Policies. Document which event types are subscribed and why.
7. Cost projection. Component licenses + key-management infrastructure (HSM if CCKM) + storage growth from Field Audit Trail archive.

Review Checklist

• [ ] Three Shield licenses confirmed in Setup (or marked "not in scope" with rationale).
• [ ] Per-field encryption scheme matches filter / sort requirements.
• [ ] No field on the encryption list is a Formula / Roll-Up / unique-indexed External ID; if it was, the source field is encrypted instead.
• [ ] Key-management posture named (Salesforce-managed / BYOK / CCKM) with one-sentence rationale.
• [ ] CCKM design documents the HSM outage failure mode.
• [ ] Field Audit Trail retention XML present for every audited object; archiveRetentionYears ≤ 10.
• [ ] Event Monitoring scope explicit (which event types, log-only vs real-time).
• [ ] Total cost projection includes component licenses + HSM (if CCKM) + storage growth.

Salesforce-Specific Gotchas

1. Three Shield components, three separate licenses. None included in any standard edition. Verify each PSL before any Setup work. (See references/gotchas.md § 1.)
2. Probabilistic encryption blocks SOQL WHERE equality filters; deterministic restores exact-match filtering only. Neither scheme restores sorting — you can't sort records in list views by fields containing encrypted data, and ciphertext order does not track plaintext order in any case. Wrong scheme = wrong queries; expecting sort from deterministic = a design that fails at query time. (See references/gotchas.md § 2.)
3. Formula / Roll-Up / unique-indexed External ID cannot be encrypted. Encrypt the source field instead. (See references/gotchas.md § 3.)
4. Cache-Only Key Service outage = encryption operations fail. A customer-HSM outage stops new writes that need encryption. Trade for the strongest custody posture. (See references/gotchas.md § 4.)
5. Field Audit Trail retention requires metadata XML, not Setup UI. HistoryRetentionPolicy is set per object via Tooling API or metadata deploy — not a checkbox. (See references/gotchas.md § 5.)
6. Tenant secret rotation re-encrypts all data. Plan the operation as a maintenance window for orgs with significant encrypted data volume. (See references/gotchas.md § 6.)
7. Real-Time Event Monitoring is Pub/Sub-only as of recent releases. Old code paths against the streaming-API channels are deprecated. (See references/gotchas.md § 7.)

Output Artifacts

Related Skills

• security/platform-encryption — Setup mechanics for the Platform Encryption component (this skill ends where that one starts).
• security/event-monitoring — Setup for Event Monitoring + Real-Time Event Monitoring + Transaction Security Policies.
• security/field-audit-trail — Setup mechanics for the per-object retention policy.
• security/byok-key-rotation — Operational runbook for tenant-secret rotation and CCKM cache invalidation.
• architect/hybrid-integration-architecture — Adjacent decisions when Shield-encrypted data flows to AWS / Heroku / external systems.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• templates/salesforce-shield-architecture-template.md
• scripts/check_salesforce_shield_architecture.py