You are here:
Bring Your Own Key (BYOK) Option
With BYOK, customers can bring key material from outside of Salesforce. They generate key material by using their own crypto libraries, enterprise key management system, or hardware security module. Customers can encrypt it with a self-signed or certificate authority (CA) certificate’s public key. They upload the keys to Shield Platform Encryption. They can revoke access on demand via the Key Management tooling in Setup or programmatically via the API.
Customers can opt out of the key derivation process on a key-by-key basis. When customers opt out of derivation, they upload their own DEK, which is used to directly encrypt and decrypt data. Before they’re stored in the Salesforce database, customer-supplied DEKs are wrapped, either with a tenant wrapping key or with the external root key that created them. When needed, Shield Platform Encryption unwraps the keys on the regional Shield KMS and places them in the encrypted key cache for a limited time.
Customer-supplied key material can be uploaded once every 24 hours in production and Developer Edition orgs, and every 4 hours in sandbox orgs. FLE key material can be destroyed declaratively or programmatically by the customer at any time. Database Encryption keys have a minimum 3-month lifespan.
Refer to Rotate Your Encryption Key Material for all key rotation intervals.
Field-Level Encryption BYOK
For FLE, by default, when customer-supplied tenant secrets are uploaded, all subsequent data is encrypted by using the new material. They’re encrypted either with the key derived from the current primary secret and the new customer-supplied tenant secret or the new DEK alone. This org-specific derived DEK is never persisted on disk.
Customers can opt out of the key derivation process on a key-by-key basis. When customers opt out of derivation, they upload their own DEK, which is used to directly encrypt and decrypt data. Before they’re stored in the Salesforce database, customer-supplied DEKs are wrapped, either with a tenant wrapping key or the external root key that created them. When needed, Shield Platform Encryption unwraps them on the regional Shield KMS and places them in the encrypted key cache for a limited time.
Alternatively, Field-Level Encryption customers can create and store their DEKs outside of Salesforce and use the Cache-Only Key Service to use those DEKs for Shield Platform Encryption. Customers can use an on-premises key service, host their own cloud-based key service, or use a cloud-based key brokering vendor. DEKs are fetched on demand over a secure channel that the customer configures. These DEKs are wrapped with a cache key encryption key and placed in the encrypted key cache for encrypt and decrypt operations. Because cache-only keys bypass the key derivation process, they’re used to directly encrypt and decrypt your data.
Subsequent encryption and decryption requests go through the encrypted key cache until the cache-only key is revoked or rotated, or the cache is flushed. After the cache is flushed, the Cache-Only Key Service fetches key material from your specified key service. The cache is regularly flushed every 72 hours. Certain Salesforce operations flush the cache on average every 24 hours. Destroying a DEK invalidates the corresponding DEK that’s stored in the cache.
Database Encryption BYOK
BYOKs for Database Encryption are always Database Encryption seeds. Full DEK upload isn’t supported for Database Encryption. All Database Encryption uses derived DEKs, so customers can only upload a database tenant secret. Then, unique DEKs are derived for every database fragment within the Salesforce database, as opposed to FLE DEKs, which are derived in the KMS.
Per Salesforce key backup policy, new database tenant secret material isn’t used for new DEKs for up to 24 hours. During this time a unique Salesforce provided Database Encryption seed is used. This seed becomes a permanent addition to the customer’s key archive.
- BYOK Tenant Secret Flow
To supply your own tenant secret, you create the secret, sign it with a BYOK-compatible certificate, and encode it with base64 encoding.
