Introduction

When a CAST application analysis/snapshot is actioned, part of that process is to store the analyzed source code in the application schemas so that client applications such as Imaging, Console and the Dashboards can display that source code. Source code is stored by default in the application schemas in unencrypted format, however, if your environment requires that this source code is stored in encrypted format (due to security or privacy concerns) then it is possible to configure this. Some things to note about this:

• the encryption mechanism uses the PostgreSQL encryption module called pgcrypto: https://www.postgresql.org/docs/current/pgcrypto.html. This module must be installed on all CAST Storage Service/PostgreSQL hosts where encrypted source code needs to be stored.
• the encryption currently functions at CAST Storage Service/PostgreSQL host level i.e. if the option is enabled for a particular CAST Storage Service/PostgreSQL host, all application schemas installed on that host will store source code in encrypted format.
• the encryption of source code is only actioned during the insert into the CAST application schemas on the CAST Storage Service/PostgreSQL instance, therefore it is always transmitted in unencrypted format over the local network, both from and to the CAST Storage Service/PostgreSQL instance (i.e. from Node to CAST Storage Service/PostgreSQL host and when source code is requested by other applications such as Console (Architecture Studio), CAST Imaging and CAST Dashboards).
• when source code encryption is enabled, performance will be impacted in both directions , i.e. source code upload by the Node to the CAST Storage Service/PostgreSQL host and reading and decryption of source code from the CAST Storage Service/PostgreSQL host by client applications such as Imaging, Console and the Dashboards.
• the size of encrypted source code stored in the CAST application schemas will be larger than unencrypted source code.
• there is no end user tool to manage this: if an encryption key needs to be changed (for example) then all source code has to be re-uploaded via a new analysis, or if existing source code needs to be newly encrypted, it will need uploading again via a new analysis.

Compatibility matrix

Support for encrypting/unencrypting source code is available in the following releases:

Configuration process

Install the pgcrypto module

The first step is to install the pgcrypto module on all CAST Storage Service/PostgreSQL instances on which you want to store encrypted source code. To do so, run the following query using pgAdmin (for example) on each CAST Storage Service/PostgreSQL instance - this query will install the module in the "public" schema:

set search_path=public
CREATE EXTENSION IF NOT EXISTS pgcrypto;

Configure AIP Core (Node) to upload source code in encrypted format

To force an AIP Core (Node) to function in encrypted source code mode, the following is required:

• an .ini file needs to be created and then configured on all AIP Core instances (Nodes)
• 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)

Create and configure an .ini file for all AIP Core (Node) instances

Nodes are configured to look for an .ini file via an environment variable that is defined on the host server. This .ini file allows you to configure encrypted source code mode for multiple CAST Storage Services/PostgreSQL instances and determine the encryption key. You can store the .ini file:

• on the server's local file system - in this situation, all Nodes hosting CAST applications that must store source code in encrypted source code format and all client applications that must decrypt encrypted source code must have the same copy of the .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 .ini file is stored on a shared network drive that is accessible from all Nodes that must store source code in encrypted format and all client applications that must decrypt encrypted source code. The advantage of this is that there is only one copy of the .ini file and the configuration is valid for all servers.

The .ini file can use any name (e.g. myfile.ini), however, an existing feature to enable the use of an SSL encrypted connection between CAST applications and CAST Storage Service/PostgreSQL also uses an .ini file in exactly the same way, therefore you may already have an .ini file available if you have enabled SSL connections for your CAST Storage Service/PostgreSQL instance - see SSL encrypted mode configuration for CAST Storage Service and PostgreSQL. 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 to define which CAST Storage Service/PostgreSQL instance should store source code in encrypted format and define the encryption key:

[host:port,database]
encryption_key_default=MYKEY

For example:

[my_css1:2284,postgres]
encryption_key_default=#J3citp#FNYF*qa7c&Ps

[my_css1:2284,postgres]
encryption_key_default=#J3citp#FNYF*qa7c&Ps

[my_css2:5432,postgres]
encryption_key_default=AFK%3JdMEn99WypMVSCU

