Skip to main content

Service encryption

Service traffic encryption is designed to enhance the security of exchanges and to protect user privacy against attacks carried out from networks. In this section, we show you how to configure it for your Genesis applications.

info

Genesis supports TLS only. SSL is deprecated and not supported. Legacy config and docs may still use “SSL” in names or wording; in all cases the protocol in use is TLS.

Configuring TLS​

To support TLS fine-tuning by process, Genesis has two types of configuration files:

  • network-config.yaml — the global network config settings
  • network-config-PROCESS_NAME.yaml — process-level overrides

As soon as a project detects either of these files, the new TLS configuration will be enabled. Environment variables can be used in the YAML directly using ${...}.

For a full overview of all available options, see the Network configuration YAML reference.

TLS Modes​

Genesis supports four modes for traffic encryption:

  • Plain text: services do not use encryption
  • Selective TLS: only selected services use TLS
  • TLS: all services use TLS
  • Mutual TLS: all services use TLS, plus services require client certificates

Before version 8.15 of the Genesis Platform, only plain text and selective TLS were supported. To configure previous versions, see Legacy configuration. The legacy configuration is still supported in version 8.15 and beyond.

Plain text​

Plain text is the default mode, and no additional configuration is required. However, to explicitly use plain text, see the following minimal example.

tls: 
  mode: PLAIN_TEXT

Selective TLS​

In selective TLS, TLS needs to be enabled on a process-by-process level, in contrast to TLS and MUTUAL_TLS, which will always be enabled across all processes. Those (secure="true") processes will encrypt their connections. Client connections to any processes will verify the identity of (secure="true") processes. All other connections will be unencrypted and unverified.

Minimal configuration​

This is a minimal configuration to enable selective TLS. For a full overview of available options, see the Network configuration YAML reference.

tls:
  mode: SELECTIVE_TLS
  identity:
    source: KEYSTORE
    keystore:
      type: "JKS"
      path: "/path/to/server-keystore.jks"
      storePassword: "testpass"
      keyAlias: "server"
      keyPassword: "testpass"
  trust:
    source: SYSTEM

Additionally, for selective TLS, please adjust the relevant *-service-definitions.xml files and add the secure="true" property for the required processes.

<configuration>
  <service host="localhost" name="POSITION_DATASERVER" port="11000" secure="true"/>
  <service host="localhost" name="POSITION_REQUEST_SERVER" port="11001" secure="true"/>
  <service host="localhost" name="POSITION_EVENT_HANDLER" port="11002" secure="true"/>
  <service host="localhost" name="POSITION_CONSOLIDATOR" port="11003" secure="true"/>
  <service host="localhost" name="POSITION_FGW" port ="11004" secure="true"/>
  <service host="localhost" name="POSITION_FGW_STREAMER" port ="11005" secure="true"/>
  <service host="localhost" name="POSITION_FGW_STREAMER_CLIENT" port ="11006" secure="true"/>
</configuration>

TLS​

When using the TLS mode, TLS is used across all processes. All processes will encrypt their connections. Client connections to any processes will verify the identity of the process they are connected to.

Minimal configuration​

This is a minimal configuration to enable TLS. For a full overview of available options, see the Network configuration YAML reference.

tls:
  mode: TLS
  identity:
    source: CERTIFICATE
    certificate:
      certChainPath: "/path/to/server-cert.pem"
      privateKeyPath: "/path/to/server-key.pem"
      privateKeyPassword: ""
  trust:
    source: CERTIFICATE
    certificate:
      caBundlePath: "/path/to/ca-cert.pem"

Mutual TLS​

When using Mutual TLS mode, TLS is enforced across all processes. All processes will encrypt their connections. Client connections to any processes will verify the identity of the process they are connected to. Processes verify client identities when clients connect.

Minimal configuration​

This is a minimal configuration to enable Mutual TLS. For a full overview of available options, see the Network configuration YAML reference.

tls:
  mode: MUTUAL_TLS
  identity:
    source: CERTIFICATE
    certificate:
      certChainPath: "/path/to/server-cert.pem"
      privateKeyPath: "/path/to/server-key.pem"
  trust:
    source: CERTIFICATE
    certificate:
      caBundlePath: "/path/to/ca-cert.pem"

