Exporting Fortanix Data Security Manager keys to Cloud Providers for BYOK - Salesforce (Using Cache-Only Keys)

1.0 Introduction

This document describes the steps required to export t Fortanix-Data-Security-Manager (DSM) keys to Salesforce that support BYOK for server-side encryption.

Salesforce's Shield Platform Encryption is introducing a new pilot feature called Cache-Only Keys. This capability enhances the existing Bring Your Own Key (BYOK) capability by allowing customers to host their key material in a wrapped format, which Salesforce fetches as required. While this is cached in an encrypted form, Salesforce does not retain or persist the key material in any system of record or backups.

Fortanix DSM can be used as an HSM-backed Software-as-a-service (SAAS) for Fortanix - Salesforce Cache-Only BYOK solution. This article explains how to use Fortanix DSM to securely generate encryption keys and configure it in Salesforce’s Shield Platform.

Shield Platform Encryption requires additional licensing and may not be supported for all Salesforce apps. For more information, refer to the Salesforce documentation.

2.0 Prerequisites

Ensure the following:

1. A Salesforce account with permission to the below settings.

   1. Named Credentials

   2. Certificate and Key Management

   3. Key Management

2. A Fortanix DSM account with appropriate permissions to create groups, applications (apps), security objects, and plugins.

3. Ensure that the required permissions are available before proceeding. The following is the procedure:

   1. From Setup, enter Permission Sets in the Quick Find box, then select Permission Sets.

   2. Click New.

   3. Create a label for the set of permissions, for example, Key Manager. The API name populates with a variation of your chosen label.

   4. Click Save.

   5. In the System section of the Key Manager page, select System Permissions.

   6. Click Edit, and enable the Customize Application and Manage Encryption Keys permissions.

   7. Click Save.

   8. From Setup, enter Users in the quick find box, then select Users.

   9. Select the name you want in the User list.

   10. Scroll down to Permission Set Assignments, and select Edit Assignments.

   11. Select Key Manager, then add it to the Enabled Permission Sets list.

   12. Click Save.

4. Before you can start encrypting data, you need to create a tenant secret:

   1. From Setup, in the Quick Find box, enter Platform Encryption and then select Key Management.

   2. Select Data in Salesforce from the Choose Tenant Secret Type list. Tenant secret types allow you to specify which kind of data you want to encrypt with a tenant secret. You can start by encrypting data in the core Salesforce database for now.

   3. Select Generate Tenant Secret. Now, you have a tenant secret that the Salesforce key management service can use to create the keys. Those keys encrypt and decrypt the data.

      

3.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

3.1 Signing Up

To get started with the Fortanix DSM cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

3.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

For more information on how to set up an account in Fortanix DSM, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

3.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.

   

2. On the Adding new group page, do the following:

   1. Title: Enter a name for your group.

   2. Description (optional): Enter a short description of the group.

3. Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

3.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the + button to create a new app.

   

2. On the Adding new app page, do the following:

   1. App name: Enter the name for your application.

   2. ADD DESCRIPTION (optional): Enter a short description of the application.

   3. Authentication method: Select the default API Key as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication.

   4. Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.

3. Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

3.5 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click VIEW API KEY DETAILS.

3. Click the USERNAME/PASSWORD tab.

4. From the Credentials Details dialog box, copy the Username (app UUID) and Password of the app to use it later to configure Named Credentials in Salesforce.

3.6 Creating a Plugin

Perform the following steps to create a new plugin:

1. In the DSM left navigation panel, click the Plugins menu item and then click + NEW PLUGIN to create, import, or browse a new plugin.

2. On the NEW PLUGIN dialog box, select the CREATE/IMPORT A NEW PLUGIN tile.

   NOTE

   Fortanix DSM currently supports plugins in Lua.

   

3. In the Adding new plugin form, do the following:

   1. Plugin name: Enter a name that identifies your plugin. For example: Demo Plugin.

   2. In the Assigning the new plugin to groups section, assign the new plugin to an existing group. You can also create a new group by clicking CREATE NEW GROUP and assigning the plugin to the new group.

   3. Click Next.

      

   4. On the next screen, copy and paste the plugin code from the GitHub repository.

4. Click CREATE.

   

The new plugin is added to the Fortanix DSM successfully.

3.7 Copying the Plugin UUID

Perform the following steps to copy the plugin UUID from the Fortanix DSM:

1. In the DSM left navigation panel, click the Plugins menu item, and then click the plugin created in Section 3.6: Creating a Plugin to go to the detailed view of the plugin.

2. From the top of the plugin’s page, click the copy icon next to the plugin UUID to copy it to use in setting up Salesforce credentials.

3.8 Creating a Self-Signed Certificate in Salesforce.

Perform the following steps to generate and download a Self-signed certificate in Salesforce:

1. Log in to Salesforce. Go to Setup.

2. Create a Self-signed certificate under Security → Certificate and Key Management with the settings.

3. Disable the Exportable Private Key check box.

4. Select the Use Platform Encryption check box.

   

   For more information, refer to the Salesforce documentation: Certificate and Key Management.

5. After the Self-signed certificate is created, download and save it to your desired location to import it in Fortanix DSM as explained in Section 3.9: Creating a Security Object.

   

