Introduction

Out of the box, both CAST Storage Service and PostgreSQL are not preconfigured to function in SSL encrypted mode, i.e. to accept incoming encrypted database connections for enhanced security. However, SSL encrypted mode can be configured if required. The configuration process involves specific steps described in this document:

• Generate SSL certificates/keys
• Configure CAST Storage Service/PostgreSQL to accept incoming SSL connections
• Configure CAST AIP core and related applications to function in SSL mode
• Configure CAST AIP Console/AIP Node to function in SSL mode
• Configure standalone CAST Dashboards to function in SSL mode

Which CAST applications can currently connect in SSL mode?

Configuration process

Generate SSL certificates/keys

The first step is to generate the SSL certificates/keys that are required by both the CAST Storage Service/PostgreSQL instance and CAST applications.

Install OpenSSL

To generate the required SSL certificates, OpenSSL must be installed on the server hosting your CAST Storage Service/PostgreSQL instance.

OpenSSL installation on Windows

• Download and install OpenSSL from http://gnuwin32.sourceforge.net/packages/openssl.htm (note that this will install an older release - 0.9.8).
• Create a System and User Environmental variable as follows:
  • Variable Name - OPENSSL_CONF
  • Variable Value - location of the openssl.cnf file, for example: %PROGRAMFILES%\GnuWin32\share\openssl.cnf

OpenSSL installation on Linux

OpenSSL may be preinstalled on your chosen Linux distribution. To check, run the following command:

openssl version

If OpenSSL is not installed, follow the appropriate installation instructions. For example:

Debian based: apt-get install openssl
RedHat/CentOS based: yum install openssl

Certificate/key generation

Create a root key and certificate for the server hosting CAST Storage Service/PostgreSQL (root.crt, root.key) - ensure you change any settings, in particular the -subj option to suit your own environment:

openssl genrsa -des3 -out root.key 1024 
openssl rsa -in root.key -out root.key 
openssl req -new -key root.key -days 365 -out root.crt -x509 "/CN=root.yourdomain.com"

Create a server key and certificate for the server hosting CAST Storage Service/PostgreSQL (server.crt, server.key) - ensure you change any settings, in particular the -subj option to suit your own environment:

openssl genrsa -des3 -out server.key 1024 
openssl rsa -in server.key -out server.key 
openssl req -new -key server.key -out server.csr -subj "/CN=server.hostname" 
openssl x509 -req -in server.csr -CA root.crt -CAkey root.key -days 365 -out server.crt -CAcreateserial  

Create the client certificates/keys to be used with CAST applications (postgresql.crt, postgresql.key, postgresql.pk8, postgresql.pfx) - ensure you change any settings, in particular the -subj option to suit your own environment:

openssl genrsa -des3 -out postgresql.key 1024
openssl rsa -in postgresql.key -out postgresql.key
openssl req -new -key postgresql.key -out postgresql.csr -subj "/CN=operator"
openssl x509 -req -in postgresql.csr -CA root.crt -days 365  -CAkey root.key -out postgresql.crt -CAcreateserial
openssl pkcs8 -topk8 -in postgresql.key -out postgresql.pk8 -outform der -nocrypt
openssl pkcs12 -export -out postgresql.pfx -inkey postgresql.key -in postgresql.crt -password pass: 

Finally, copy the following "server" certificates and keys to the folder in which your postgresql.conf file is located:

• root.crt
• server.key
• server.crt

The postgresql.conf file located is here:

Windows: %PROGRAMFILES%\CAST\CASTStorageService3\db_data

Linux: Run the following commands in psql on the host server to locate the postgresql.conf file:

psql -U postgres
show config_file;

Configure CAST Storage Service/PostgreSQL to accept incoming SSL connections

Edit postgresql.conf to enable SSL

Edit the postgresql.conf file located here:

Windows: %PROGRAMFILES%\CAST\CASTStorageService3\db_data

Linux: Run the following commands in psql on the host server to locate the postgresql.conf file:

psql -U postgres
show config_file;

Modify the file as follows and then save the file:

# - Security and Authentication -

ssl = on						# (change requires restart) 
ssl_cert_file = 'server.crt'	# (change requires restart) 
ssl_key_file = 'server.key'		# (change requires restart) 
ssl_ca_file = 'root.crt'		# (change requires restart)

Edit pg_hba.conf file to enable SSL

Edit the pg_hba.conf file located here:

Windows: %PROGRAMFILES%\CAST\CASTStorageService3\db_data

Linux: Run the following commands in psql on the host server to locate the postgresql.conf file:

psql -U postgres
show hba_file;

