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

1.0 Introduction

There are several ways to export Fortanix-Data-Security-Manager (DSM) keys to Salesforce that support BYOK or 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 HSM backed Software-as-a-service (SAAS) for Fortanix - Salesforce Cache-Only BYOK solution. This guide explains how to use Fortanix DSM to securely generate encryption keys and configure in Salesforce’s Shield Platform.

Shield Platform Encryption requires additional licensing and may not be supported for all Salesforce apps. See more details here.

2.0 Prerequisites

The following are the prerequisites:

1. A Salesforce account with permission to below settings.

   1. Name Credentials

   2. Certificate and Key Management

   3. Key Management

2. A Fortanix DSM account with appropriate permissions to create groups, 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 Data Security Manager (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 the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

3.3 Creating a Group

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

1. Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.

   

2. On the Adding new group page, enter the following details:

   • Title: Enter a title for your group.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create the new group.

The new group has been 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. Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.

   

2. On the Adding new app page, enter the following details:

   • App name: Enter the name of your application.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

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

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

3. Click the Save button to add the new application. 

The new application has been 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. Click the Apps menu item in the DSM left navigation bar and 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 the VIEW API KEY DETAILS button.

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 add a plugin in Fortanix DSM:

1. Create a plugin in Fortanix DSM.

   1. Click the Plugins tab on the left navigation panel.

   2. Click the New Plugin button to create new plugin.

   3. Enter the "Plugin name".

      

   4. Select the Group created in Section 3.3: Creating a Group, and then click Next.

   5. Copy and paste the plugin code from the Github repository https://github.com/fortanix/sdkms-plugin-library/tree/master/salesforce, and then click Create. 

   6. Copy and save UUID of the plugin created for future configuration.

2. 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 setting in screenshot below.

   3. Disable the check box "Exportable Private Key".

   4. Select the check box “Use Platform Encryption".    

      

      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

      

Import the downloaded certificate in Fortanix DSM as explained in the next Section 3.7 Creating Security Object.

3.7 Creating a Security Object

Perform the following steps to import a certificate key in the Fortanix DSM:

1. Click the Security Objects menu item in the DSM left navigation bar and click the + button on the Security Objects page to add a security object.

   

2. On the Add New Security Object page, enter the following details:

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

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

   • Select the IMPORT radio button.

   • Choose a type: Select the Certificate key type to import.

   • Key operations permitted: Select the required operations to define the actions that can be performed with the cryptographic keys, such as encryption, decryption, signing, and verifying.

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

   • Add the required attributes if required using ADD ATTRIBUTES.

   • Enter the key Deactivation Date and key Activation Date.

3. Click the IMPORT button to import the certificate into Fortanix DSM as a security object.

4. Copy the UUID of the certificate as that will be used later 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 bar.

   

    

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

4.  Enter the details for named credential.

   1. Enter Label and Name of your choice.

   2. Enter the URL as below (where <uuid of plugin> is the UUID created in the Section 3.5: Copying an App UUID):
      https://sdkms.fortanix.com/sys/v1/plugins/invoke/<uuid of plugin>

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

   4. Enter the username and password of Fortanix DSM as created in the Section 3.5: Copying an 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

We can generate as many keys as we want with Fortanix DSM and configure in Salesforce using steps mentioned below. Whenever customer wants to rotate key, simply execute the plugin and generate a new key. The same needs to be configured in Salesforce afterwards.

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

   1. Go to plugin created in the previous section.

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

   3. Enter the following payload in the text box.

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

   4. Click RUN TEST.

      

   5. 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 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 data encryption key.
      opq_key_identifier: Fortanix DSM plugin also generates a security object of type “OPAQUE”. It contains meta-information to generate response (JWE Token) required by Salesforce. Meta-information contains the following information:

      1. AES Encryption key UUID (dek)

      2. UUID of certificate used.

      When Salesforce platform calls Fortanix DSM plugin to fetch encryption keys, the plugin reads meta information from opaque object and processes dek key material and certificate used (while generating meta info and AES initially) to generate 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 plugin and the key is stored in Fortanix DSM. The key material is securely transferred to Salesforce as part of JWE token.

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

      

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

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

      

   2. Click the Bring Your Own Key button.

      

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

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

   5. Select Named Credential created with 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 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 (refer to below screenshot).

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