3.9 Creating a Security Object

Perform the following steps to import the certificate downloaded from Salesforce in Fortanix DSM:

1. In the DSM left navigation panel, click the Security Objects menu item, and then click the + button to create a new security object.

   

2. On the Add new Security Object page, do the following:

   1. Security Object name: Enter the name of your security object.

   2. Group: Select the group as created in Section 3.3: Creating a Group.

   3. Select the IMPORT radio button.

   4. In the Choose a type section, select the Certificate key type.

   5. In the Place value here or import from file section, select the value format type as Hex, Base64, or Raw, and click UPLOAD A FILE to upload the certificate.

   6. In the Key operations permitted section, select the required operations to define the actions that can be performed with the cryptographic keys, such as encryption, decryption, signing, and verifying.

3. Click IMPORT to create the new security object.

3.10 Copying the Security Object UUID

Perform the following steps to copy the security object UUID from the Fortanix DSM:

1. In the DSM left navigation panel, click the Security Objects menu item, and then click the security object created in Section 3.9: Creating a Security Object to go to the detailed view of the security object.

2. From the top of the security object’s page, click the copy icon next to the security object UUID to copy it to use in setting up Salesforce credentials.

4.0 Salesforce Setup

Perform the following steps to define the Named Credential in Salesforce:

1. Log in to Salesforce. Go to Setup.

2. Click the “Named Credentials” item under the Security menu in the left navigation menu.

   

    

3. Click New Named Credential. It opens a screen to create a Named Credential. 

4.  Enter the details for the named credential.

   1. Enter Label and Name of your choice.

   2. Enter the URL: https://sdkms.fortanix.com/sys/v1/plugins/invoke/<uuid of plugin>

      Where, <uuid of plugin> is the UUID as copied in Section 3.5: Copying the App UUID.

   3. Select the Identity Type as Named Principal and the Authentication Protocol as Password Authentication.

   4. Enter the username and password of Fortanix DSM as created in Section 3.5: Copying the App UUID, and then click Save.

      

   5. Go to Security → Platform Encryption → Advanced Settings and set Allow Cache-Only Keys with BYOK option to ON.
      Optionally, you can enable replay detection by setting the Enable Replay Detection for Cache-Only Keys option to ON.

      

4.1 Generate Encryption Keys and Import to Salesforce

Multiple keys may be generated using Fortanix DSM and configured in Salesforce by following the steps below. When a customer requires key rotation, the plugin must be re-executed to generate a new key, which is then reconfigured in Salesforce.

1. Generate JWE Token (BYOK Cache only KEY) using the plugin.

   1. Navigate to the plugin created in Section 3.6: Creating a Plugin.

   2. Click ADD TEST INPUT on the right-hand side.

   3. Enter the following payload in the input field:

      {
      "cert": "<uuid of certificate imported in DSM>",
      "name": "<unique name of key eg: salesforce_ency_key_v1>"
      }

   4. Click RUN TEST.

      

   5. The plugin generates security objects (AES encryption key and meta information) in Fortanix DSM and returns their UUID.
      Copy the value of “opq_key_identifier” field in the response body.
      This is required while setting up BYOK in Salesforce.
      dek: UUID of AES encryption key generated by plugin and stored securely in Fortanix DSM. Salesforce uses it as the data encryption key.
      opq_key_identifier: Fortanix DSM plugin also generates a security object of type OPAQUE. It contains meta-information to generate a response (JWE Token) required by Salesforce. Meta-information contains the following information:

      1. AES Encryption key UUID (dek)

      2. UUID of the certificate used.

      When the Salesforce platform calls the Fortanix DSM plugin to fetch encryption keys, the plugin reads meta information from the opaque object and processes dek key material and certificate used (while generating meta info and AES initially) to generate the JWE token. The same is returned to Salesforce in the desired JSON format. For more information, refer to the Salesforce documentation: JWE token.

   6. dek value is AES encryption key, which is generated by the plugin and the key is stored in Fortanix DSM. The key material is securely transferred to Salesforce as part of the JWE token.

   7. Go to the Security Objects screen to see the newly created object.

      

2. Configure Salesforce to use Fortanix DSM to fetch the Cache-only Key at runtime.

   1. Go to Setup → Security → Platform Encryption → Key Management.

      

   2. Click Bring Your Own Key.

      

   3. Select the desired certificate to be used (it should be the same as the one used while executing the plugin to generate the encryption key and meta information).

   4. Select the Use a Cache-Only Key radio button.

   5. Select the Named Credential created with the Fortanix DSM endpoint.

   6. Enter BYOK ID (opq_key_identifier) generated by the Fortanix DSM plugin in Step 1.

   7. Click Save.

      

   8. After the configuration is saved, Salesforce calls Fortanix DSM to fetch the JWE token and decrypt it with the private key of the certificate.

   9. You can see the newly imported key on the “Key Management” screen.

      

3. Verify the Key Import in the Fortanix DSM Event logs.

   1. Logs are generated in Fortanix DSM while fetching encryption keys during setup (after Step 2i).

   2. Go to Event Logs in Fortanix DSM to verify.

   3. Logs are also generated later when Salesforce calls Fortanix DSM to fetch the encryption keys at runtime.