Bring Your Own Key (BYOK) 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 Upload Process

In a nutshell, uploading your own key is a multi-step process

• Create a self-signed or CA certificate for wrapping your key material.
• Generate your 256-bit key material.
  

  Note You use a different method for tenant secrets and root key-based secrets, like Search and Database Encryption.
• Wrap the key material with the certificate public key using the SHA512 padding algorithm.
• Encode the encrypted, wrapped secret with base64 encoding.
• Upload your material on the Key Management Page.

We provide scripts to help you automate this process.

Important We currently provide bash scripts for Linux and MacOs only. If you want to use one of our scripts, but are using the Windows operating system, you will need to use a Linux emulator.

BYOK for FLE, Files, and Event Bus Data

For Field-Level Encryption (FLE), Files and Attachments, and Event Bus Data, you use the appropriate form on the Key Management page to upload two files that you create:

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

By default for these features the secret you upload is used by Salesforce as a tenant secret, and is used as part of a key derivation function (KDF). If you enable the Allow BYOK to Opt Out of Key Derivation option on the Encryption Settings page, you can choose to upload a final data encryption key (DEK) instead.

You can use a tenant secret BYOK for one feature, such as FLE, and use a DEK BYOK for another feature, such as Files and Attachments.

For FLE, Files and Attachments, and Event Bus Data, your customer-supplied key material for FLE must meet these specifications:

• 256-bit size
• Encrypted with a public 4096-bit RSA key that is 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 Search Index Encryption, Database Encryption, and Platform Encryption for Data 360.

BYOK for search indexes and for Database Encryption uses certificates and session tokens to secure your key material. BYOK for Data 360 uses certificates and import tokens.

• Salesforce generates a compatible certificate that you then use to wrap your customer-supplied key. This certificate ensures that your key is compatible with our encrypted storage processes.
• Salesforce also generates a session token (for search and database encryption) or an import token (for Platform Encryption for Data 360) containing metadata that verifies the authenticity of your uploaded key. It provides secure key handling during the upload process. Session tokens are valid during the session within which they are created. Import tokens are valid for 24 hours. You can generate a new certificate and session or import token at any time.

For search indexes, Database Encryption, and Platform Encryption for Data 360 your customer-supplied key material must meet 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.

  First, a 256-bit AES wrapping key is generated and encrypted by using the 4096-bit RSA public key extracted from the downloaded BYOK certificate. The encryption uses RSA-OAEP and MGF1 with SHA-512.

  Next, the 256-bit customer-generated AES key is wrapped by 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.

• After it’s encrypted, encode it in standard base64.

BYOK Key Rotation

You can rotate BYOK keys the same as other FLE keys, subject to the rotation period restriction for the feature. The most recently uploaded key is the designated active key and encrypts new data. Older keys are archived and used to decrypt existing data.