Modify the file as follows to allow IPv4 and IPv6 (where appropriate) connections using SSL by adding "hostssl" entries and an appropriate authentication METHOD (see https://www.postgresql.org/docs/9.6/auth-pg-hba-conf.html for more information about this):

# TYPE  DATABASE        	USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   	all             all                                     peer
# IPv4 local connections:
host    	all             all             127.0.0.1/32            md5
host    	all             all             0.0.0.0/0               md5
# Allow IPv4 loopback with SSL + password + a check on SSL cert
hostssl		all             all             127.0.0.1/32            md5 clientcert=1
# Allow any IPv4 with SSL + password + a check on SSL cert
hostssl		all				all		  		0.0.0.0/0               md5 clientcert=1
# IPv6 local connections:
host    	all             all             ::1/128                 md5
host    	all             all             ::0/0               	md5
# Allow IPv6 loopback with SSL + password + a check on SSL cert
hostssl     all             all             ::1/128                 md5 clientcert=1
# Allow any IPv6 with SSL + password + a check on SSL cert
hostssl     all             all             ::0/0                   md5 clientcert=1

Restart CAST Storage Service/PostgreSQL instance

Finally restart your CAST Storage Service or PostgreSQL instance to ensure the changes you have made are taken into account.

Configure applications to function in SSL mode

To force CAST AIP core and related applications/CAST Imaging to connect to CAST Storage Service or PostgreSQL in SSL mode, the following is required:

• an SSLParameters.ini file needs to be created and then configured on all AIP Core instances (AIP Nodes) / CAST Imaging instances
• a Windows environment variable (System or User according to your own requirements) needs to be created referencing the ini file on all AIP Core instances (AIP Nodes) / CAST Imaging instances
• configure the aip-node-app.properties on all AIP Core instances (AIP Nodes)

Create and configure SSLParameters.ini file on all AIP Core (AIP Node) instances / CAST Imaging instances

Supported CAST applications are configured to look for a file called SSLParameters.ini via an environment variable that is defined on the host server. This SSLParameter.ini file allows you to configure SSL mode for multiple CAST Storage Services/PostgreSQL instances and determine where the required client side certificates and keys are located.

You can store the SSLParameters.ini file:

• on the server's local file system - in this situation, all servers hosting CAST applications that must use SSL mode to connect to a CAST Storage Service/PostgreSQL instance must have a copy of the SSLParameters.ini file, therefore if you need to make an update to the file, you will need to make the update on all servers where the file exists.
• on a shared network drive - in this situation, the SSLParameters.ini file is stored on a shared network drive that is accessible from all servers hosting CAST applications that must use SSL mode to connect to a CAST Storage Service/PostgreSQL instance. The advantage of this is that there is only one copy of the SSLParameters.ini file and the configuration is valid for all servers

Create the SSLParameters.ini file using a text editor and use the following syntax:

[HOST:PORT]
ssl=true
sslmode=require
sslrootcert=root.crt
ssljdbckey=postgresql.pk8
sslkey=postgresql.key
sslcert=postgresql.crt 
sslpfx=postgresql.pfx

[HOST:PORT]
ssl=true
sslmode=require
sslrootcert=root.crt
ssljdbckey=postgresql.pk8
sslkey=postgresql.key
sslcert=postgresql.crt 
sslpfx=postgresql.pfx

Create environment variable on all AIP Core (AIP Node) instances / CAST Imaging instances

Create a Windows environment variable (System or User according to your own requirements) on each server hosting CAST applications that must use SSL mode to connect to a CAST Storage Service/PostgreSQL instance. Use the following syntax:

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

Configure AIP Node (for AIP Console) to function in SSL mode

If you are using AIP Console to manage the AIP Node, the following configuration must be performed on each AIP Node (i.e. a machine on which CAST AIP Core has been installed and is being managed in AIP Console) that must use an encrypted SSL connection to the target CAST Storage Service/PostgreSQL instance.

Edit the following file:

%PROGRAMDATA%\CAST\AipConsole\AipNode\aip-node-app.properties

Find the following section:

# =============================
# CSS Server parameters
# -----------------------------
database.server.name=my_css_server:2282
database.server.user=operator
database.server.ssl=
database.server.ssl.iniPath=
# to encrypt the password use aip-encryption-tool
database.server.password=CRYPTED2:90B1A6EC1618661401B724DB5AC34595
database.name=postgres

Update the database.server.ssl and database.server.ssl.iniPath parameters as follows:

# =============================
# CSS Server parameters
# -----------------------------
database.server.name=my_css_server:2282
database.server.user=operator
database.server.ssl=true
database.server.ssl.iniPath=<PATH_TO>/SSLParameters.ini
# to encrypt the password use aip-encryption-tool
database.server.password=CRYPTED2:90401B724DB5AC34595
database.name=postgres

Restart Microsoft Windows on all AIP Nodes / CAST Imaging instances

Finally restart Microsoft Windows on all AIP Nodes/ CAST Imaging instances so that all changes are taken into account.

Configure standalone CAST Dashboards to function in SSL mode

There are two ways to force the standalone CAST Dashboards to function in SSL mode:

• By modifying the URL that points to the CAST Storage Service/PostgreSQL instance (this method must be used for Dashboards deployed in Linux environments, but can also be used in Microsoft Windows environments)
• By using the SSLParameters.ini file and an environment variable (this method should be used for Dashboards deployed in Microsoft Windows environments)

Method 1: Modify the connection URL

Edit the following file:

WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties

ZIP ≥ 2.x
<unpacked_zip>\application.properties

Locate the following section in the file:

## DATASOURCE
# Resource1 is the datasource name used in domains.properties
# Adapt server name (localhost) and port (2282) if required
# You can add multiple datasources if you want to connect to multiple CSS Servers. Datasource name must be unique
# You have to configure your domains names and relative schema names in domains.properties
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

Modify the restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres line to point to the certificate files you generated previously:

restapi.datasource[0].url=jdbc:postgresql://my_server:2282/postgres?ssl=true&sslrootcert=\\\\my_host\\share\\root.crt&sslcert=\\\\my_host\\share\\postgresql.crt&sslkey=\\\\my_host\\share\\postgresql.pk8&sslmode=verify-ca

This is broken down as follows:

Finally restart the application server so that all changes are taken into account.

Method 2: Using the SSLParameters.ini file and an environment variable

• Create and configure SSLParameters.ini file on host server as described above.
• Create an environment variable on the host server as described above.
• Finally restart the application server so that all changes are taken into account.

Notes

Any custom scripts that you use to connect to your CAST Storage Service / PostgreSQL instance will need to be refactored to take advantage of the encrypted SSL connection should you wish to.