Exporting Fortanix DSM Keys to Cloud Providers for BYOK - Salesforce

1.0 Introduction

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

2.0 Prerequisites

Ensure the following:

1. A Salesforce account with the following permissions:

   1. Certificate Management

   2. Encryption Key Management

   3. Customize Application

   The account does not need 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:

   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, 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. A Fortanix DSM account with appropriate permissions to create groups, applications (apps), security objects, and plugins.

3.0 Download a Self-Signed Certificate from 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 underSecurity→Certificate and Key Managementwith the settings 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. 

   

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

6. After the certificate is created, download it.

   

4.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:

4.1 Signing Up

4.2 Creating an Account

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

4.3 Creating a Salesforce Instance 

Perform the following steps to create an instance using the Salesforce wizard in Fortanix DSM SaaS:

1. Sign up at https://smartkey.io/ to access DSM SaaS for the AMER region. DSM SaaS supports multiple regions, as listed here.

2. In the DSM left navigation panel, click the Integrations menu item, and then select the Cloud Key Management/BYOK check box. Click ADD INSTANCE on the Salesforce tile.

   

3. On the Add Instance page:

   1. Title: Enter a name for your instance. The Fortanix DSM will, by default, apply SF_ as a suffix to the entered name.

   2. Client Certificate: Click UPLOAD CERTIFICATE to upload the certificate that you downloaded from Salesforce in Section 3.0: Download Self-Signed Certificate in Salesforce into Fortanix DSM as a security object.

4. Click SAVE INSTANCE.

   

   With the creation of an instance, a new group, an app, a plugin, and a security object are created within Fortanix DSM.

4.4 Salesforce Instance Detailed View

Navigate to the Integrations menu item → Salesforce wizard → Salesforce instances table. In the instance detailed view page, the following information is represented:

• API KEY: Click VIEW API KEY DETAILS to view the details of the API key, such as username and password.

• MANAGE KEYS: Click MANAGE to oversee the keys created.

• INSTANCE STATUS: To disable the created instance, toggle Disabled.

• DELETE: To delete the instance, click the overflow menu and select DELETE. Note that deleting an instance will result in the removal of the app, group, and all security objects associated with the instance, rendering all key material inaccessible.

4.5 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 4.3: Creating a Salesforce Instance 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.

5.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 suitable for all Salesforce Apps. For more information, refer here.

5.1 Create a Connected App in Salesforce

1. To create an External Client App, navigate to Apps → External Client Apps→ New External Client App.

2. Configure the app with the following settings:

   • Name: Enter a name for the app.

   • In the API (Enable OAuth Settings) section, select Enable OAuth Settings for authentication.

   • In the App Settings, set the Callback URL field to https://login.salesforce.com/services/oauth2/success .

   • In the OAuth scope field, select Manage user data via APIs.

   • In the Flow enablement field, select Enable Client Credentials flow.

3. Click Save to create the external client app.

4. Click Edit Policies:

   • In the OAuth Flows and External Client App Enhancements section, select Enable Client Credentials Flow. In the Run As (Username) field, specify the user.

   • In the App Authorization section, for the IP Relaxation field, select Relax IP restrictions from the drop down menu.

     

     If you selected Enforce IP Restriction, you must add the DSM IP to the trusted IP Range. Use quick search to find Network Access, and then click New to add trusted IP ranges.                

     

     

5. Click Save.

6. In the detailed view of the external client app, navigate to the Settings tab.

7. In the App Settings section, click Consumer Key and Secret to retrieve the consumer key and consumer secret.

   

8. Save the Consumer Key and Consumer Secret for future use.

   

9. Verify the following Salesforce credentials:

   • Client/Consumer Secret (Created in Step 7)

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

6.0 Plugin Operations

6.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: Specifies the operation that you want to perform. A valid value is configure.

• consumer_key: Specifies the consumer Key of the connected app.

• consumer_secret: Specifies the Consumer Secret of the connected app.

• tenant: Specifies the Salesforce tenant URI.

• version: Specifies the API version (Fortanix Plugin tested against version 57.0).

• name: Specifies the name of the security object. This security object 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",
  "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"on

6.2 Check Operation

This operation is to test whether the plugin can import a wrapping certificate from Salesforce into Fortanix DSM.

Parameters:

• operation: Specifies the operation that you want to perform. A valid value is check.

• secret_id: Specifies the  response of the configuration operation.

• wrapper: Specifies the name of the wrapping certificate in Salesforce.

Example

JSON Input: 

{
  "operation": "check",
  "secret_id": "3968218b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "wrapper"  : "<name of the security object you want to use a 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
}

