...

• 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

...

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 -subj "/CN=root.yourdomain.com"

...

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;

Anchor
accept accept

Configure CAST Storage Service/PostgreSQL to accept incoming SSL connections

Edit postgresql.conf to enable SSL

...

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)the Node to use SSL mode

Anchor
ini ini

Create and configure

...

the .ini file on all AIP Core (

...

Node) instances / CAST Imaging instances

Supported CAST applications are configured to look for a file called SSLParametersan .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 (recommended) - 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 SSLParametersThe .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

...

Refers to the target CAST Storage Service/PostgreSQL instance. For example:

• SERVER1:2282
• 192.168.20.52:2282
• SERVER2:5432

You can add as many HOST:PORT sections as you require.

...

Value should be one of the following:

• require
• verify-ca
• verify-full
• disable

More details about this is mentioned in https://www.postgresql.org/docs/13/libpq-ssl.html. This variable will match the PostgreSQL SSL parameter PGSSLMODE.

...

Refers to the location of the client certificates and keys generated previously with OpenSSL The certificates and keys need to be copied to the location you have chosen. The location of these certificates and keys is flexible:

• They can be stored on a shared network drive
• They can be stored on the server's local file system - in this situation, the certificates and keys need to be available on all server's that must use SSL mode

You can use the following path syntax:

• Local drive: D:\keys\postgresql.key
• Direct path: \\SERVER\certs\root.crt
• Mapped drive on server: S:\\certs\root.crt >>> Appropriate permissions required.

CAST highly recommends that you separate the storage and place the .crt files in one folder and all other keys (.pk8, .key, .pfx) in another folder - i.e. do not mix the two together.

...

can use any name (e.g. myfile.ini), however, a feature to enable the encryption of analyzed source code also uses an .ini file in exactly the same way, therefore you may already have an .ini file available if you have enabled this - see Storing analyzed source code in encrypted format. If this is the case, you can re-use this file and you can mix and match configuration from both features in this file.

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

[host:port,database]
ssl=true
sslmode=require
sslrootcert=root.crt
ssljdbckey=postgresql.pk8
sslkey=postgresql.key
sslcert=postgresql.crt 
sslpfx=postgresql.pfx

...

...

...

For example:

...

...

...

• 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:

...

ssl=true

...

sslrootcert=\\\\my_host\\share\\root.crt

...

sslcert=\\\\my_host\\share\\postgresql.crt

...

sslkey=\\\\my_host\\share\\postgresql.pk8

...

sslmode=verify-ca

...

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

...

[my_css1:2284,postgres]
ssl=true
sslmode=require
sslrootcert=C:\certs\root.crt
ssljdbckey=C:\certs\postgresql.pk8
sslkey=C:\certs\postgresql.key
sslcert=C:\certs\postgresql.crt
sslpfx=C:\certs\postgresql.pfx

[my_css1:2284,postgres]
ssl=true
sslmode=require
sslrootcert=C:\certs\root.crt
ssljdbckey=C:\certs\postgresql.pk8
sslkey=C:\certs\postgresql.key
sslcert=C:\certs\postgresql.crt
sslpfx=C:\certs\postgresql.pfx

[my_css2:5432,postgres]
ssl=true
sslmode=require
sslrootcert=C:\temp\certs\root.crt
ssljdbckey=C:\temp\postgresql.pk8
sslkey=C:\temp\postgresql.key
sslcert=C:\temp\postgresql.crt
sslpfx=C:\temp\postgresql.pfx

[my_css1:2284,postgres]
ssl=true
sslmode=require
sslrootcert=C:\certs\root.crt
ssljdbckey=C:\certs\postgresql.pk8
sslkey=C:\certs\postgresql.key
sslcert=C:\certs\postgresql.crt
sslpfx=C:\certs\postgresql.pfx

[my_css2:5432,postgres]
ssl=true
sslmode=require
sslrootcert=C:\temp\certs\root.crt
ssljdbckey=C:\temp\postgresql.pk8
sslkey=C:\temp\postgresql.key
sslcert=C:\temp\postgresql.crt
sslpfx=C:\temp\postgresql.pfx
encryption_key_default=AFK%3JdMEn99WypMVSCU

Anchor
env env

Create environment variable on all AIP Core (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

Image Added

Configure Node (for Console) to function in SSL mode

Console ≥ 2.x

Update the CAST Storage Service/PostgreSQL connection profile to use SSL mode (see Administration Center - Settings - CSS and Measurement settings):

Click to enlarge

Image Added

Console 1.x

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 Nodes / CAST Imaging instances

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

Configure standalone CAST Dashboards (≥ 2.x) to function in SSL mode

There are two ways to force the standalone CAST Dashboards to function in SSL mode. Both are valid for Dashboards deployed on Microsoft Windows and on Linux:

• By modifying the URL that points to the CAST Storage Service/PostgreSQL instance 
• By using the .ini file and an environment variable

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

JAR ≥ 2.x
%PROGRAMDATA%\CAST\Dashboards\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 .ini file and an environment variable

Configure an .ini file

All host servers on which your CAST Dashboards are running need to have access to an .ini file that defines the CAST Storage Service/PostgreSQL instances which must be accessed via SSL, along with the various required certificates:

• If you stored the .ini file for your AIP Core instance (Node) - see Create and configure the .ini file on all AIP Core (Node) instances / CAST Imaging instances above - on a shared network resource that the CAST Dashboard host server(s) has access to, you can simply re-use this .ini file by pointing the environment variable at this .ini file - CAST highly recommends this method
• Alternatively, you can create an .ini file on the local file system of the server(s) hosting the CAST Dashboards - this .ini file should contain a reference to all CAST Storage Service/PostgreSQL instances which must be accessed via SSL, along with the various required certificates - i.e. use the same syntax as described above in Create and configure the .ini file on all AIP Core (Node) instances / CAST Imaging instances above. The disadvantage of this option is that if you need to change an encryption key (for example), you will need to update multiple .ini files.

Create an environment variable on the host server

On all servers hosting Dashboards that must read encrypted source code, add an environment variable called CASTCONNECTIONEXTRAPARAMETERS that points to the .ini file created previously. Use the following syntax:

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.

Disabling SSL access

If you need to disable SSL access, use the following steps:

• The entry [host:port,database] and all sub-entries should be removed from SSLParameters.ini file (this file may be located in multiple locations if you are not storing it in a shared network location). Note that if you are using the related feature Storing analyzed source code in encrypted format, you should not remove the entire section, instead you should just remove the sub-entries starting with "ssl", for example:

Image Added

• Reverse the changes made to the postgresql.conf and pg_hba.conf files as detailed above in Configure CAST Storage Service/PostgreSQL to accept incoming SSL connections.
• Untick the Use SSL option in Console for all instances where SSL has been configured previously, see Administration Center - Settings - CSS and Measurement settings:

Image Added

• Restart the CAST Storage Service/PostgreSQL instance and all Nodes where SSL has been configured previously.