Key Derivation Function (KDF)
A Key Derivation Function (KDF) is a cryptographic primitive that derives one or more secondary keys from a primary input, typically a master key, a password, or a passphrase.
Definition
A Key Derivation Function (KDF) is a cryptographic primitive that derives one or more secondary keys from a primary input, typically a master key, a password, or a passphrase. KDFs are designed to be one-way and computationally expensive, making them resistant to brute-force attacks on the underlying input. In the Salesforce context, KDFs underpin password hashing (the platform never stores plaintext passwords; it stores KDF-derived hashes), tenant secret derivation (Shield's data encryption keys derive from the tenant secret through a KDF), and various API token generation paths.
The KDF concept matters in Shield Platform Encryption because the visible tenant secret is not what actually encrypts records; the platform derives per-record or per-context data encryption keys through a KDF chain from the tenant secret. This separation lets the platform rotate keys without re-encrypting all data: rotation changes the tenant secret, but only new writes use the new derived keys. Older data remains decryptable with the original derivation chain until a Mass Encryption job re-derives.
How KDFs underpin Salesforce key management
Why KDFs exist
Direct use of a master key for every encryption operation is dangerous: any compromise of the master key compromises all data. KDFs solve this by deriving narrower-scope keys that can be rotated without touching the master. A KDF chain might derive: master tenant secret > per-record data key > per-field encryption key, each step using a one-way function so reversing from the data key does not reveal the tenant secret.
Common KDF algorithms
Modern systems use PBKDF2, bcrypt, scrypt, or Argon2 for password-based KDFs, all designed to be deliberately slow to resist brute force. For key-based KDFs (deriving one key from another), HKDF is the standard. Each algorithm has security and performance characteristics; Salesforce's specific KDF choices are documented in the Shield architecture papers but treated as platform internals for most administrators.
KDF in password storage
When a user sets a Salesforce password, the platform does not store the password. Instead, it stores a KDF-derived hash with a unique salt per user. To verify a login, the platform applies the same KDF to the submitted password and compares the result to the stored hash. The one-way property means compromising the password storage does not directly reveal passwords; attackers must brute-force each hash individually, which the deliberate slowness of the KDF makes expensive.
KDF in Shield key derivation
Shield's tenant secret is the master key but rarely the direct encryption key. The platform derives data encryption keys from the tenant secret through a KDF chain, with the derivation parameters specific to each record or field. Rotation works by changing the tenant secret: new writes use new derived keys; old data remains decryptable with the previous tenant secret. The KDF is what makes this rotation feasible without massive re-encryption.
Salt and its purpose
KDFs typically take a salt input alongside the master key. The salt is a unique value per derivation that prevents identical inputs producing identical outputs across users or records. For password hashes, the salt is per-user. For Shield key derivation, the salt is per-record-or-field. The salt is not secret; it is stored alongside the hash or ciphertext. The purpose is precisely to prevent rainbow-table attacks (precomputed hash lookups) and to provide cryptographic separation between derivations.
KDF performance considerations
KDFs are deliberately slow to resist brute force. For password verification, the slowness happens only on login attempts (rare). For Shield key derivation, the slowness happens on every encryption and decryption, which adds up for high-volume operations. The platform caches derived keys briefly to mitigate the cost; for Cache-Only Key Service users, the cache plus KDF cost adds noticeable latency to encrypted-field operations. Plan accordingly.
Custom Apex and KDF
Apex code that handles passwords or master keys should use Crypto.generateMac() for HMAC-based derivation, or external libraries for PBKDF2/scrypt/Argon2. Hand-rolling a KDF in Apex is a security risk; the standard libraries handle salt, iteration count, and other details correctly. For password-storage scenarios in custom apps, prefer Auth Providers that handle the cryptography rather than building your own.
Work with KDFs in Shield and custom code
KDFs are mostly invisible to administrators because the platform handles key derivation internally. The steps below cover the cases where KDF concepts matter for custom code or Shield architecture decisions.
- Identify scenarios requiring KDF awareness
Most administrators never need to think about KDFs. Awareness matters for Shield architects designing rotation strategy and Apex developers building custom encryption.
- For Shield rotation, plan the cadence
The KDF chain enables non-disruptive rotation. Plan quarterly or annual rotation; the KDF is what makes this feasible at scale.
- After rotation, run Mass Encryption
Mass Encryption re-derives data keys for older records under the new tenant secret. Without it, old keys remain in use indefinitely.
- For custom Apex, use Crypto.generateMac()
Need HMAC-based derivation? Use the built-in Crypto.generateMac(). Need stronger password hashing? Use an external library through a Named Credential proxy, not hand-rolled Apex.
- Audit custom encryption code
Any Apex code handling passwords or deriving keys deserves a security review. Hand-rolled KDFs are a common vulnerability source.
- Document KDF choices for compliance
Compliance auditors may ask which KDF algorithms protect your data. Shield documentation answers this; document custom code separately.
- Benchmark performance impact
For Cache-Only Key Service or heavy custom encryption, the KDF cost is observable. Benchmark before production to set expectations.
Platform-managed. Administrators do not configure directly; rotation is the visible operation.
Platform-managed for Salesforce passwords. Users never see the derivation.
HMAC-based derivation for custom Apex needs.
For stronger password hashing in custom apps, call an external service.
Handles authentication including password storage. The standard alternative to custom KDF in Apex.
- Hand-rolling a KDF in Apex is a serious security risk. Standard algorithms exist for a reason; custom implementations usually have subtle bugs.
- KDF slowness compounds with HSM round-trip for Cache-Only Key Service. The combined cost can make encrypted-field queries noticeably slower than plaintext queries.
- Salt and IV are different concepts often confused. Salt prevents identical KDF outputs; IV prevents identical ciphertexts. Both serve uniqueness but in different contexts.
- Mass Encryption after rotation is the step that makes rotation meaningful. Skipping it means old keys remain in use indefinitely.
- Compliance audits sometimes ask about KDF specifics. Shield documents the algorithms; custom code needs separate documentation.
Trust & references
Straight from the source - Salesforce's reference material on Key Derivation Function (KDF).
- 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 a Key Derivation Function?
Q2. Why does the KDF approach matter for multi-tenant security?
Q3. Do administrators interact with KDFs directly?
Discussion
Loading discussion…