Legacy configuration​

Legacy TLS is still supported for version 8.15 and beyond. It uses XML (service-definitions, system-definitions, process config) and JKS keystores. In legacy configuration, only plain text and selective TLS are available. For production, use certificates from a trusted CA (see your CA's documentation for keystore creation). For creating test certificates only, see Generating certificates for testing only below.

How legacy settings relate to the new configuration​

The legacy XML and JKS settings correspond to the new network-config YAML model as follows:

  • secure="true" in *-service-definitions.xml — same, see Selective TLS for details.
  • DefaultKeystoreLocation / DefaultKeystorePassword / DefaultCertificate in system-definitions — server identity and trust in the new model (tls.identity with KEYSTORE, tls.trust with CERTIFICATE or SYSTEM).
  • Per-process messaging / keyStoreLocation / keyStorePassword in <product>-process-config.kts — process-level overrides in the new model (network-config-{processName}.yaml).

Global TLS settings​

In genesis-system-definitions.kts set DefaultKeystoreLocation, DefaultKeystorePassword, and DefaultCertificate:

    // Required if the processes are to communicate through TLS
    item(name="DefaultKeystoreLocation", value="/path/to/keystore.jks")
    item(name="DefaultKeystorePassword", value="Password123")
    item(name="DefaultCertificate", value="/path/to/certificate.crt")

These values are used by all processes to communicate with encrypted processes or to accept encrypted connections.

Web GUI​

Ensure that the server is configured to accept the certificate, .. better wording here.. Install the server certificate (or the test CA) on the target machine's operating system as a trusted root CA so the browser trusts the connection.

Generating test certificates​

warning

The following steps are for creating self-signed certificates (e.g. for use in dev or test environments). Do not use these certificates in production. For production, use certificates from a trusted CA.

Generate a CA cert​

Create a self-signed CA and store it in a dedicated keystore. This CA will be used to sign server certificates so you can install a single CA cert on test machines instead of each server cert.

keytool -genkeypair -keyalg RSA -keysize 2048 -alias test-ca -keystore ca.jks -storepass changeit -validity 3650 -ext bc:ca:true

When prompted, enter a distinguished name (e.g. CN=Test CA, OU=IT, O=MyOrg, L=City, ST=State, C=XX). The resulting ca.jks is your test CA keystore.

Generate a server cert signed by the CA​

  1. Create a server keystore and keypair. Use the server hostname or SANs that clients will use to connect:
keytool -genkeypair -keyalg RSA -keysize 2048 -alias server -keystore keystore.jks -storepass changeit -validity 825 -ext SAN=dns:localhost,dns:myserver.example.com

Answer the prompts (CN should match the primary server name). Store this keystore outside the application directory (e.g. /home/exmon/keystore.jks).

  1. Generate a certificate signing request (CSR) from the server keystore:
keytool -certreq -alias server -keystore keystore.jks -storepass changeit -file server.csr
  1. Sign the CSR with your test CA:
keytool -gencert -alias test-ca -keystore ca.jks -storepass changeit -infile server.csr -outfile server.cer -validity 825
  1. Import the CA cert into the server keystore (if not already present), then import the signed server cert:
keytool -export -alias test-ca -keystore ca.jks -storepass changeit -file ca.crt
keytool -importcert -alias test-ca -file ca.crt -keystore keystore.jks -storepass changeit -noprompt
keytool -importcert -alias server -file server.cer -keystore keystore.jks -storepass changeit -noprompt

The server keystore (keystore.jks) is now ready for use with DefaultKeystoreLocation. To give clients a cert to trust, export the CA cert: keytool -export -alias test-ca -file ca.crt -keystore ca.jks -storepass changeit. Use ca.crt (not the server cert) when installing on test machines so all servers signed by this CA are trusted.

Install the test CA cert on a test machine​

Clients (browsers, GUI, other test processes) must trust the test CA so they accept server certificates signed by it. Install the CA certificate (ca.crt) as a trusted root on each test machine that will connect.

Linux​

Distribution-dependent. On Ubuntu:

sudo cp ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Windows​

Right-click ca.crt and select Install Certificate. Choose Local machine, then Place all certificates in the following store and select Trusted Root Certification Authorities.