Install Securosys Middleware for Salesforce Cache-Only Keys

Obtain Salesforce BYOK Certificate

Before installing the Securosys Middleware it's important to obtain a Salesforce BYOK-compatible certificate. This will enable you to encrypt your data in Salesforce with Cache-only Key Service, using Salesforce to generate a 4096-bit RSA self-signed certificate.

Each BYOK-compatible certificate’s private key is encrypted with a derived, org-specific tenant secret key. This tenant secret key will be generated within the Securosys HSM and wrapped by the Salesforce BYOK-compatible certificate’s public key.

You can also generate a certificate-authority (CA) signed certificate. See Generate a Certificate Signed by a Certificate Authority for more information. To ensure that your certificate is BYOK-compatible, remember to manually change the Exportable Private Key, Key Size, and Platform Encryption settings.

info

If you’re not sure whether a self-signed or CA-signed certificate is right for you, consult your organization’s security policy. For more information about what each option implies, see Certificates and Keys in Salesforce Help.

To create a self-signed certificate follow the next steps:

1. From Setup, in the Quick Find box, enter Platform Encryption, and then select Key Management.
2. Click Bring Your Own Key.
3. Click Create Self-Signed Certificate.
4. Enter a unique name for your certificate in the Label field. The Unique Name field automatically assigns a name based on what you enter in the Label field.
   • The Exportable Private Key (1), Key Size (2), and Use Platform Encryption (3) settings are preset. (For a BYOK certificate, you must select 4096 for the key size). These settings ensure that your self-signed certificate is compatible with Salesforce Shield Platform Encryption.
   • Example:
5. When the Certificate and Key Detail page appears, click Download Certificate. The certificate will be downloaded as a .crt file.

Configure Securosys Middleware

Define Docker Compose

In this guide, we will use Docker Compose to define and run the containers. You can also use another container runtime, such as Kubernetes.

Edit the file docker-compose.yml contained within the downloaded Middleware .zip file.

services:

  #Database Service
  salesforce_sql:
    image: mariadb:11.8
    container_name: salesforce_sql
    ports:
      - "3306:3306"
    volumes:
      - ./salesforce_sql/mysql-lib:/var/lib/mysql
    environment:
      - MYSQL_USER=replaceme # REPLACE with your credentials
      - MYSQL_PASSWORD=replaceme # REPLACE with your credentials
      - MYSQL_DATABASE=replaceme
      - MYSQL_ROOT_PASSWORD=replaceme
    restart: unless-stopped

  securosys_salesforce:
    image: securosys.jfrog.io/salesforce-cache-only-keys/securosys-salesforce-cache-only-keys:latest
    container_name: securosys_salesforce
    restart: unless-stopped
    depends_on:
      - salesforce_sql
    ports:
      #make sure port 8080 is not in use. `8081:8080` exposes api on port 8081
      - "8080:8080"
    volumes:
      # place for application configuration files
      - ./config-files:/etc/app/config
      # output folder of e.g. logfiles
      - ./output:/etc/app/output
    environment:
      - logging.config=/etc/app/config/log/logback.xml

Define Application Config

Before installing the Securosys Middleware, make sure to configure it to connect to either your on-premise Primus HSM or CloudHSM Partition.

Edit the application.yml file, contained within the downloaded Middleware .zip file. This file defines the configuration options the Securosys Middleware will use. It tells the Middleware which database it should use, where it can reach the HSM, and how it should authenticate against APIs of the HSM and which Salesforce BYOK-compatible certificate to use.

Example configuration:

##DATABASE-CONNECTION CONFIGURATION
spring:
  datasource:
    url: jdbc:mariadb://localhost:3306/securosys?allowPublicKeyRetrieval=true&sslMode=false # jdbc:mysql://<host_or_ip>:3306/securosys?useSSL=true
    username: replace-me_db-username # REPLACE according to the `MYSQL_USER` in the docker-compose.yml file
    password: replace-me_db-password # REPLACE according to the `MYSQL_PASSWORD` in the docker-compose.yml file

##HSM CONFIGURATION
hsm:
  # Make sure you allowed an outbound firewall rule, to allow traffic to the HSM
  # Hosts should be entered sequentially using the list as in the example below
  #First time you log in, the host and port are randomly selected. In case of an error, successive host and port combinations are checked.
  host:
    - ''
  #Ports should be entered sequentially using the list just like hosts
  port:
    - ''
  user: ''
  #This password will only be used once on an OTP basis
  setupPassword: 'replace-me_hsm-setupPassword'
  #Used for CloudsHSM access
  proxyUser: 'replace-me_proxy-username'
  #Used for CloudsHSM access
  proxyPassword: 'replace-me_proxy-password'

##Salesforce Cache-Only Keys Service Configuration
salesforce:
  byokCertificate: 'file:/etc/app/config/salesforce_byok.crt'

HSM Configuration Parameter	Description
host	Specify the DNS or IP of the HSM or CloudHSM. See Connectivity Details for more information. Multiple hosts can be specified sequentially in their own lines to allow for multiple connections (HA cluster environments).
port	Specify the JCE port of the HSM or CloudHSM. See Connectivity Details for more information.
user	Specify the Partition where the keys are and will be stored.
setupPassword	Specify the setup password to establish the initial connection between the Middleware and the HSM. When successful a permanent secret will be fetched, and the setup password will expire in the set amount of time.
proxyUser	Specify your proxy username, applicable to CloudHSM.
proxyPassword	Specify your proxy password, applicable to CloudHSM.
byokCertificate	Specify the path to your downloaded Salesforce BYOK-compatible certificate.

Logging

The Securosys Middleware collects logs to assist with troubleshooting. These logs can additionally be configured to log remotely to a syslog server, Splunk App or to a TCP socket.

Edit the logback.xml file with your parameters if remote logging is desired.

Deploy Securosys Middleware

Finally, start the container:

docker compose up --detach