Master Wrapping Key
A Master Wrapping Key is the cryptographic key in Salesforce Shield Platform Encryption that wraps (encrypts) other key material so it can be stored at rest without exposing the plaintext. "Wrappin…
Definition
A Master Wrapping Key is the cryptographic key in Salesforce Shield Platform Encryption that wraps (encrypts) other key material so it can be stored at rest without exposing the plaintext. "Wrapping" is encryption applied to keys rather than to records. In Shield, data encryption keys are never written to disk, and org-specific key material is always kept wrapped. The wrapping key is what makes that protection possible inside the tiered key architecture.
The Master Wrapping Key lives inside a hardware security module (HSM) and never appears in plaintext outside that boundary. It sits above tenant secrets and data encryption keys in the chain of trust. When Shield needs to store a tenant secret or a customer-supplied data encryption key, it wraps that material first. When the platform needs the key for an encrypt or decrypt operation, the HSM unwraps it in memory. This wrapping layer is one reason a storage breach alone does not reveal usable keys.
Where wrapping fits in the Shield key hierarchy
Wrapping is encryption for keys, not for records
Shield separates two jobs that both use cryptography. Data encryption keys protect your records, files, and fields. Wrapping keys protect those data encryption keys. The distinction matters because the threat models differ. A data encryption key has to be available, in derived form, whenever a query touches encrypted data. A wrapping key only has to be available to the HSM that unwraps protected material. Key wrapping uses algorithms built for key material, with integrity checks that detect tampering of the wrapped blob. The output is a wrapped key that is useless to anyone without the wrapping key. Salesforce states the principle plainly: data encryption keys are never stored on disk, and your org-specific key material is always wrapped. The Master Wrapping Key is the top of that wrapping arrangement. It is the reason an attacker who somehow reads the storage holding tenant secrets gets ciphertext, not keys. Without HSM access to the wrapping key, the wrapped material cannot be turned back into something that decrypts your data.
The tiered key structure it belongs to
Shield does not protect key material with a single key. It uses a tiered structure that combines wrapped keys, signing, and key derivation. Salesforce describes the critical components of the architecture as the KDF secrets, the KDF salt, the wrapping keys, and the data encryption keys, all secured together in that tiered design. Two patterns sit under this umbrella. For Field-Level Encryption and Database Encryption, Shield derives a data encryption key on demand from a unique tenant secret you control plus a primary secret (the KDF seed, formerly called the master secret) that Salesforce maintains. For External Key Management, search indexes, and BYOK for Data 360, Shield instead uses a root key that wraps the data encryption keys that directly encrypt your data. In both patterns, wrapping keys guard the material that is not derived on the fly. The Master Wrapping Key is the HSM-held key that anchors this wrapping, so stored secrets and stored DEKs stay protected at a layer above the platform default encryption at rest.
How BYOK upload uses wrapping
Bring Your Own Key shows the wrapping key working in the open. With BYOK you generate key material outside Salesforce using your own crypto libraries, KMS, or HSM. You do not send the raw secret. First you generate a BYOK-compatible certificate, which is a PKCS#8 encrypted, Base64 encoded 4096-bit RSA key pair. Then you wrap your key material against that certificate before upload. The exact method depends on the feature. For Field-Level Encryption, Files and Attachments, and Event Bus data, you encrypt the key material with the certificate public key using OAEP padding on a 4096-bit RSA key. For search indexes, Database Encryption, and Data 360, a two-stage wrap applies: a 256-bit AES wrapping key is generated and then encrypted with the 4096-bit RSA public key from the downloaded certificate. Salesforce only ever receives wrapped material. Before storage in the database, customer-supplied DEKs are wrapped again, either with a tenant wrapping key or with the external root key that created them. The plaintext key never crosses the HSM boundary unwrapped.
Cache-Only Key Service and external roots
Cache-Only Key Service extends the wrapping idea to keys that Salesforce never stores at all. Your key material stays in your own key management service. Shield fetches it only when an operation needs it, holds it in an encrypted cache, and never persists it. The transit and caching of that material still rely on wrapping so the key is protected in motion and in memory. The root-key model behaves similarly for External Key Management and BYOK for Data 360. There, an external root key wraps the data encryption keys rather than Shield deriving them from two secrets. The wrapping key concept is the common thread. Whether the source is a Salesforce-managed primary secret, an uploaded BYOK secret, or a cache-only fetch from your KMS, the keys that touch your data are wrapped before they rest anywhere. This is why Shield can offer several key management styles without changing the storage guarantee. The wrapped form is what hits disk, and only an HSM with the wrapping key can reverse it.
Rotation and the chain of trust
Key rotation in Shield happens at more than one layer, and wrapping shapes how it works. The primary secret (KDF seed) is generated once per release inside an HSM during a High Assurance Virtual Ceremony, and Salesforce rotates it each release. Tenant secrets rotate on your schedule, since you control when they are generated, activated, revoked, or destroyed. Above those, wrapping keys rotate on a Salesforce-managed cadence. Rotating a wrapping key means unwrapping the protected material with the old key and re-wrapping it with the new one, an operation internal to the platform that you do not observe directly. The benefit of this layering is containment. Rotating one layer does not force a full re-encryption of your data, because data encryption keys are derived or wrapped rather than stored in the clear. The Master Wrapping Key is part of the chain of trust that links your customer-facing tenant secret down to the HSM-protected infrastructure that ultimately guards it.
What admins can and cannot touch
You will not find a Master Wrapping Key field in Setup. It is platform infrastructure, not a configurable object. As an admin or architect, your direct controls are the tenant secret and the key management policy: generating tenant secrets, rotating them, choosing Salesforce-managed keys versus BYOK versus Cache-Only Key Service, and assigning the right permissions. The wrapping key works underneath all of those choices. That separation is intentional. It keeps the most sensitive key, the one that unwraps everything else, inside the HSM and out of reach of any application path or administrator session. Your trust in the wrapping layer rests on Salesforce attestations and compliance documentation rather than on direct inspection. For audits, that is usually the point. Auditors who require key material to be protected at multiple layers can map the tiered structure: tenant secrets and DEKs wrapped under HSM-controlled keys, sitting on top of the platform default encryption at rest. The Master Wrapping Key is the piece that makes that multi-layer claim true.
A worked example: one field decrypt
Walk through a single read of an encrypted field to see the wrapping key in context. A user opens a record with an encrypted Social Security number. The application server checks its cache for that org data encryption key. If the key is present, the field decrypts and the user sees the value. If the key is not cached, the server pulls the encrypted tenant secret from the database and asks the regional key management server to derive the data encryption key. Deriving that key requires the primary secret and the tenant secret to be available to the HSM, which means the wrapped tenant secret has to be unwrapped first. The Master Wrapping Key performs that unwrap inside the HSM. The derived data encryption key then lives only in the protected cache, never on disk. When the cache entry expires, the cycle repeats. At no point does a wrapping key, a primary secret, or a plaintext tenant secret leave the HSM boundary in the clear. That is the guarantee the wrapping key exists to provide.
Trust & references
Cross-checked against the following references.
- How Shield Platform Encryption WorksSalesforce
- Generate and Wrap BYOK Key MaterialSalesforce
Straight from the source - Salesforce's reference material on Master Wrapping Key.
Hands-on resources to go deeper on Master Wrapping Key.
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 does the Master Wrapping Key do in Salesforce Shield?
Q2. Why does Shield wrap tenant secrets with the Master Wrapping Key instead of storing them directly?
Q3. Where is the Master Wrapping Key stored in Shield's infrastructure?
Discussion
Loading discussion…