[my_css1:2284,postgres]
encryption_key_default=#J3citp#FNYF*qa7c&Ps

[my_css2:5432,postgres]
encryption_key_default=AFK%3JdMEn99WypMVSCU

[my_css2:5432,mydb]
encryption_key_default=Dk#QD8@7*YwUbxC4tAt%jQ

[my_css1:2284,postgres]
encryption_key_default=#J3citp#FNYF*qa7c&Ps

[my_css2:5432,postgres]
encryption_key_default=AFK%3JdMEn99WypMVSCU

[my_css2:5432]
ssl=truesslmode=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

Create environment variable on all AIP Core (Node) instances

Create a Windows environment variable (System or User according to your own requirements) on all AIP Core (Node) instances. Use the following syntax:

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

Restart the Node

To ensure that the new environment variable is taken into account, restart the host server on which your Nodes are installed.

Configure CAST applications to read encrypted source code

All CAST applications (CAST Console, CAST Imaging, CAST Dashboards etc.) that need to read source code from a CAST Storage Service/PostgreSQL instance that has been encrypted need to have access to the encryption key defined on the host AIP Core instance (Node) so that the encrypted source code can be unencrypted. Instructions for each application are given below. CAST highly recommends restarting all servers following the addition of the required information.

Configure an .ini file

All host servers on which your CAST client applications are running need to have access to an .ini file that defines the CAST Storage Service/PostgreSQL instances which host the encrypted source code and the unique encryption key for unencrypting the source code when it is read by the CAST client application. This .ini will have the exact same content as the .ini file defined in Create and configure an .ini file on all AIP Core (Node) instances above. Therefore:

• If you stored the .ini file for your AIP Core instances (Node) - see Create and configure an .ini file on all AIP Core (Node) instances above - on a shared network resource that the CAST client application host servers have 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 client application - this .ini file should contain a reference to all CAST Storage Service/PostgreSQL instances containing encrypted source code and the same encryption key used to encrypt the source code on the AIP Core instance (Node) - i.e. use the same content/syntax as described above in Create and configure an .ini file on all AIP Core (Node) instances. 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.

Tell the CAST applications where the .ini file is located

On all servers hosting CAST client applications that must read encrypted source code, you must ensure that the location of the .ini file is defined. This can be done in two different ways:

• Via an environment variable
• Via a properties file (this method is specific to CAST Console and CAST Imaging only - other CAST applications must use an environment variable) 

Via an environment variable

Add an environment variable called CASTCONNECTIONEXTRAPARAMETERS that points to the .ini file created previously. Use the following syntax:

Via a properties file

An alternative to creating an environment variable is to define an entry in a properties file that specifies where the .ini file is located. The properties files in question are:

CAST Console - Node
Console Enterprise edition: %PROGRAMDATA%\CAST\AIP-Node\application.yml
Console Standalone edition: %PROGRAMDATA%\CAST\AIP-Console-Standalone\application-standalone.yml

CAST Imaging
Traditional Windows installer: %APPDATA%\CAST\ImagingSystem\sourcecode\application.properties
Docker Installer (located in the unzipped extension folder): server\sourcecode\application.properties or sourcecode\application.properties

Add the following lines into the relevant file if they do not already exist and include the path to the .ini file, for example:

CAST Console - Nodedatasource:
	encryptionini: "\\server\share\myfile.ini"

CAST Imaging
datasource.encryptionini=\\server\share\myfile.ini

CAST Imaging,, CAST Console and and CAST Storage Service/PostgreSQL - match the details in the .ini file

You should ensure that the configuration of your CAST Storage Service/PostgreSQL instances in CAST Imaging and CAST Console matches what you have defined in the .ini file. For example, if you have defined an entry in the .ini file to store encrypted source code for the server named "my_css_server", then you should also ensure that "my_css_server" is correctly defined in CAST Imaging and CAST Console:

Restart the host servers

To ensure that the new environment variable is taken into account, restart the host servers on which your CAST client applications are installed.