Exporting Fortanix Data Security Manager keys to Cloud Providers for BYOK - Salesforce

Overview

The purpose of this article is to describe the steps required to 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

Fortanix Data Security Manager Setup

  1. Create a Group in Fortanix DSM.
    1. Log in to Fortanix DSM (https://sdkms.fortanix.com)
    2. Click the left navigation bar to navigate to the Groups tab.
       GroupsRedbox.png
      Figure 1: Groups Page  
    3. Click the (+) icon or click the Create New Group button to create a new group.
        Groups3.png
      Figure 2: Create Group  
  2. Create an app in Fortanix DSM.
    1. Click the left navigation bar to navigate to the Apps tab.
        AppsRedbox.png Figure 3: Apps Page  
    2. Click the (+) icon or Click New App to create a new app.
    3. Enter the desired information (refer the screenshot below), and select the group created in the previous step, and then click SAVE.
        Apps2.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. The 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-automated, and then click Create
    6. Copy and save UUID of the plugin created for future configuration.
  4. 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.
        SecurityObjectsRedBox.png
      Figure 8: 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.
        SecurityObjectsImportRedbox.png
      Figure 9: 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.
    9. Click the IMPORT button to import the certificate into Fortanix DSM as a security object.
       SecurityObjectsImport1Redbox.png
      Figure 10: Security Object Import Options  
    10. Copy the UUID of the certificate as that will be used later in setting up Salesforce credentials.

Initialize Salesforce

Fortanix DSM allows for secure generation, escrow, and lifecycle management of Salesforce tenant secrets. This enables customers to backup encryption keys for the Salesforce Shield Platform.

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

  1. Create a New Profile under Setup >> Profiles.
    Select “Manage Encryption Keys” under “Administrative Permissions" .keyManagerProfile.png Figure 11: Key Manager Profile Page
  2. Create a New User under Setup >> Users with the following inputs:
    • Name: arbitrarily input
    • Profiles: choose the KMS role created in previous step
    • Note the credentials to securely import into Fortanix DSM secret.
    allUsers.png
    Figure 12: All Users
  3. Create a Connected App under “Apps >> App Manager” with the following inputs:
    • Name: arbitrarily input
    • Select the “Enable OAuth Settings
    • Select the “Enable Device Flow” for automated access
    • Note the credentials to securely import into Fortanix DSM secret.

      connectedApp1.png
      Figure 13: Connected App Detail LEAppManager.png
      Figure 14: Lightning Experience App Manager manageConnectedApp1.png
      Figure 15: Manage Connected Apps

  4. Whitelist the Fortanix DSM application IP range (CIDR).NetworkAccess.png
    Figure 16: Network Access Page
  5. Create a Certificate under “Setup >> Certificate and Key Management” and use the following:
    • Label: arbitrarily input, but note it for later use
    • Clear the “Exportable Private Key
    • Select the option to "Use Platform Encryption"
    CertificateAndKeyManagement.png
    Figure 17: Certificate and Key Management
  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 18: Security Menu  
      Click the New Named Credential button. It opens a screen to create a Named Credential.
      SalesforceBYOKSdkms-Step15.png
    3.  
    4. 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 DSMSetup Step 3):
        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 created in the section Fortanix DSM Setup Step 2, and then click Save.
        NewNamedCredentialPage1.png
        Figure 19: New Named Credential Page
  7.      
  8. 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. Clearthe check box "Exportable Private Key".
    4. Select the check box “Use Platform Encryption".   SalesforceBYOKSdkms-Step9.png Figure 20: Use Platform Encryption  
      Please refer to the Salesforce documentation (https://developer.salesforce.com/docs/) for more information on “Certificate and Key Management”.
    5. Once certificate is created, please download and save it to your desired location. SalesforceBYOKSdkms-Step10.png
      Figure 21: Certificate and Key Management     
  9. Verify the following Salesforce credentials:
    • Client/Consumer Key (Created in step 3)
    • Client/Consumer Secret (Created in step 3)
    • OAuth username (Created in step 2)
    • OAuth password (Created in step 2)
    • Tenant URI API version (Fortanix Plugin tested against version 50.0)
  10.                         

Plugin Operations

Configure Operation

This operation configures Salesforce credentials in Fortanix DSM and returns a UUID. You need to pass this UUID for other operations. This is a one-time process.

Parameters:

    • operation: The operation which you want to perform. A valid value is configure.
    • consumer_key: Consumer Key of the connected app.
    • consumer_secret: Consumer Secret of the connected app.
    • username: OAuth username.
    • password: OAuth password.
    • tenant: Salesforce tenant URI.
    • version: API version (Fortanix Plugin tested against version 50.0).
    • name: Name of the sobject. This sobject will be created in Fortanix DSM and will have Salesforce credential information.

Example:

Input JSON:

{
  "operation": "configure",
  "consumer_key": "CBK...................D",
  "consumer_secret": "DMV................D",
  "username" : "ft......x@<your company domain>",
  "password" : "fy....K",
  "tenant"   : "<Salesforce tenant URI>",
  "version"  : "v50.0",
  "name"    : "Salesforce NamedCred Dev"
}

Output:

"3968218b-72c3-4ada-922a-8a917323f27d"

Check Operation

This operation is to test whether plugin can import wrapping certificate from Salesforce into Fortanix DSM (This certificate is required by plugin to authenticate itself to Salesforce).

Parameters:

    • operation: The operation which you want to perform. A valid value is check.
    • secret_id: The response of configuration operation.
    • wrapper: Name of the wrapping certificate in Salesforce.

Example

Input JSON

{
  "operation": "check",
  "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "wrapper"  : "SFBYOK_FTX_Wrapper"
}

Output JSON

{
  "group_id": "ff2............................c",
  "public_only": true,
  "key_ops": [
    "VERIFY",
    "ENCRYPT",
    "WRAPKEY",
    "EXPORT"
  ],
  "enabled": true,
  "rsa": {
    "signature_policy": [
      {
        "padding": null
      }
    ],
    "encryption_policy": [
      {
        "padding": {
          "OAEP": {
            "mgf": null
          }
        }
      }
    ],
    "key_size": 4096
  },
  "state": "Active",
  "created_at": "20201229T183553Z",
  "key_size": 4096,
  "kid": "6de........................4",
  "origin": "External",
  "lastused_at": "19700101T000000Z",
  "obj_type": "CERTIFICATE",
  "name": "SFBYOK_FTX_Wrapper",
  "acct_id": "ec9.......................7",
  "compliant_with_policies": true,
  "creator": {
    "plugin": "654.......................1"
  },
  "value": "MII........................9",
  "activation_date": "20201229T183553Z",
  "pub_key": "MII......................8",
  "never_exportable": false
}

CheckOperation.png Figure 22: Configure Operation

Query Operation

This operation allows you to search tenant secrets (Salesforce encryption keys) using Salesforce Sobject Query Language (SSQL).

Parameters

    • operation: The operation which you want to perform. A valid value is query or search.
    • secret_id: The response of configuration operation.
    • query: SSQL query.
    • tooling:  It is an optional flag. If set to true, it allows querying against the Salesforce Tooling REST API.
    • sandbox: To indicate, whether to use test or production tenant.

Example

Input JSON

{
  "operation": "search",
  "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "query"   : "select Id, Status, Version from TenantSecret where Type = `Data`",
  "tooling"  : false,
  "sandbox"  : false
}

Output JSON

{
  "done": true,
  "totalSize": 5,
  "records": [
    {
      "attributes": {
        "type": "TenantSecret",
        "url": "/services/data/v50.0/sobjects/TenantSecret/02G..........O"
      },
      "Status": "ARCHIVED",
      "Id": "02G.............D",
      "Version": 3
    },
    {
      "Version": 1,
      "attributes": {
        "url": "/services/data/v50.0/sobjects/TenantSecret/02G...........W",
        "type": "TenantSecret"
      },
      "Id": "02G...........W",
      "Status": "ARCHIVED"
    },
    {
      "Version": 2,
      "Id": "02G..........O",
      "attributes": {
        "type": "TenantSecret",
        "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O"
      },
      "Status": "ARCHIVED"
    },
    {
      "Id": "02G...........4",
      "attributes": {
        "url": "/services/data/v50.0/sobjects/TenantSecret/02G...........4",
        "type": "TenantSecret"
      },
      "Version": 4,
      "Status": "DESTROYED"
    },
    {
      "attributes": {
        "type": "TenantSecret",
        "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O"
      },
      "Id": "02G..........O",
      "Version": 5,
      "Status": "ACTIVE"
    }
  ]
}

Query1.png
Figure 23: Query Operation Query2.png
Figure 24: Query Operation Key Management

Upload Operation

This operation allows you to create a key material in Fortanix DSM and upload to Salesforce.

Parameters:

    • operation: The operation which you want to perform. A valid value is upload.
    • secret_id: The response of configuration operation.
    • wrapper: Name of the wrapping certificate in Salesforce.
    • type: A valid value is Data|EventBus|SearchIndex.
    • mode: Key derivation mode. It can be blank which defaults to “PBKDF2” or can also be "NONE" to disable key derivation in Salesforce.
    • name: Prefix of the name.
    • sandbox: To indicate, whether to use test or production tenant.

Example:

Input JSON

{
  "operation": "upload",
  "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "wrapper"  : "SFBYOK_FTX_Wrapper",
  "type"     : "Data",
  "mode"     :  "",
  "name"     : "Salesforce Data Key",
  "sandbox"  : false
}

Output JSON

{
  "obj_type": "AES",
  "custom_metadata": {
    "SF_HASH": "ESP.......................=",
    "SF_UPLOAD": "EDF.....................=",
    "SF_WRAPPER": "SFBYOK_FTX_Wrapper",
    "SF_MODE": "",
    "SF_KID": "02G...........O",
    "SF_TYPE": "Data"
  },
  "acct_id": "ec9...................7",
  "creator": {
    "plugin": "654....................1"
  },
  "public_only": false,
  "origin": "Transient",
  "kid": "bb7................3",
  "lastused_at": "19700101T000000Z",
  "activation_date": "20201229T185549Z",
  "key_size": 256,
  "kcv": "b5...9",
  "name": "Salesforce Data Key 20201229T185546Z",
  "state": "Active",
  "enabled": true,
  "key_ops": [
    "EXPORT"
  ],
  "compliant_with_policies": true,
  "created_at": "20201229T185549Z",
  "aes": {
    "tag_length": null,
    "key_sizes": null,
    "random_iv": null,
    "fpe": null,
    "iv_length": null,
    "cipher_mode": null
  },
  "never_exportable": false,
  "group_id": "ff2..............b"
}

upload1.png
Figure 25: Upload Operation upload2.png
Figure 26: Upload Operation Key Management

Status Operation

This operation allows you to obtain current status of a Salesforce key.

Parameters:

    • operation: The operation which you want to perform. A valid value is status.
    • secret_id: The response of configuration operation.
    • wrapper: Name of the wrapping certificate in Salesforce.
    • name: "name of corresponding sobject in Fortanix DSM".
    • sandbox: To indicate, whether to use test or production tenant.

Example:

Input JSON

{
      "operation" : "status",
      "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wrapper"   : "SFBYOK_FTX_Wrapper",
      "name"      : "Salesforce Data Key 20201229T185546Z",
      "sandbox"   : false
}

Output JSON

{
  "RemoteKeyIdentifier": null,
  "CreatedDate": "2020-12-29T18:55:49.000+0000",
  "SecretValueHash": "ESP........................=",
  "CreatedById": "005..........2",
  "KeyDerivationMode": "PBKDF2",
  "attributes": {
    "url": "/services/data/v50.0/sobjects/TenantSecret/02G..........O",
    "type": "TenantSecret"
  },
  "LastModifiedDate": "2020-12-29T18:55:49.000+0000",
  "IsDeleted": false,
  "SecretValue": "CgM.............................=",
  "SecretValueCertificate": null,
  "Type": "Data",
  "RemoteKeyServiceId": null,
  "Version": 6,
  "Id": "02G..........O",
  "Status": "ACTIVE",
  "SystemModstamp": "2020-12-29T18:55:49.000+0000",
  "RemoteKeyCertificate": null,
  "Source": "UPLOADED",
  "Description": "Salesforce Data Key 20201229T185546Z",
  "LastModifiedById": "005............2"
}

status.png
Figure 27: Status Operation

Sync Operation

This operation allows you to sync Fortanix DSM key object with Salesforce key.

Parameters:

    • operation: The operation which you want to perform. A valid value is sync.
    • secret_id: The response of configuration operation.
    • wrapper: Name of the wrapping certificate in Salesforce.
    • name: "name of corresponding sobject in Fortanix DSM".
    • sandbox: To indicate, whether to use test or production tenant.

Example

Input JSON

{
      "operation" : "sync",
      "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wrapper"   : "SFBYOK_FTX_Wrapper",
      "name"      : "Salesforce Data Key 20201229T185546Z",
      "sandbox"   : false
}

Output JSON

{
  "RemoteKeyCertificate": null,
  "IsDeleted": false,
  "CreatedById": "005..............2",
  "Status": "ACTIVE",
  "Type": "Data",
  "LastModifiedById": "005............2",
  "CreatedDate": "2020-12-29T18:55:49.000+0000",
  "SystemModstamp": "2020-12-29T18:55:49.000+0000",
  "Source": "UPLOADED",
  "SecretValueHash": "ESP.................c",
  "LastModifiedDate": "2020-12-29T18:55:49.000+0000",
  "Version": 6,
  "RemoteKeyServiceId": null,
  "RemoteKeyIdentifier": null,
  "attributes": {
    "type": "TenantSecret",
    "url": "/services/data/v50.0/sobjects/TenantSecret/02G............O"
  },
  "KeyDerivationMode": "PBKDF2",
  "Id": "02G...........O",
  "SecretValueCertificate": null,
  "Description": "Salesforce Data Key 20201229T185546Z",
  "SecretValue": "CgM........................M"
}

Destroy Operation

This operation allows you to destroy an archived Salesforce key.

Parameters:

    • operation: The operation which you want to perform. A valid value is destroy.
    • secret_id: The response of configuration operation.
    • wrapper: Name of the wrapping certificate in Salesforce.
    • name: "name of corresponding sobject in Fortanix DSM".
    • sandbox: To indicate, whether to use test or production tenant..

Example

Input JSON

{
      "operation" : "destroy",
      "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wrapper"   : "SFBYOK_FTX_Wrapper",
      "name"      : "Salesforce Data Key 20201229T185546Z",
      "sandbox"   : false
}

Output JSON

output is empty, with http status indicating success.

destroy1.png
Figure 28: Destroy Operation destroy2.png
Figure 29: Destroy Operation Key Management

Restore Operation

This operation allows you to restore a destroyed Salesforce key.

Parameters:

    • operation: The operation which you want to perform. A valid value is restore.
    • secret_id: The response of configuration operation.
    • wrapper: Name of the wrapping certificate in Salesforce.
    • name: "name of corresponding sobject in Fortanix DSM".
    • sandbox: To indicate, whether to use test or production tenant.

Example:

Input JSON

sudo apt install docker.io
{
      "operation" : "restore",
      "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wrapper"   : "SFBYOK_FTX_Wrapper",
      "name"      : "Salesforce Data Key 20201229T185546Z",
      "sandbox"   : false
}

Output JSON

output is empty, with http status indicating success.

restore1.png
Figure 30: Restore Operation restore2.png
Figure 31: Restore Operation Key Management

 

 

 

 

Comments

Please sign in to leave a comment.

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