Step 3 - Configure CAST components to function in encrypted mode

Overview

To force CAST Imaging components (analysis-node, imaging-services, imaging-viewer and dashboards) to connect to CAST Storage Service/PostgreSQL instance(s) in encrypted mode, the components need to know the target instance and where the relevant client certificates and keys are located. This is achieved using:

an .ini file which contains the required information about the CAST Storage Service/PostgreSQL instance(s) and the client keys and certificates that will secure the connection
an environment variable (available on all machines that require access to encrypted database instances) which is used to define the location of the .ini file

Deal with client keys and certificates

Find the client keys and certificates generated in Step 1 - Generate certificates and keys on each machine:

client.key - client private key file
client.crt - client certificate file
client.pk8 - client certificate file using pk8 for JDBC connections
client.pem.pk8 - client certificate file using pk8 for JDBC connections
client.pfx - client certificate file using pkcs12 for .NET connections
root.crt - trusted root certificate will be used to verify that the client can trust the certificate presented by the server

Copy these files to a folder on the local file system, for example:

# Microsoft Windows:
C:\CAST\ssl

# Linux:
/etc/ssl/certs

Create and configure the .ini file

You can store the .ini file:

on the local file system of each machine where a CAST Imaging component has been installed. In this situation, if you need to make an update to the .ini file, you will need to make the update on all servers where the file exists.
on a shared network drive - in this situation, the .ini file is stored on a shared network drive that is accessible from all machines hosting a CAST component that must use encrypted mode to connect to a CAST Storage Service/PostgreSQL instance. The advantage of this is that there is only one copy of the .ini file and the configuration is valid for all machines.

The .ini file can use any name (e.g. myfile.ini), and must contain the following syntax:

[host:port,database]
ssl=true|false
sslmode=require|verify-ca|verify-full|disable
sslrootcert=/path/to/root.crt
ssljdbckey=/path/to/client.pk8|/path/to/client.pem.pk8
sslkey=/path/to/client.key
sslcert=/path/to/client.crt 
sslpfx=/path/to/client.pfx

Entry	Description
`[host:port,database]`	Refers to the target CAST Storage Service/PostgreSQL instance. For example: `postgresql.corp.domain.com:2284` `192.168.20.52:2284` `mypostgres:5432` Notes: You can add as many `[host:port,database]` sections as you require. `host` should be entered in lowercase CAST recommends that you avoid using “localhost” even if the target CAST Storage Service/PostgreSQL is located on the same machine as the CAST component.
`ssl=true\|false`	Defines whether the connection to the target instance specified in [host:port,database] must use encrypted mode (true) or not (false).
`sslmode=require\|verify-ca\|verify-full\|disable`	More details about this setting can be found in https://www.postgresql.org/docs/13/libpq-ssl.html . This variable will match the PostgreSQL parameter `PGSSLMODE`.
`sslrootcert=`	The full path to `root.crt` file on the local file system. This variable will match the PostgreSQL SSL parameter `PGSSLROOTCERT`.
`sslkey=`	The full path to `client.key` file on the local file system. This variable will match the PostgreSQL SSL parameter `PGSSLKEY`.
`sslcert=`	The full path to `client.crt` file on the local file system. This variable will match the PostgreSQL SSL parameter `PGSSLCERT`.
`ssljdbckey=`	Full path to `client.pk8` or `client.pem.pk8` file on the local file system for JDBC connections.
`sslpfx=`	Full path to `client.pfx` file on the local file system for .NET connections.

Examples

Two CAST Storage Service/PostgreSQL instances:

[my_pg1.corp.domain.com:2284]
ssl=true
sslmode=require
sslrootcert=/etc/ssl/certs/root.crt
ssljdbckey=/etc/ssl/certs/client.pk8
sslkey=/etc/ssl/certs/client.key
sslcert=/etc/ssl/certs/client.crt
sslpfx=/etc/ssl/certs/client.pfx

[my_pg2.corp.domain.com:5432]
ssl=true
sslmode=verify-ca
sslrootcert=/etc/ssl/certs/root.crt
ssljdbckey=/etc/ssl/certs/client.pk8
sslkey=/etc/ssl/certs/client.key
sslcert=/etc/ssl/certs/client.crt
sslpfx=/etc/ssl/certs/client.pfx

Create environment variable on each machine hosting a CAST component

On each machine hosting a CAST Imaging component that requires access to encrypted database instances, define an environment variable. This is used to define the location of the .ini file created in the previous action.

Microsoft Windows

Create a Microsoft Windows environment variable (System or User according to your own requirements) with the following syntax:

Variable Name - CASTCONNECTIONEXTRAPARAMETERS
Variable Value - location of the .ini file, for example: <FULLPATH>\myfile.ini

Linux via Docker

In a Linux via Docker installation, the .ini file must be accessible within the required Docker containers. To achieve this, a docker-compose.override.yml is created for each component containing configuration to mount the location containing the .ini file (either a local folder on the machine or a mounted network share) and the environment variable CASTCONNECTIONEXTRAPARAMETERS.

Create docker-compose.override.yml

First create a file called docker-compose.override.yml containing the following information:

services:
  nodev3:
    volumes:
      - path/to/local/ssl/folder:/app/ssl
    environment:
      - CASTCONNECTIONEXTRAPARAMETERS=/app/ssl/myfile.ini

Where:

volumes: mounts a file system folder containing the .ini file to a specific location within the Docker container. Paths are all examples. If the defined file system folder is already mounted to a network share, then you can take advantage of having only one copy of the .ini in your network.
CASTCONNECTIONEXTRAPARAMETERS: an environment variable pointing to the .ini file within the Docker container. Paths/filenames are all examples.

Copy docker-compose.override.yml for analysis-node components

Copy the docker-compose.override.yml to the CAST Imaging installation location on the machine(s) hosting the analysis-node component(s):

cp docker-compose.override.yml /opt/cast/installation/imaging-node

If you already have a docker-compose.override.yml in this location, you will need to add the configuration listed above to the existing file.

Clone docker-compose.override.yml and tailor for other components

Now clone the docker-compose.override.yml three times, and edit each one, tailoring it to the target component:

For imaging-services change nodev3 to control-panel
For dashboards change nodev3 to dashboards
For imaging-viewer change nodev3 to etl

Copy each cloned and tailored file to the relevant installation folder on the machines hosting each component:

For imaging-services:

cp docker-compose.override.yml /opt/cast/installation/imaging-services

For dashboards:

cp docker-compose.override.yml /opt/cast/installation/imaging-dashboards

For imaging-viewer:

cp docker-compose.override.yml /opt/cast/installation/imaging-viewer

Restart services

To ensure that all changes are taken into account, restart all impacted services:

Microsoft Windows

Restart all CAST Imaging Microsoft Windows Services as listed in Installation on Microsoft Windows.

Linux via Docker

Restart each component using:

docker compose down
docker compose up -d

E.g. from the following locations:

/opt/cast/installation/imaging-node
/opt/cast/installation/imaging-services
/opt/cast/installation/imaging-dashboards
/opt/cast/installation/imaging-viewer

What’s next?

See Step 4 - Declare the CAST Storage Service/PostgreSQL.