Master Secret
The Master Secret in Salesforce Shield is the top-level cryptographic input from which all other keys in the customer's key hierarchy derive.
Definition
The Master Secret in Salesforce Shield is the top-level cryptographic input from which all other keys in the customer's key hierarchy derive. The Master Secret is held in the Salesforce Master HSM (or in the customer HSM for BYOK and Cache-Only scenarios) and never appears in plaintext outside the HSM boundary. Operations needing key material derive it through HSM-mediated key derivation; the Master Secret itself does not encrypt customer data directly.
The concept matters for compliance documentation and architecture review. Auditors examining a Shield deployment look for evidence that the Master Secret is properly protected: held in FIPS-certified hardware, accessed only through controlled operations, rotated on a defined schedule, destroyed when no longer needed. The Master Secret is the security anchor; compromise of the Master Secret would compromise every key derived from it, which is why the HSM protection is non-negotiable. Customers cannot view, export, or directly manipulate the Master Secret; their interactions happen through tenant secret operations layered above it.
How the Master Secret anchors Shield
Position in the key hierarchy
The hierarchy stacks: data encryption keys (per record or per field) > tenant secrets (per customer org) > Master Secret (per Salesforce instance or per customer for BYOK). The Master Secret is the deepest layer customers can reason about. Below it: the HSM hardware and physical security controls Salesforce operates.
Where the Master Secret lives
For Salesforce-Managed Keys, the Master Secret lives in Salesforce's Master HSM. For BYOK, the customer-generated Master Secret lives in both the customer HSM (master copy) and the Salesforce Master HSM (working copy, wrapped). For Cache-Only Key Service, the Master Secret lives only in the customer KMS; Salesforce holds no persistent copy.
Why HSM protection is essential
The Master Secret is the highest-value cryptographic asset in the system. Compromise of the Master Secret means an attacker can derive every tenant secret and decrypt every record. HSM protection ensures the Master Secret never appears in plaintext where software-level attacks could reach it. The HSM exposes operations (sign, derive, unwrap) but not the secret itself.
Rotation of the Master Secret
Master Secret rotation is rare and high-stakes. For Salesforce-Managed Keys, Salesforce handles rotation on its own schedule. For BYOK, the customer rotates by generating a new Master Secret in their HSM and uploading. For Cache-Only, the customer rotates in their KMS. Rotation invalidates derived tenant secrets unless re-derived under the new Master Secret.
Destruction implications
Destroying the Master Secret renders every tenant secret derived from it unusable, which renders every encrypted record unrecoverable. This is the strongest customer-side data revocation lever. Build approval workflows around destruction; the operation is rare and irreversible, and accidental destruction is catastrophic.
Compliance documentation
Salesforce compliance attestations (FedRAMP, SOC 2) describe the Master Secret protection. Customers cite these documents in their own audits. The Master Secret itself is not directly visible to customers; the protection model is verified through attestation rather than direct inspection.
Master Secret versus tenant secret
Customers interact with tenant secrets directly through Setup. Master Secrets are platform-internal infrastructure (for Salesforce-Managed) or customer infrastructure (for BYOK and Cache-Only). The two terms are sometimes conflated in casual usage; the distinction matters for compliance architecture: tenant secrets are the customer-facing key layer, Master Secrets are the underlying protection layer.
Decide on Master Secret protection model
Customers do not directly configure the Master Secret; the relevant decisions are about which key model to use. The steps below cover those decisions and the documentation expectations.
- Understand the key hierarchy
Read Salesforce Shield architecture documentation. Confirm understanding before evaluating customer-controlled alternatives.
- Choose key model
Salesforce-Managed (Master Secret platform-internal), BYOK (Master Secret customer-controlled), or Cache-Only (Master Secret in customer KMS only).
- For Salesforce-Managed, rely on attestations
Reference FedRAMP, SOC 2, and other Salesforce attestations for Master Secret protection evidence.
- For BYOK, generate Master Secret in customer HSM
Use a FIPS-certified HSM to generate the Master Secret. Upload to Salesforce wrapped under Salesforce's wrapping key.
- For Cache-Only, configure KMS endpoint
Stand up the customer KMS that will host the Master Secret. Configure connectivity from Salesforce.
- Document Master Secret protection
For compliance audits, document the chain: HSM hardware, key generation process, rotation schedule, destruction procedures.
- Plan rotation and destruction procedures
Master Secret rotation is rare and high-stakes. Document the procedure; require multi-party approval for destruction.
Held in Salesforce Master HSM. Customer reliance on attestations.
Customer generates in their HSM; Salesforce holds wrapped copy.
Customer holds only; Salesforce fetches on demand.
Rare operation; rotates derived tenant secrets.
Irreversible; renders all derived secrets unusable.
- The Master Secret cannot be viewed or exported by customers. Compliance verification depends on attestations and HSM-mediated operations.
- Destruction is catastrophic. Build multi-party approval workflows; accidental destruction renders all derived data unrecoverable.
- Master Secret rotation propagates to derived tenant secrets. Plan the cascade carefully; rotation cycles affect downstream data accessibility.
- BYOK Master Secret wrapped under Salesforce wrapping key. Destruction of Salesforce wrapping key is also catastrophic; understand the dependency.
- Cache-Only Master Secret depends on customer KMS availability. KMS downtime halts all decryption; plan KMS high availability.
Trust & references
Straight from the source - Salesforce's reference material on Master Secret.
- How Shield Platform Encryption WorksSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the Master Secret?
Q2. How does the Master Secret enable tenant isolation?
Q3. Who manages the Master Secret?
Discussion
Loading discussion…