Transport layer encryption

Topics

Transport layer encryption secures communication between Energylogserver components. Configuration details are available in the Security Configuration section.

For external documentation, visit the official TLS guide.

Offline TLS Tool

The TLS Tool is a program that can be used for:

  • Generating Root and Intermediate CA’s,

  • Generating Node, Client, and Admin certificates,

  • Generating CSRs,

  • Validating certificates

Besides the actual certificates the tool also generated configuration snippets which you can directly copy and paste into your Data Node main .yml file.

General usage

The tls tool will read the node and certificate configuration settings from a yaml file, and outputs the generated files in a configurable directory.

You can choose to create the Root CA and (optional) intermediate CAs with your node certificates in one go. Or you can create the Root and intermediate CA first, and generate node certificates as you need them.

You will find the script in:

<installation directory>/tlstool.sh

Command line options

TLS Command Line Options

Name

Description

-c,–config

Relative or absolute path to the configuration file. Required.

-t,–target

Relative or absolute path to the output directory. Optional, default: out

-v,–verbose

Enable detailed output, default: false

-f,–force

Force certificate generation despite of validation errors. default: false

-o,–overwrite

Overwrite existing node-, client and admin certificates if they are already present. default: false

-p,–pem

Change certificate file extension from “.crt” to “.pem”. default: false

-ca,–create-ca

Create new Root and Intermediate CAs

-crt,–create-cert

Create certificates using an existing or newly created local certificate authority

Examples

<installation directory>/tlstool.sh -c config/tlsconfig.yml -ca -crt

Reads the configuration from config/tlsconfig.yml and generates the configured Root and intermediate CAs and the configured node, admin, and client certificates in one go. The generated files will be written to out.

<installation directory>/tlstool.sh -c config/tlsconfig.yml -ca

Reads the configuration from config/tlsconfig.yml and generates the configured Root and intermediate CAs only.

<installation directory>/tlstool.sh -c config/tlsconfig.yml -crt

Reads the configuration from config/tlsconfig.yml and generates node, admin, and client certificates only. The Root and (optional) intermediate CA certificates and keys need to be present in the output directory, and their filenames, keys and (optional) passwords have to be configured in tlsconfig.yml.

Root CA

To configure the Root CA for all certificates, add the following lines to your configuration file:

ca:
   root:
      dn: CN=root.ca.example.com,OU=CA,O=Example Com, Inc.,DC=example,DC=com
      keysize: 2048
      pkPassword: root-ca-password 
      validityDays: 3650
      file: root-ca.crt

Generated files:

  • root-ca.crt - Root certificate

  • root-ca.key - Private key of the Root CA

  • root-ca.readme - Auto-generated passwords of the root and intermediate CAs

Options:

Root CA Configuration Options

Name

Description

dn

The complete Distinguished Name of the Root CA. If you have special characters in the DN, you need to quote them correctly. Mandatory.

keysize

The size of the private key. Default: 2048

pkPassword

Password of the private key. One of: “none”, “auto” or a self-chosen password. Default: auto

file

File name of the certificate, optional. Default: “root-ca”

The pkPassword can be one of:

  • none: The generated private key will be unencrypted

  • auto: A random password is generated automatically. After the certificates have been generated, you can find the password in root-ca.readme file. To use these new passwords again, you must edit the tool config file and set the generated passwords there.

  • other value: Values other than none or auto are used as password directly

Intermediate CA

In addition to the root CA you optionally also specify an intermediate CA. If an intermediate CA is configured, then the node, admin, and client certificates will be signed by the intermediate CA. If you do want to use an intermediate CA, remove the following section from the configuration. The certificates are then signed by the root CA directly.

ca:
   intermediate:
      dn: CN=signing.ca.example.com,OU=CA,O=Example Com, Inc.,DC=example,DC=com
      keysize: 2048
      validityDays: 3650  
      pkPassword: intermediate-ca-password
      file: intermediate-ca.crt

Generated files:

  • intermediate-ca.crt - Intermediate certificate

  • intermediate-ca.key - Private key of the intermediate certificate

  • root-ca.readme - Auto-generated passwords of the root and intermediate CAs

