Loading
Prepare for Email to Become the Default Login ExperienceRead More
Set Up and Maintain Your Salesforce Organization
Upload Your BYOK Key Material

You are here:

  1. Salesforce Help
  2. Docs
  3. Set Up and Maintain Your Salesforce Organization

Upload Your BYOK Key Material

After you prepare your Bring Your Own Key (BYOK) key material, upload it to Salesforce. You can upload keys for most categories of data that Shield Platform Encryption supports. Each data category uses a different type of key material: tenant secrets for deriving data encryption keys, data encryption keys (DEKs) for direct encryption, or root keys for securing other keys. You upload the key for your category of data, such as search indexes, plus a second file that secures your key material during upload.

Required Editions

Available in both Salesforce Classic (not available in all orgs) and Lightning Experience.
Available in: Enterprise, Performance, and Unlimited Editions with the Salesforce Shield or Shield Platform Encryption licenses.
Available for free in Developer Edition.
User Permissions Needed
To generate, destroy, export, import, upload, and configure key material: Manage Encryption Keys
To view and edit Setup: View Setup and Configuration

Before you start, make sure that you have a BYOK-compatible certificate and have created and wrapped your BYOK key material.

As a best practice, back up your key material in a safe location.

Note
Note

You can have up to 50 active and archived tenant secrets of each type. For example, you can have one active and 49 archived Fields and Files (Probabilistic) tenant secrets, and the same number of Event Bus tenant secrets. This limit includes Salesforce-generated and customer-supplied key material. Database Encryption keys don't contribute to this limit.

If you reach the limit, destroy an existing key before reactivating, rearchiving, or creating a callout to another one. Before destroying a key, synchronize the data that it encrypts with an active key.

See Also

Upload a Tenant Secret for Field-Level Encryption, Files, or Event Bus Data

For field-level encryption (FLE), files and attachments, or event bus data, the Shield Key Management Service (KMS) uses your tenant secret to derive your org-specific data encryption key. The tenant secret that you upload for a specific category, such as the event bus, is used to encrypt and decrypt only that data.

The upload for FLE, Files and Attachments, and Event Change Data requires two files: the encrypted key material and the hashed plaintext key material, which secures your encrypted tenant secret during upload.

  1. From Setup, use the Quick Find box to find and select Key Management.
    The Key Inventory and Management page loads.
  2. In the Key Inventory section, select a key type: Fields and Files (Probabilistic), Fields (Deterministic), or Event Bus.
  3. Click Bring Your Own Key.
    If you're prompted to generate a certificate, choose either Self-Signed or CA Signed. If you already created certificates, you can either select one of those or create one.
  4. Give your certificate a unique label, and save your work.
  5. Use this certificate to prepare your key material for upload. See Wrap BYOK Key Material.
  6. In the Upload Tenant Secret section, attach both the encrypted tenant secret and the hashed plaintext tenant secret. Click Upload.
    Upload a tenant secret for field-level encryption, files, or event bus data

    This tenant secret becomes the active tenant secret. If you don't want Salesforce to derive a data encryption key for you, you can opt out of key derivation and upload your own final data encryption key. For more information, see Opt Out of Key Derivation with BYOK.

Upload a Tenant Secret for Database Encryption

The Shield Key Management Service (KMS) uses your customer-supplied Database tenant secret to derive the keys used for encrypting and decrypting your data in the transactional database. This tenant secret encrypts only the data stored in the transactional database.

Generate a self-signed certificate, and then wrap your Database tenant secret with that certificate's public key. Your certificate comes with a session token that secures your tenant secret during the upload process.

  1. From Setup, use the Quick Find box to find and select Key Management.
    The Key Inventory and Management page loads.
  2. In the Key Inventory section, select Database.
  3. Click Bring Your Own Key.
  4. If prompted, enter a unique name for a new certificate and then click Generate Certificate. If you already have a self-signed certificate, you see details about your active certificate.
  5. Click Download Certificate and Token.
    Two files download: the certificate and a session token.
  6. Use this certificate to prepare your key material for upload. See Wrap BYOK Key Material.
  7. In the Upload Tenant Secret section, attach your wrapped tenant secret and the session_token.txt file associated with your certificate. Click Upload.
    Upload a tenant secret for Database Encryption

    This tenant secret becomes the active tenant secret for Database Encryption.

Upload a Data Encryption Key for Search Index Encryption

For Search Index Encryption, you upload a data encryption key (DEK) as your BYOK key material. The Shield Key Management Service (KMS) uses your DEK directly for encrypting and decrypting your data. BYOK DEKs encrypt only search indexes.

Before you can create a search index DEK, you must have an active Salesforce root key. The root key secures the DEK during routine encryption and decryption operations. When you first turn on search index encryption, Salesforce automatically generates a root key and DEK.

The upload requires two files: the encrypted key material and the session token file associated with your certificate.

  1. From Setup, use the Quick Find box to find and select Key Management.
    The Key Inventory and Management page loads.
  2. In the Root Key Inventory section, check that a root key exists. If a root key exists, skip these substeps and go to the next step. If you don't have a root key, generate one.
    1. Click Generate Root Key.

      The Configure a Key Management Service window appears.

      Create a root key
    2. Click Shield Key Management Service and then click Done.
      Salesforce begins generating your root key, which can take a while. When the root key is ready, you're notified by email. Later steps require an active Salesforce root key.
  3. In the Key Inventory table, select Search Index.
  4. Click Bring Your Own Key.
  5. If prompted, enter a unique name for a new certificate and then click Generate Certificate.
  6. Click Download Certificate and Token.
    Two files download: the certificate and a session token.
  7. Use this certificate to prepare your key material for upload. See Wrap BYOK Key Material.
  8. In the Upload Data Encryption Key section, attach both the wrapped data encryption key and the session_token.txt file associated with your certificate. Click Upload.
    Upload a DEK for search index encryption

    This DEK becomes the active DEK for search indexes.

    From here on, the Shield KMS uses your DEK to encrypt and decrypt your users' search data.

Upload a Root Key for Backup & Recover Next or Data 360

For Backup & Recover Next and Data 360, you upload a root key to Salesforce. Your root key secures the data encryption key (DEK) that encrypts and decrypts all Data 360 data stores, including Data 360's vector-based search, and backups stored at-rest. As with other BYOK keys, your root keys for each data store are exclusive to that data store.

  1. From Setup, use the Quick Find box to find and select Key Management.
    The Key Inventory and Management page loads.
  2. In the Root Key Inventory section, select Data 360 or Backup & Recover.
  3. Click Generate Root Key.

    The Configure a Key Management Service box appears.

    Select the Bring Your Own Root Key option from the key management service window
  4. Click Bring Your Own Root Key. Then click Next.
  5. If prompted, enter a unique name for a new certificate and then click Generate Certificate.
  6. Click Download Certificate and Token.
    Two files download: the certificate and a session token.
  7. Use this certificate to prepare your key material for upload. See Wrap BYOK Key Material.
  8. In the Upload Root Key section, attach both the wrapped root key and the import_token.txt file associated with your certificate. Click Upload.
    Upload a root key and import token for Data 360 or Backup & Recover Next root keys

    The uploaded secret becomes the active root key.

    From here on, Data 360 uses your root key to secure the DEKs for all Data 360 data stores. Your Backup & Recover Next root key secures the DEKs that encrypt backups stored at rest.

 
Loading
Salesforce Help | Article