Install the Cache-Only Key Proxy

In this step, you will install, configure, and deploy the Securosys Proxy for Salesforce Cache-Only Key Service.

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

Download

Download the .zip file with the release artifacts.

Define the Docker Compose

Edit the file docker-compose.yml to define two containers that will be launched: a database, and the proxy itself. A template for this file is included in the release artifacts.

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

Set the BYOK Certificate File

Place the Salesforce BYOK Certificate that you created in the previous step in the ./config-files directory, i.e. at path ./config-files/salesforce_byok.crt. This ensures that it will be correctly mounted, so that the proxy can read it.

Define the Application Config

Edit the application.yml file, which defines the configuration options the proxy will use. It tells the proxy 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 Certificate to use. A template for this file is included in the release artifacts.

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 proxy 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 Certificate.

Logging

The Cache-Only Key Proxy 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.

Configure TLS and Access Control

Since the proxy has access to your HSM partition, it is important to securely expose it over the internet and have access control in place. Even though the proxy can only return keys wrapped for the hard coded BYOK Certificate, TLS and access control are important security measures.

Currently, the Cache-Only Key Proxy does not natively offer TLS termination or access control (like Basic Auth or mTLS). Therefore, please deploy a reverse proxy in front of the Cache-Only Key Proxy, and configure the reverse proxy to handle TLS and access control.

See the Salesforce documentation for the list of access control mechanisms that Salesforce supports for calling out to your proxy.

Deploy the Proxy

Finally, start the container:

docker compose up --detach