Node and Client certificates

Global and default settings

The default settings are applied to all generated certificates and configuration snippets. All values here are optional.

defaults:
  validityDays: 730
  pkPassword: auto
  generatedPasswordLength: 12
  nodesDn:
    - "CN=*.example.com,OU=Ops,O=Example Com, Inc.,DC=example,DC=com"
  nodeOid: "1.2.3.4.5.5"
  httpsEnabled: true
  reuseTransportCertificatesForHttp: false

Options:

TLS Configuration Parameters

Parameter

Description

validityDays

Validity of the generated certificates, in days. Default: 730. Can be overwritten for each certificate separately.

pkPassword

Password of the private key. One of: “none”, “auto” or a self-chosen password. Default: auto. Can be overwritten for each certificate separately.

generatedPasswordLength

Length of the auto-generated password for the private keys. Only takes effect when pkPassword is set to auto. Default: 12. Can be overwritten for each certificate separately.

httpsEnabled

Whether to enable TLS on the REST layer or not. Default: true

reuseTransportCertificatesForHttp

If set to false, individual certificates for REST and Transport are generated. If set to true, the node certificates are also used on the REST layer. Default: false

verifyHostnames

Set this to true to enable hostname verification. Default: false

resolveHostnames

Set this to true to resolve hostnames against DNS. Default: false

signatureAlgorithm

Signature algorithm (for RSA default is SHA256withRSA, for EC its SHA256withECDSA)

useEllipticCurves

If set to true use elliptic curves instead of RSA. Default is false (since 1.7)

ellipticCurve

The curve to be used. Default is: NIST P-384 (since 1.7)

Node certificates

To generate node certificates, add the node name, the Distinguished Name, the hostname(s), and/or the IP address(es) in the nodes section:

nodes:
  - name: node1
    dn: CN=test.example.com,OU=Dev,O=Energy Software,C=Poland
    dns: test.example.com
    ip: 10.0.2.1
  - name: node2
    dn: CN=node2.example.com,OU=Dev,O=Energy Software,C=Poland
    dns: 
      - node2.example.com
      - es2.example.com
    ip: 
      - 10.0.2.1
      - 192.168.2.1
  - name: node3
    dn: CN=node3.example.com,OU=Dev,O=Energy Software,C=Poland
    dns: node3.example.com

Generated files:

  • [nodename].crt - Node certificate

  • [nodename].key - Private key of the node certificate

  • [nodename]_http.crt - REST certificate, only generated if reuseTransportCertificatesForHttp is false

  • [nodename]_logserver_config_snippet.yml - Logserver Guard configuration snippet for this node, add this to logserver.yml

Options:

Node Certificate Options

Name

Description

name

Name of the node, will become part of the filenames. Mandatory

dn

The Distinguished Name of the certificate. If you have special characters in the DN, you need to quote them correctly. Mandatory

dns

The hostname(s) this certificate is valid for. Should match the hostname of the node. Optional, but recommended.

ip

The IP(s) this certificate is valid for. Optional. Prefer hostnames if possible.

Admin and client certificates

To generate admin and client certificates, add the following lines to the configuration file:

clients:
  - name: spock
    dn: CN=spock.example.com,OU=Dev,O=Energy Software,C=Poland
  - name: kirk
    dn: CN=kirk.example.com,OU=Dev,O=Energy Software,C=Poland
    admin: true

Generated files:

  • [name].crt - Client certificate

  • [name].key - Private key of the client certificate

  • client-certificates.readme - Contains the auto-generated passwords for the certificates

Options:

Client Certificate Options

Name

Description

name

Name of the certificate, will become part of the file name

dn

The complete Distinguished Name of the certificate. If you have special characters in the DN, you need to quote them correctly

admin

If set to true, this certificate will be marked as an admin certificate in the generated configuration snippet.

Note that you need to mark at least one client certificate as an admin certificate.

Adding certificates after the first run

