Fabasoft Folio uses socket connections to connect backend services and frontend clients.
The socket communication used between frontend and backend services may be encrypted and authenticated using SSL/TLS encryption.
Clients and server processes use certificate fingerprints to identify trusted peers. The default implementation uses keys and trusts per host. Every host acting as part of a Fabasoft installation has to have a key and the correct trusts to identify services and clients.
To enable encryption and authentication, the environment variable TLSDIR is used. This variable is configured as other environment variables used to configure the socket connection (e.g. HOST, PORT) for Fabasoft Services.
Once the variable is configured for a service or client process, the referenced directory and the required files must exist, otherwise the service or client will fail to work and report errors.
If the variable is added or changed, all services have to be restarted.
Default value of TLSDIR on Microsoft Windows
To set the variable for Microsoft Windows, add the environment variable in the system properties as system variable.
Default value of TLSDIR on Linux
$ export TLSDIR="/var/opt/fabasoft/tls"
To set the variable for Linux, add the entry to the file /etc/fabasoft/base.conf.
Once the TLSDIR is set it must point to a directory containing a key and a trusts file per host.
This file contains the certificate and private key and is used to authenticate the peer (client or server) of a SSL/TLS protected socket connection.
Sample file hostkey.pem
-----BEGIN PRIVATE KEY-----
This file contains fingerprints (SHA-256) of accepted peer certificates.
Sample file hosttrusts.cfg
# Trusted host certificates (sha256 fingerprint).
Text following a # is ignored and empty lines are ignored, too.
To create new certificates, the utility fsckeygen may be used. The utility will create the files hostkey.pem (new certificate and key) and hosttrusts.cfg (fingerprint of the newly created certificate).
Any existing fingerprints of trusted peer certificates must be added manually.
Sample use of fsckeygen on Microsoft Windows
As reference the corresponding openssl commands are listed.
Reference bash commands to generate host key and trusts
openssl $NEWCERTARGS -keyout key.pem -out cert.pem
rm cert.pem key.pem certfp.cfg
A typical installation of Fabasoft Services uses multiple hosts.
To enable this scenario, the host key and host trust files may be copied to all connected machines or the host trust files of all connected machines have to be edited manually to contain all fingerprints of trusted host certificates.