6.3 Select Operation

This operation allows you to select a security object and fetch its details.

Parameters

• operation: Specifies the operation that you want to perform. A valid value is a query or search.

• secret_id: Specifies the response of the configuration operation.

• sobject: SQL query.

• tooling: Specifies an optional flag. If set to true, it allows querying against the Salesforce Tooling REST API.

• method: Specifies the method “GET|PUT|PATCH|DELETE”.

Example

JSON Input:

{
  "operation": "select",
  "secret_id": "2f9bb707-7897-4c1d-9293-5844712ee621",
  "sobject"  : "TenantSecret",
  "tooling"   : false,
  "method"    : "GET"
}

JSON Output:

{
  "recentItems": {},
  "objectDescribe": {
    "queryable": true,
    "mergeable": false,
    "hasSubtypes": false,
    "custom": false,
    "updateable": true,
    "replicateable": false,
    "mruEnabled": false,
    "labelPlural": "Tenant Secret",
    "deepCloneable": false,
    "feedEnabled": false,
    "activateable": false,
    "triggerable": false,
    "retrieveable": true,
    "urls": {
      "rowTemplate": "/services/data/v50.0/sobjects/TenantSecret/{ID}",
      "sobject": "/services/data/v50.0/sobjects/TenantSecret",
      "describe": "/services/data/v50.0/sobjects/TenantSecret/describe"
    },
    "undeletable": false,
    "keyPrefix": "02G",
    "layoutable": false,
    "name": "TenantSecret",
    "isSubtype": false,
    "isInterface": false,
    "deletable": false,
    "deprecatedAndHidden": false,
    "customSetting": false,
    "createable": true,
    "associateParentEntity": null,
    "associateEntityType": null,
    "searchable": false,
    "label": "Tenant Secret"
  }
}

6.4 Query Operation

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

Parameters

• operation: Specifies the operation that you want to perform. A valid value is a query or search.

• secret_id: Specifies the response of the configuration operation.

• query: SQL query.

  • It can be “select Id, Status, Version from TenantSecret” or

    “select Id, Status, Version from TenantSecret where Type = 'Data'” or

    “select Id, Status, Version from TenantSecret where Type = 'Data' and Status = 'ACTIVE'”

• tooling: Specifies an optional flag. If set to true, it allows querying against the Salesforce Tooling REST API.

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
}

JSON Output:

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

6.5 Upload Operation

This operation allows you to create a key material in Fortanix DSM and upload it to Salesforce. The response will contain the same name as given in the upload operation with the suffix as “YYYYmmDDTHHMMSSZ.

Parameters:

• operation: Specifies the operation that you want to perform. A valid value is query or search.

• secret_id: Specifies the response of the configuration operation.

• wrapper: Specifies the name of the wrapping certificate in Salesforce.

• type: Valid values are  Data|EventBus|SearchIndex|DeterministicData (Data can be used once per 24-hour period,EventBus can be used once per 168-hour period)

• mode: Key derivation mode. It can be blank, which defaults to “xBKxxx”, or can also be "NONE" to disable key derivation in Salesforce.

• name: Specifies the prefix of the namsame namee.

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

JSON Output:

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

6.6 Status Operation

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

Parameters:

• operation: Specifies the operation that you want to perform. A valid value is status.

• secret_id: Specifies the response of the configuration operation.

• wrapper: Specifies the name of the wrapping certificate in Salesforce.

• name: Specifies the name of the corresponding security object in Fortanix DSM.

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

JSON Output:

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

6.6 Sync Operation

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

Parameters:

• operation: Specifies the operation that you want to perform. A valid value is sync.

• secret_id: Specifies the response of the configuration operation.

• wrapper: Specifies the name of the wrapping certificate in Salesforce.

• name: Specifies the name of the the corresponding security object in Fortanix DSM.

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

6.8 Destroy Operation

This operation allows you to destroy an archived Salesforce key.

Parameters:

• operation: Specifies the operation that you want to perform. A valid value is destroy.

• secret_id: Specifies the response of the configuration operation.

• wrapper: Specifies the name of the wrapping certificate in Salesforce.

• name: Specifies the name of the corresponding security object in Fortanix DSM.

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.

6.9 Restore Operation

This operation allows you to restore a destroyed Salesforce key.

Parameters:

• operation: Specifies the operation that you want to perform. A valid value is restore.

• secret_id: Specifies the response of the configuration operation.

• wrapper: Specifies the name of the wrapping certificate in Salesforce.

• name: Specifies the name of the the corresponding security object in Fortanix DSM.

Example:

JSON Input:

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

JSON Output:

output is empty, with http status indicating success.