You can always add more node- or admin certificates as you need them after the initial run of the tool. As a precondition

  • the root CA and, if used, the intermediate certificates and keys must be present in the output folder

  • the password of the root CA and, if used, the intermediate CA must be present in the config file

If you use auto-generated passwords, copy them from the generated root-ca.readme file to the configuration file.

Certificates that have already been generated in a previous run of the tool will be left untouched unless you run the tool with the -o,--overwrite switch. In this case, existing files are overwritten. If you have chosen to auto-generate passwords, new keys with auto-generated passwords are created.

Creating CSRs

If you just want to create CSRs to submit them to your local CA, you can omit the CA part of the config complete. Just define the default, node, and client section, and run the TLS tool with the -csr switch.

Configuring ciphers for TLS settings

How to enable, disable and/or limit available ciphers for Logserver services.

Logserver Data Node

Edit config file /etc/logserver/logserver.yml.

Example:

logserverguard.ssl.transport.enabled_ciphers:
- TLS_AES_256_GCM_SHA384
- TLS_AES_128_GCM_SHA256
- TLS_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

logserverguard.ssl.http.enabled_ciphers:
- TLS_AES_256_GCM_SHA384
- TLS_AES_128_GCM_SHA256
- TLS_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

After editing restart Data Node service. Note that this settings should be updated on all cluster nodes.

Logserver GUI

Edit config file /etc/logserver-gui/logserver-gui.yml.

Example:

server.ssl.cipherSuites:
- TLS_AES_256_GCM_SHA384
- TLS_AES_128_GCM_SHA256
- TLS_CHACHA20_POLY1305_SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384
- ECDHE-ECDSA-CHACHA20-POLY1305
- ECDHE-RSA-CHACHA20-POLY1305
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256

After editing restart Logserver GUI service

Cerebro

Since 7.6.1 there is a default configuration for enabled algorithms on path /opt/cerebro/conf/java.config.

You can edit it and after restarting cerebro.service, changes will be applied.

7.6.0 and before

  1. To recreate current default behavior, create file /opt/cerebro/conf/java.config with content:

    security.useSystemPropertiesFile=false
jdk.tls.ephemeralDHKeySize=2048
jdk.certpath.disabledAlgorithms=MD2, SHA1, MD5, DSA, RSA keySize < 2048
jdk.tls.disabledAlgorithms=DH keySize < 2048, TLSv1.1, TLSv1, SSLv3, SSLv2, TLS_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_GCM_SHA384, TLS_RSA_WITH_AES_128_GCM_SHA256, DHE_DSS, RSA_EXPORT, DHE_DSS_EXPORT, DHE_RSA_EXPORT, DH_DSS_EXPORT, DH_RSA_EXPORT, DH_anon, ECDH_anon, DH_RSA, DH_DSS, ECDH, 3DES_EDE_CBC, DES_CBC, RC4_40, RC4_128, DES40_CBC, RC2, HmacMD5, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_256_CBC_SHA
jdk.tls.legacyAlgorithms=

  2. Edit ExecStart definition of /usr/lib/systemd/system/cerebro.service like so:

    ExecStart=/opt/cerebro/bin/cerebro "-Djava.security.properties=/opt/cerebro/conf/java.config" "-Dconfig.file=/opt/cerebro/conf/application.conf"

  3. Reload systemd and restart cerebro.service

    systemctl daemon-reload
systemctl reenable cerebro
systemctl restart cerebro

E-doc

Since 7.6.1 there is a default configuration for enabled ciphers on path /opt/e-doc/env.config.

You can edit it and after restarting e-doc.service, changes will be applied.

7.6.0 and before

  1. To recreate current default behavior, create file /opt/e-doc/env.config with content:

    NODE_OPTIONS=--tls-cipher-list='TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA256:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!SRP:!CAMELLIA'

  2. Edit /usr/lib/systemd/system/e-doc.service. Add following under [Service] section:

    EnvironmentFile=-/opt/e-doc/env.config

  3. Reload systemd and restart e-doc.service

    systemctl daemon-reload
systemctl reenable e-doc
systemctl restart e-doc