Master Secret
A Master Secret is the top-level, per-release cryptographic input that Salesforce Shield Platform Encryption uses to derive the keys that protect customer data at rest.
Definition
A Master Secret is the top-level, per-release cryptographic input that Salesforce Shield Platform Encryption uses to derive the keys that protect customer data at rest. It is one of several secrets generated inside the Salesforce Master HSM (a FIPS 140-2 hardware security module) and it never appears in plaintext outside that hardware boundary. The Master Secret does not encrypt your records by itself. Instead, the key derivation function combines it with your organization's tenant secret to produce the data encryption key (DEK) that actually encrypts and decrypts data.
In the Shield key model, the Master Secret is the layer that Salesforce controls and customers cannot view, export, or edit. Customers manage the tenant secrets that sit above it through the Setup UI and API. Because the Master Secret feeds every derived key in a release, it is the highest-value cryptographic asset in the system, which is why it lives in air-gapped hardware and is rotated on Salesforce's own release cadence.
How the Master Secret anchors Shield key derivation
Where it sits in the key hierarchy
Shield Platform Encryption stacks its key material in layers, and the Master Secret is the deepest layer customers can reason about. At the top sit the data encryption keys (DEKs) that directly encrypt fields, files, and attachments. Each DEK is derived from two inputs: the tenant secret you control for your organization, and the Master Secret that Salesforce maintains for the whole release. Below those secrets sits the hardware: the Master HSM that generates the secret and the embedded HSMs inside the key derivation servers that do the derivation work. The important point is that no single layer is enough on its own. A DEK is useless without both the tenant secret and the Master Secret feeding the derivation. The Master Secret alone never touches a record. The tenant secret alone cannot recreate a DEK either. That split is deliberate. It lets you keep control of the tenant secret lifecycle (generate, rotate, destroy) while Salesforce keeps the Master Secret locked inside hardware you never see. For an architect documenting a Shield deployment, this is the layer where customer control ends and platform-operated protection begins.
How the Master Secret is generated
The Master Secret is created by the Master HSM at the start of each Salesforce release. The Master HSM is a SafeNet Luna G5 device, FIPS 140-2 compliant, that stays air-gapped from the production network at all times and is stored in a bank safety deposit box. Access is restricted to designated Salesforce security officers. At release time the device is plugged into an offline laptop and used to generate the per-release secrets and keys on the HSM itself. Once generated, each secret is hashed with SHA-256, then the Master Secret and the other secrets are encrypted under the per-release master wrapping key. The encrypted material is checked into source control and exported to the Salesforce internal file system. From there, the embedded HSMs in the key derivation servers can unwrap it when they boot. This ceremony, sometimes run as a High Assurance Virtual Ceremony, means the plaintext Master Secret only ever exists inside the Master HSM during that offline session. It is never typed, copied to a screen, or written to disk in the clear.
The secrets generated alongside it
The Master Secret does not arrive alone. During per-release generation the Master HSM produces a small family of secrets and keys that work together. Alongside the Master Secret it creates a master salt, a master wrapping key, a tenant wrapping key, and a transit wrapping key pair. Each plays a specific role in the derivation pipeline. The master salt is fed into the key derivation function with the Master Secret. The master wrapping key encrypts the other secrets so they can be stored and shipped safely. The tenant wrapping key encrypts tenant secrets that the embedded HSMs generate or that customers upload. The transit wrapping key pair protects the short-lived transit key that wraps a finished data encryption key as it travels back to the encryption service. Understanding this set helps explain why the Master Secret is described as per-release rather than per-customer. A new release brings a fresh batch of these secrets, and the key derivation servers load the correct batch based on metadata attached to the data they are asked to decrypt.
How a data encryption key is derived from it
When a customer reads or writes encrypted data and the needed DEK is not already cached, the encryption service asks a key derivation server to produce it. The server decrypts the relevant tenant secret with the tenant wrapping key in its cache, then runs the key derivation function. Shield uses PBKDF2WithHmacSHA256 for this step. The PBKDF2 inputs are specific and worth knowing for an audit. The pseudorandom function is HmacSHA256. The password input is the Master Secret XOR the tenant secret, so neither value alone can produce the key. The salt is the master salt, the iteration count is 15,000, and the derived key length is 256 bits. The resulting DEK is encrypted with a transit key before it leaves the derivation server, so it is never transmitted in the clear. The encryption service then decrypts the DEK, holds it in memory, and uses it to encrypt or decrypt the record. Derived keys are not persisted to disk. They live in a memory cache governed by a least recently used policy and disappear when the cache is flushed.
Why hardware protection and never-on-disk matter
Salesforce built this model to keep encryption keys available to the encryption service while keeping them away from privileged employees such as database administrators, and away from anyone who breaches the database. The Master Secret is central to that goal. If an attacker obtained the Master Secret for a release, they could combine it with stolen tenant secrets and derive every affected DEK. Holding it in a FIPS 140-2 HSM means it never appears in plaintext where a software-level attack could reach it. Two design choices reinforce this. First, the Master HSM is air-gapped and offline except during the release ceremony, so there is no network path to attack it. Second, derived keys are never persisted on disk. They are produced on demand and cached only in memory, so a stolen disk or a database dump yields ciphertext and wrapped secrets, not usable keys. This is why Shield deployments can satisfy regulators who require evidence that keys are generated and stored securely, not just that data is encrypted. Encryption without strong key protection leaves data vulnerable, and the Master Secret is the keystone of that protection.
BYOK and Cache-Only: who holds the Master Secret
For the default Salesforce-managed model, the Master Secret is pure platform infrastructure. Salesforce generates it, protects it, and rotates it each release, and customers never interact with it directly. Bring Your Own Key, available since Winter '17, does not change that. With BYOK you still rely on the same Master Secret for the release. What changes is the tenant secret: you generate a 256-bit tenant secret outside Salesforce, wrap it with a BYOK certificate's public key, attach a SHA-256 hash, and upload it. The key derivation server validates the hash, then pairs your tenant secret with the current Master Secret to derive the DEK. So even when customers want maximum control, the derivation still depends on the Salesforce Master Secret. The lever customers actually pull is the tenant secret, plus the ability to revoke Salesforce's access to it. Cache-Only Key Service pushes control further, letting the tenant secret live only in a customer key service that Salesforce fetches and caches briefly. Across all three models the Master Secret stays inside Salesforce hardware. The distinction matters when an architect maps which key material sits inside the customer boundary and which stays with the platform.
Master Secret versus tenant secret in practice
The two terms get conflated in casual conversation, but the difference is the whole point of the design. The tenant secret is the customer-facing key layer. You see it in Setup under Key Management, where it shows a version, a status of Active, Archived, or Destroyed, and a key type. You generate it, rotate it, archive it, and can destroy it, and the Manage Encryption Keys permission gates those actions. Only the most recent tenant secret is active and used to derive new DEKs; archived versions stay around to decrypt older data. The Master Secret has none of that surface area. There is no row for it in Setup, no version you click, no button to rotate it. It is generated by Salesforce per release and protected in hardware you never touch. When you destroy a tenant secret, you make it impossible to re-derive the DEK for data encrypted under it, which is the strongest customer-side revocation lever you have. You can do that precisely because the Master Secret alone cannot rebuild the key. In short: tenant secret is the dial you turn, and the Master Secret is the fixed foundation it turns against.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Master Secret.
- Shield Platform Encryption TerminologySalesforce
- Bring Your Own Key (BYOK) OverviewSalesforce
Hands-on resources to go deeper on Master Secret.
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 in Salesforce Shield's key hierarchy?
Q2. How does the Master Secret enable cryptographic tenant isolation across orgs on shared infrastructure?
Q3. Who manages the Master Secret for Salesforce-Managed Keys?
Discussion
Loading discussion…