Step 1 - Generate certificates and keys
Overview
This initial step involves generating server and client certificates/keys to secure the CAST Storage Service/PostgreSQL instance and any machines connecting to it, known as “mutual TLS”.
- See the official PostgreSQL documentation for more information: https://www.postgresql.org/docs/current/ssl-tcp.html
- The instructions below describe the process of creating and using self-signed certificates. However, CAST highly recommends that you use certificates signed by a CA (Certificate Authority).
- OpenSSL (https://www.openssl.org/) is required to generate all key and certificate files: it is typically shipped as a base package on most Linux distributions, but is NOT shipped with Microsoft Windows, therefore if you are using CAST Storage Service installed on Microsoft Windows, you will need to obtain this tool first. If you have a recent release of
gitinstalled on the machine,openssl.exeis provided here:%PROGRAMFILES%\Git\usr\bin.
Generate server certificates and keys
Three files are required on the machine(s) hosting the CAST Storage Service/PostgreSQL instance(s) to secure the instance and incoming client connections:
server.key- server private key fileserver.crt- server certificate fileroot.crt- trusted root certificate that ensures clients present a signed certificate when they connect
You will need to create this set of files for all CAST Storage Service/PostgreSQL instance(s) you need to secure, i.e. running the commands on each machine.
Generate private key and CSR
To generate the private key (server.key) and a CSR (server.csr certificate signing request), run the following commands on the machine where the CAST Storage Service/PostgreSQL instance is installed, with elevated permissions (see also https://docs.openssl.org/1.1.1/man1/req/ ):
openssl req -new -text -nodes -subj '/CN=<FQDN>' -keyout server.key -out server.csr
Where:
req- indicates that we want to generate files-new- generates a brand new CSR-text- prints out the CSR in text form-nodes- no DES, meaning do not encrypt the private key in a PKCS#12 file-subj- defines the CN (Common Name) for the machine, i.e. the FQDN (Fully Qualified Domain Name), such aspostgresql.corp.domain.com-keyout- defines the name of the private key file-out- defines the name of the CSR file
Generate trusted “root” certificate
To generate a trusted “root” certificate, which will serve as both the server certificate (server.crt) and a CA certificate (root.crt), run the following command on the machine where the CAST Storage Service/PostgreSQL instance is installed, with elevated permissions (see also https://docs.openssl.org/1.1.1/man1/req/ ).
openssl req -x509 -text -in server.csr -key server.key -out root.crt
Where:
req- indicates that we want to generate filesx509- outputs a certificate instead of a certificate request-text- prints out the certificate in text form-in- specifies the input filename to read a request from - use theserver.csrgenerated with the previous command-key- provides the private key for signing a new certificate - use theserver.keygenerated with the previous command-out- specifies the output filenameroot.crtto write to
Clone “root.crt” certificate into “server.crt”
Since we are using self-signed certificates, you will use the root.crt as the trusted root certificate and clone it to produce the server certificate file server.crt. In a Linux environment this can be achieved using the following command:
cp root.crt server.crt
In a Microsoft Windows environment, use File Manager to clone root.crt.
Check output
At the end of the process you should have the following files available on the machine(s) hosting the CAST Storage Service/PostgreSQL instance:
root.crtserver.crtserver.csr(not needed going forward)server.key
Generate client certificates and keys
Various files are required for the client side machines, i.e. machines hosting any CAST Imaging component that can potentially interact with the CAST Storage Service/PostgreSQL instance to secure the instance itself:
client.key- client private key fileclient.crt- client certificate fileclient.pk8- client certificate file using pk8 for JDBC connectionsclient.pem.pk8- client certificate file using pk8 for JDBC connectionsclient.pfx- client certificate file using pkcs12 for .NET connectionsroot.crt- trusted root certificate will be used to verify that the client can trust the certificate presented by the server - this file was generated previously - copy it from the CAST Storage Service/PostgreSQL instance where it was generatedserver.key- server certificate file - this file was generated previously - copy it from the CAST Storage Service/PostgreSQL instance where it was generated
CAST highly recommends that you generate this set of required files on each machine where a CAST Imaging component is installed. For example:
- single machine installation: generate one set of keys/certificates on this single machine
- distributed/multiple machine installation: generate one set of keys/certificates on each machine. Remember that all CAST Imaging components can interact with a CAST Storage Service/PostgreSQL instance:
analysis-nodeimaging-servicesimaging-viewerdashboards
Run all of the following commands with elevated permissions (see also https://docs.openssl.org/1.1.1/man1/req/ ).
Generate private key and CSR
To generate the private key (client.key) and a CSR (client.csr certificate signing request), run:
openssl req -new -text -nodes -subj '/CN=<db_user>' -keyout client.key -out client.csr
Where:
req- indicates that we want to generate files-new- generates a brand new CSR-text- prints out the CSR in text form-nodes- no DES, meaning do not encrypt the private key in a PKCS#12 file-subj- defines the CN (Common Name) for the machine, in this situation use theoperatoruser login for your target CAST Storage Service/PostgreSQL instances-keyout- defines the name of the private key file-out- defines the name of the CSR file
Generate client certificate
To generate a client certificate client.crt signed with client.key, validated by client.csr and with a “parent” certificate being the root.crt and its associated private key (server.key), run:
openssl req -x509 -text -CAcreateserial -in client.csr -CA root.crt -CAkey server.key -out client.crt
Where:
req- indicates that we want to generate filesx509- outputs a certificate instead of a certificate request-text- prints out the certificate in text form-in- specifies the input filename to read a request from - use theclient.csrgenerated with the previous command-CA- specifies the “CA” certificate to be used for signing a new certificate - use theroot.crtgenerated previously - copy it from the CAST Storage Service/PostgreSQL instance where it was generated-CAkey- sets the “CA” private key to sign a certificate with. The private key must match the public key of the certificate given with-CA- use theserver.keygenerated previously - copy it from the CAST Storage Service/PostgreSQL instance where it was generated-out- specifies the output filenameclient.crtto write to
Generate client certificates in dedicated formats
Connections from some CAST components require client certificates in dedicated formats. To generate these client files, run these commands
# Create the PKCS8 key in DER format for JDBC connections
openssl pkcs8 -topk8 -in client.key -out client.pk8 -outform der -nocrypt
# Create PKCS8 in PEM format, specifically for the "imaging-services` Authentication Service
openssl pkcs8 -topk8 -in client.pk8 -out client.pem.pk8 -outform pem -nocrypt
# Create the PFX file for .NET connections
openssl pkcs12 -export -out client.pfx -inkey client.key -in client.crt -password pass:
Apply required permissions and ownership rights to client.key (Linux only)
Ensure the client.key permissions and ownership rights are correctly set:
chown root:root /path/to/client.key
chmod 0640 /path/to/client.key
Check output
At the end of the process you should have the following files available on the machine(s) hosting the relevant CAST components:
client.crtclient.csrclient.keyclient.pem.pk8client.pfxclient.pk8root.crt(copied from the CAST Storage Service/PostgreSQL instance where it was generated)server.key(copied from the CAST Storage Service/PostgreSQL instance where it was generated - only needed during the certificate creation process)