1. Fortanix
  2. Fortanix Data Security Manager (DSM)
  3. Integration / Use-case
  4. Cloud Key Management / BYOK

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

Last Updated: 

Overview

There are several ways to export Fortanix Data Security Manager (DSM) keys to Salesforce that support BYOK for server-side encryption. 

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.   imageRedbox1.png

Salesforce

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.

Fortanix Data Security Manager Setup

  1. Create a Group in Fortanix DSM.
    1. Log in to Fortanix DSM (https://<fortanix_dsm_url>)
    2. Click the left navigation bar to navigate to the Groups tab.
      SalesforceBYOKSdkms-Step1.png
      Figure 1: Groups Page
       
    3. Click the (+) icon or click the Create New Group button to create a new group.
      SalesforceBYOKSdkms-Step2.png
      Figure 2: Create Group
       
  2. Create an app in Fortanix DSM.
    1. Click the left navigation bar to navigate to the Apps tab.
        SalesforceBYOKSdkms-Step3.png
      Figure 3: Apps Page
       
    2. Click the (+) icon or Click New App to create a new app.
    3. Enter the desired information (refer below screenshot), and select the group created in the previous step, and then click SAVE.
        SalesforceBYOKSdkms-Step5.png
      Figure 4: Create App
       
    4. Navigate to the Apps dashboard to see the newly created app.
          SalesforceBYOKSdkms-Step6.png
      Figure 5: View App
       
    5. Click the COPY API KEY link. It opens a model window.
    6. Go to the USERNAME/PASSWORD tab in the model window.       SalesforceBYOKSdkms-Step7.png
                              Figure 6: View Credentials    
    7. Copy and Save the username / password. Details will be required later to configure “Named Credentials” in Salesforce later.
  3. 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".
        PluginsRedbox.png
      Figure 7: Plugins Page
       
    4. Select the “Group” created in Step 1, 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.
  4. 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".   SalesforceBYOKSdkms-Step9.png
      Figure 8: Use Platform Encryption
       
      Please refer to the Salesforce documentation for more info on “Certificate and Key Management”.
    5. Once certificate is created, please download it. SalesforceBYOKSdkms-Step10.png
      Figure 9: Download the Certificate
       
      Download the certificate, and then save to your desired location.
  5. Import the Certificate to Fortanix DSM.
    1. Log in to Fortanix DSM.
    2. Click the left navigation bar to navigate to the “Security Objects” tab.
      SalesforceBYOKSdkms-Step11.png
      Figure 10: Create Security Object 
       
    3. Click the (+) button or click Create Security Object button to create a new Security object.
    4. Enter the name of security object, and then select the Group created in Step 1.
    5. Click the IMPORT button.
      SalesforceBYOKSdkms-Step12.png
      Figure 11: Import Security Object
       
    6. Choose Security Object type as “Certificate”.
    7. Choose value format as “BASE 64”.
    8. Click the Upload a file button to upload the converted certificate at Step 4d.
    9. Click the IMPORT button to import the certificate into Fortanix DSM as a security object.
      SalesforceBYOKSdkms-Step13.png
      Figure 12: Security Object Import Options
       
    10. Copy the UUID of the certificate as that will be used later in setting up Salesforce credentials.
  6. Salesforce Setup:
    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.
        SalesforceBYOKSdkms-Step14.png
                 Figure 13: Security Menu  
      Click the New Named Credential button. It opens a screen to create a Named Credential.
      SalesforceBYOKSdkms-Step15.png
      3.  
    3. Enter the details for named credential.
      1. Enter Label and Name of your choice.
      2. Enter the URL as below (uuid: uuid of plugin created in the section Fortanix Data Security Manager Setup Step 3):
        https://<fortanix_dsm_url>/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 created in the section Fortanix Data Security Manager Setup Step 2, and then click Save.
        SalesforceBYOKSdkms-Step16.png
        Figure 14: New Named Credential Page
         
      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.
          imageRedbox.png
        Figure 15: Advanced Settings
         

Steps to 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 Step 3 of section Fortanix Data Security Manager Setup.
    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.
      SalesforceBYOKSdkms-Step17.png
      Figure 16: 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. Refer salesforce documentation for more info on 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.
      SalesforceBYOKSdkms-Step18.png
      Figure 17: Security Menu
       
  2. Configure Salesforce to use Fortanix DSM to fetch Cache-only Key at runtime.
    1. Go to Setup >> Security >> Platform Encryption >> Key Management.
      SalesforceBYOKSdkms-Step19.png    
      Figure 18: Platform Encryption  
    2. Click the Bring Your Own Key button.
      SalesforceBYOKSdkms-Step20.png
      Figure 19: Bring Your Own Key
       
    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.
      SalesforceBYOKSdkms-Step21.png
      Figure 20: Security Menu
       
    8. Once 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.
      SalesforceBYOKSdkms_TokenUsingPluginStep22.png
      Figure 21: Key Management
       
  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 below screenshot).
    3. Logs are also generated later when Salesforce calls Fortanix DSM to fetch the encryption keys at runtime.
        SalesforceBYOKSdkms-Step23.png
      Figure 22: Events and Tasks
       

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful