Bring Your Own Key Overview

Permissions Required

To work with encryption keys, you need the Manage Encryption Keys permission. To generate BYOK-compatible certificates, you need the Customize Application permission.

BYOK Generation and Upload Process

Salesforce stores data in various databases and data stores that can vary in architecture. Because Shield Platform Encryption uses dedicated key material for each data store, not all customer-supplied keys have the same size, wrapping, and encoding requirements.

• Depending on the certificate requirements for each key, create either a self-signed or CA certificate for wrapping your key material.
• Generate your 256-bit key material. Different key material types required different generation methods.
• Wrap the key material with the certificate public key.
• Encode the encrypted, wrapped secret with base64 encoding.
• Upload your key material.

Salesforce provides scripts to help you automate this process and ensure a service-compatible key that's ready for upload.

Important We provide bash scripts for Linux and MacOs. To work with these scripts on a Windows operating system, use a Linux emulator.

BYOK for Field-Level Encryption, Files, and Event Bus Data

For Field-Level Encryption (FLE), files and attachments, and event bus data, you create and upload two files:

• A file containing the encrypted 256-bit key
• A file containing the hash of the encrypted 256-bit key

By default, Salesforce uses your uploaded secret as a tenant secret as part of a key derivation function (KDF). You can opt out of key derivation on a key-by-key basis and use your uploaded key material as the final data encryption key (DEK). In this way, you control the keys used for encrypt and decrypt operations.

Customer-supplied key material and DEKs for these data categories must meet these specifications:

• 256-bit size
• Encrypted with a public 4096-bit RSA key that’s extracted from the downloaded BYOK certificate, then padded using the SHA1 padding algorithm with OAEP padding. To be compatible with Salesforce BYOK, use a PKCS#8 encrypted, Base64 encoded RSA key pair (2048 bits or larger) with appropriate headers and footers.
• After it’s encrypted, encode it in standard base64.

BYOK for Backup & Recover Next, Data 360, Database Encryption, and Search Indexes

Salesforce secures uploaded root keys with a combination of certificates and tokens. We generate certificates for you. You then wrap your customer-supplied key with this certificate before upload. This process makes sure that your key is compatible with our encrypted storage process.

Salesforce also generates tokens that contain metadata that verifies the authenticity of your uploaded key. We use two kinds of tokens:

• Import tokens provide secure key handling during the upload process and are valid for 24 hours. BYOK for Data 360 uses import tokens.
• Session tokens are valid during the session within which they’re created. BYOK for search indexes and Database Encryption use session tokens.

You can generate a new certificate and session or import token at any time.

Generate customer-supplied root keys for search indexes, Database Encryption, and Platform Encryption for Data 360 according to these specifications:

• 256-bit size
• Requires a two-stage key wrapping process to prepare the BYOK payload, aligning with PKCS#11 CKM_RSA_AES_KEY_WRAP.

  Encrypt the 256-bit key with the 4096-bit RSA public key extracted from the downloaded BYOK certificate. This encryption process uses RSA-OAEP and MGF1 with SHA-512.

  Wrap the 256-bit customer-generated AES key using the AES wrapping key via AES Key Wrap with Padding (AES-KWP, RFC 5649). The final payload consists of the RSA-encrypted wrapping key, followed by the AES-wrapped customer key.

• Encode the encrypted key in standard base64.

BYOK Key Rotation

You can rotate BYOK keys the same as other keys managed through Shield Platform Encryption. The most recently uploaded key is the designated active key and encrypts new data. Older keys are archived and used to decrypt existing data.