Key Tenant Secret Rotation
Key Tenant Secret Rotation is the Salesforce Shield operation of replacing the active tenant secret with a freshly generated one, while keeping the previous secret available to decrypt older data.
Definition
Key Tenant Secret Rotation is the Salesforce Shield operation of replacing the active tenant secret with a freshly generated one, while keeping the previous secret available to decrypt older data. Rotation is the central practice of long-term key management: it limits the blast radius of a compromised key by ensuring that any single key protects only a bounded window of data, and it satisfies compliance requirements that mandate periodic key changes. The operation runs through Setup > Encryption Settings > Key Management > Generate Tenant Secret, with the new secret becoming Active immediately and the previous moving to Archived state.
Rotation is non-disruptive at the encryption operation level: new writes use the new active secret; reads of older data continue to decrypt under the archived secret. However, fully retiring an old secret requires a Mass Encryption job that re-derives data keys for older records under the new secret. Without Mass Encryption, the old secret remains in active use indefinitely for the data encrypted under it, defeating the rotation purpose for that data. The full rotation cycle includes both the generation step and the post-rotation Mass Encryption.
How tenant secret rotation works
Why rotate
Three reasons drive rotation. Compliance: many regulatory frameworks (PCI DSS, HIPAA in some interpretations, internal policies) require periodic key rotation. Defense in depth: limiting how long any single key is in use bounds the impact of a compromise. Cryptographic hygiene: even without specific compromise, long-lived keys accumulate exposure through routine operations; rotation refreshes the security boundary.
Rotation cadence
Annual rotation is the common default for B2B SaaS. Financial services and healthcare often require quarterly. Some regulated industries require monthly or even more frequent. The cadence is a policy decision; the platform supports any cadence the customer chooses. Document the cadence and audit compliance with it; the most common rotation failure is "we forgot to rotate" rather than any technical issue.
Non-disruptive activation
Generating a new tenant secret takes seconds. The new secret becomes Active immediately. New writes encrypt under the new secret; existing data remains encrypted under the previous (now Archived) secret. No downtime; users do not notice the rotation occurred. This is the primary engineering achievement that makes regular rotation feasible at scale.
Mass Encryption: the necessary follow-up
After rotation, run Mass Encryption (Encryption Statistics > Encrypt Unencrypted Data or the equivalent re-encryption job). The job re-derives data keys for older records under the new tenant secret. Without it, old data depends on the archived secret indefinitely. Mass Encryption is asynchronous and can take hours to days depending on data volume; plan it during low-traffic windows.
Archived versus Destroyed
After rotation, the previous secret is Archived. Archived secrets can still decrypt data; they cannot encrypt new data. To fully retire a secret, you must destroy it, which is irreversible. Destruction should only happen after Mass Encryption has re-encrypted all dependent data under newer secrets. Confirm no data depends on the secret before destroying.
Rotation and BYOK
For BYOK, rotation involves generating a new tenant secret in the customer HSM and uploading it. The customer holds the master copy; Salesforce holds the working copy. The flow is the same as initial setup but with rotation cadence. Cache-Only Key Service rotation is similar: the customer rotates the key in their KMS; the new key is fetched by Salesforce on demand.
Automating rotation
Salesforce does not provide built-in scheduled rotation. Automation requires an Apex scheduled job that calls the key management API to generate new secrets on schedule. For most orgs, manual rotation per the calendar reminder is simpler and avoids the risk of an automated job failing silently. For high-cadence rotation (monthly or more frequent), automation may become worth the engineering investment.
Execute a Shield key rotation cycle
Executing a tenant secret rotation is a planned event. The steps below cover the full cycle from generation through Mass Encryption and post-rotation verification.
- Confirm rotation cadence is due
Check the security calendar. Confirm the rotation falls within the required window per your compliance policy.
- Notify stakeholders
Send a short note to security and compliance teams that rotation is starting. Provide the expected timeline including the Mass Encryption window.
- Open Key Management
Setup > Encryption Settings > Key Management. Confirm the current Active secret is the expected one.
- Generate the new tenant secret
Click Generate Tenant Secret (or Import for BYOK, or trigger refresh for Cache-Only). The new secret activates within seconds; the previous moves to Archived.
- Schedule Mass Encryption
Encryption Statistics > Encrypt Unencrypted Data (or equivalent). Schedule the job for a low-traffic window. Monitor progress; the job is asynchronous.
- Verify completion
After Mass Encryption finishes, confirm the data shows 100% encrypted under the new secret in Encryption Statistics. The old secret is now ready to be destroyed if policy dictates.
- Document the rotation
Setup Audit Trail > capture the rotation event. Update the rotation log with the date, executor, and verification result. Compliance audits expect this artifact.
Platform generates the new secret. The simplest mode.
Customer generates externally and uploads. Customer retains master copy.
Customer rotates in KMS. Salesforce fetches new key on demand.
The follow-up step to re-encrypt older data. Required for full rotation effectiveness.
Previous secret moves to Archived automatically when new one becomes Active.
- Rotation without Mass Encryption is incomplete. Old data remains encrypted under the previous secret; the rotation has no effect for that data until Mass Encryption runs.
- Mass Encryption is asynchronous and can take hours to days. Plan rotation timing around this window.
- Destroying an archived secret before Mass Encryption completes can leave older data unrecoverable. Confirm encryption status before destruction.
- Salesforce does not automate rotation. Set calendar reminders; the most common failure is missing the cadence.
- BYOK rotation requires coordination with the customer HSM team. Schedule the operation as a planned change with both sides notified.
Trust & references
Straight from the source - Salesforce's reference material on Key Tenant Secret Rotation.
- Fundamental Concepts in Shield Platform EncryptionSalesforce 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 Key Tenant Secret Rotation?
Q2. Why rotate tenant secrets?
Q3. Should you destroy old secrets after rotation?
Discussion
Loading discussion…