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

1.0 Introduction

The purpose of this article is to describe the steps required to export Fortanix-Data-Security-Manager (DSM) keys to Salesforce that support BYOK for server-side encryption. 

2.0 Prerequisites

The following are the prerequisites:

1. A Salesforce account with the following permissions:

   1. Certificate Management

   2. Encryption Key Management

   3. Customize Application

   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 following permissions and click SAVE.

      • Customize Application

      • Manage Encryption Keys

      • Manage Certificates

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

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

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

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

   11. Click Save.

2. The account does not require to be an administrator account. The credentials of this account will be used for plugin operations. Perform the following steps to create a permission set with the above-mentioned permissions and assign a user:

3. A Fortanix DSM account with appropriate permissions to create groups, apps, security objects, and plugins.

3.0 Fortanix Data Security Manager Setup

3.1 Download a Self-Signed Certificate from Salesforce

1. 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 the screenshot below.

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

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

   5. Select the key size as 4096. 

      

      Refer to the Salesforce documentation for more information on Certificate and Key Management.

   6. After the certificate is created, please download it.

      

      Download the certificate, and then save it to your desired location. You need to import this certificate when creating a Salesforce instance in Fortanix DSM in the next Section: Create a Salesforce Instance.

3.2 Create a Salesforce Instance 

In the Fortanix DSM, objects like - group, app, and BYOK plugins need to be created for integration. All this can be done in a step using the Salesforce instance.

1. Log in to Fortanix DSM UI https://amer.smartkey.io/ using valid credentials. This is applicable for the Fortanix DSM on-prem application.

2. Navigate to Integrations tab → Salesforce instance.

   

3. Click the ADD INSTANCE button.

   

4. On the Add Instance form page, enter the following:

   • Instance Name: Enter the unique name of the Salesforce instance. The Fortanix DSM will by default apply SF_ as a suffix to the entered name.

   • Client Certificate: Click the Upload Certificate button to upload the certificate that you downloaded from Salesforce in the previous Section: Download Self-Signed Certificate in Salesforce into Fortanix DSM as a Security-object.

5. Click the SAVE INSTANCE button to save the changes. With saving an instance a new group, an app, a plugin, and a security object are created within Fortanix DSM.

6. Go to the security object detailed and update the name of the security object to the same name as the certificate in Salesforce. This will be used as a wrapper for plugin operations.

   

3.3 Salesforce Wizard Instance Detailed View

In the instance detailed view page, the created instances are listed as shown below:

1. Add Instance: You can add more instances of Salesforce for different environment using Add Instance button.

2. Keys: You can manage the Salesforce key by using the MANAGE button. On the Salesforce Easy Wizard, you can see the detailed information of the key.

   

3. Instance status: To disable the instance created, click the toggle Disabled.

4. DELETE: To delete the instance created click the  button. Note that deleting an instance will delete the App, Group, and all security objects belonging to the instance and all key material will become inaccessible.

4.0 Salesforce Setup

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

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

4.1 Create Connected App in Salesforce

Create a Connected App under Apps → App Manager with the following values:

1. Name: Arbitrary Input

2. Select the checkbox for the following under the API (Enable OAuth Settings) section:

   1. Enable OAuth Settings for authentication.

   2. Enable Device Flow for automated access.

3. For the OAuth scope field, select the Full Access option or add all scopes.

4. On the Manage Connected Apps page, the Callback URL can be the default URL.

   

   

5. Click the Save button.

6. After creating the app, go to App Manager, select the app, and click View.

7. Under API (Enable OAuth Settings), click Manage Consumer Details and enter the verification code.

8. Save Consumer Key and Consumer Secret now for future operations.

   

9. Click the Manage tab in the app, and check the IP Relaxation Policy. By default, it is selected as Enforce IP Restriction. Hence, you must add the DSM IP to the trusted IP Range (as described in the next step). You can also choose to change the policy to Relax IP restrictions (preferable, during the testing phase).

   

10. Search for Network Access in the quick search and click New to add trusted IP ranges if you chose to Enforce IP Restriction above

    

11. Verify the following Salesforce credentials:

    • Client/Consumer Key (Created in section 4.1 step 8)

    • Client/Consumer Secret (Created in section 4.1 step 8)

    • OAuth username (Salesforce username)

    • OAuth password (Salesforce user password)

    • Tenant URI API version (Fortanix Plugin tested against version 50.0)     

5.0 Plugin Operations

5.1 Configure Operation

This operation configures the 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:

JSON Input:

{
  "operation": "configure",
  "consumer_key": "CBK...................D",
  "consumer_secret": "DMV................D",
  "username" : "ft......x@<your company domain>",
  "password" : "fy....K",
  "tenant"   : "<Salesforce tenant URI>",
  "version"  : "v57.0",
  "name"    : "<name of the security object you want to use a wrapper>"
}

JSON Output:

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

5.2 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

JSON Input: 

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

JSON Output: 

{
  "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
}

5.3 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

JSON Input:

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

{
  "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"
    }
  ]
}

5.4 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:

JSON Input:

{
  "operation": "upload",
  "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "wrapper"  : "<name of the security object you want to use a wrapper>",
  "type"     : "Data",
  "mode"     :  "",
  "name"     : "Salesforce Data Key",
  "sandbox"  : false
}

{
  "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"
}

5.5 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:

JSON Input:

{
      "operation" : "status",
      "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wrapper"   : "<name of the security object you want to use a wrapper>",
      "name"      : "Salesforce Data Key 20201229T185546Z",
      "sandbox"   : false
}

{
  "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"
}

5.6 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

JSON Input:

{
      "operation" : "sync",
      "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wrapper"   : "<name of the security object you want to use a wrapper>",
      "name"      : "Salesforce Data Key 20201229T185546Z",
      "sandbox"   : false
}

JSON Output:

{
  "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"
}

5.7 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

JSON Input:

{
      "operation" : "destroy",
      "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wrapper"   : "<name of the security object you want to use a wrapper>",
      "name"      : "Salesforce Data Key 20201229T185546Z",
      "sandbox"   : false
}

JSON Output:

output is empty, with http status indicating success.

5.8 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:

JSON Input:

sudo apt install docker.io

{
      "operation" : "restore",
      "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wrapper"   : "<name of the security object you want to use a wrapper>",
      "name"      : "Salesforce Data Key 20201229T185546Z",
      "sandbox"   : false
}

JSON Output:

output is empty, with http status indicating success.