Master Wrapping Key
The Master Wrapping Key in Salesforce Shield is the cryptographic key used to wrap (encrypt) tenant secrets so they can be stored at rest without revealing the plaintext secret material.
Definition
The Master Wrapping Key in Salesforce Shield is the cryptographic key used to wrap (encrypt) tenant secrets so they can be stored at rest without revealing the plaintext secret material. When Salesforce stores a customer tenant secret, it does so wrapped under the Master Wrapping Key; only the HSM can unwrap it. This wrapping ensures that even if an attacker accesses the storage backing for tenant secrets, the plaintext secrets remain protected by the HSM-controlled wrapping key.
The Master Wrapping Key lives in the Master HSM (or in the customer HSM for BYOK and Cache-Only scenarios). Like the Master Secret it protects, the Master Wrapping Key never appears in plaintext outside the HSM. The key participates in two main operations: wrapping tenant secrets when they are first generated or imported, and unwrapping them when needed for derivation operations. The wrapping key is part of the chain of trust that connects customer-facing tenant secrets to the deeper HSM-protected master infrastructure.
How the Master Wrapping Key protects tenant secrets
Wrapping versus encryption
"Wrapping" is encryption specifically for protecting keys, distinct from encryption for protecting data. Wrapping operations use specialized algorithms (AES Key Wrap) designed for key material, with integrity checking that detects tampering. The output is a wrapped key; only the wrapping key holder can unwrap. The conceptual separation matters: data encryption keys protect records; wrapping keys protect data encryption keys.
Role in BYOK upload
When a BYOK customer uploads their tenant secret, the upload protocol uses the Master Wrapping Key. The customer secret arrives at Salesforce wrapped under the Salesforce wrapping key, so Salesforce can store it without ever seeing the plaintext. The HSM unwraps when key operations are needed. This is the cryptographic mechanism that lets customers trust Salesforce with key material: the plaintext never leaves the HSM boundary.
Role in Cache-Only Key Service
Cache-Only Key Service uses a similar wrapping pattern but with the customer KMS as the source. The customer KMS holds the key; when Salesforce needs it for an operation, the KMS sends a wrapped version that the Salesforce Master HSM unwraps in memory. The Master Wrapping Key is part of the protocol securing the transit.
Storage of wrapped tenant secrets
Wrapped tenant secrets are stored in Salesforce's encrypted-data-at-rest storage. The wrapping adds a layer beyond the platform's standard encryption at rest. Attackers who breach the storage backing get wrapped tenant secrets they cannot unwrap without HSM access, which is the defense-in-depth point of the wrapping key.
Wrapping key rotation
Wrapping keys rotate on a Salesforce-managed schedule. Rotation involves unwrapping every stored tenant secret with the old wrapping key and re-wrapping with the new wrapping key. The operation is internal to Salesforce; customers do not directly observe it. The mechanism is similar to tenant secret rotation but at the layer above.
Customer visibility
Customers do not directly interact with the Master Wrapping Key. It is platform infrastructure for Salesforce-Managed Keys, and part of the upload protocol for BYOK. Compliance documentation describes the wrapping key's role; direct customer access is not provided. The trust model relies on Salesforce attestations rather than direct verification.
Why wrapping matters for compliance
Compliance frameworks often require that key material be protected at multiple layers. The Master Wrapping Key provides that additional layer: tenant secrets are not just stored encrypted at rest by the platform default, they are wrapped under HSM-controlled keys. Auditors look for this layering as evidence of defense-in-depth.
Work with Master Wrapping Key in Shield
Customers do not directly configure the Master Wrapping Key. The steps below cover the related customer-side concerns.
- Understand the role
Read Salesforce Shield documentation on key wrapping. The Master Wrapping Key is the layer protecting tenant secrets at rest.
- For BYOK upload, follow Salesforce protocol
Salesforce documents the BYOK upload format. Wrap the customer secret with the Salesforce wrapping key as specified.
- For Cache-Only, configure KMS
The customer KMS sends wrapped key material to Salesforce. Configure per Salesforce documentation.
- Document the wrapping protection
For compliance audits, reference the Master Wrapping Key role in Salesforce attestations. Customer-side documentation describes the chain.
- Monitor for wrapping-related errors
Key operations occasionally surface errors related to wrapping (corruption, version mismatch). Capture in support tickets if seen.
- Test BYOK rotation if applicable
BYOK rotation re-wraps under new Master Wrapping Key versions. Test in sandbox before production rotation.
- Reference in compliance reviews
Cite the Master Wrapping Key as evidence of multi-layer key protection in customer compliance documentation.
Standard algorithm used for wrapping. Customers do not configure; platform-managed.
Master Wrapping Key in Salesforce Master HSM.
For BYOK, customer HSM holds wrapping key for upload protocol.
Salesforce-managed for platform; customer-managed for BYOK.
Salesforce-provided evidence of wrapping protection.
- The Master Wrapping Key is not customer-configurable. Customers cannot inspect or replace it directly.
- BYOK upload protocol requires correct wrapping format. Mistakes here cause upload failures; follow Salesforce documentation carefully.
- Wrapping-related errors usually indicate a corruption or version mismatch. Open a support ticket rather than attempting local debugging.
- Cache-Only Key Service relies on the wrapping protocol for in-transit key protection. KMS connectivity issues can surface as wrapping errors.
- The wrapping key is part of the chain of trust. Compromise (rare in practice) would affect all customer secrets wrapped under it; Salesforce operates the HSM under strict controls.
Trust & references
Straight from the source - Salesforce's reference material on Master Wrapping Key.
- 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 Wrapping Key?
Q2. Why use a wrapping key?
Q3. Where is the Master Wrapping Key stored?
Discussion
Loading discussion…