TLS/SSL (om_ssl)

The om_ssl module uses the OpenSSL library to provide TLS/SSL transport. It behaves like the om_tcp module, except that an SSL handshake is performed at connection time and the data is received over a secure channel. Log messages transferred over plain TCP can be eavesdropped or even altered with a man-in-the-middle attack, while the om_ssl module provides a secure log message transport.

Configuration

The om_ssl module accepts the following directives in addition to the common module directives. The Host directive is required.

Required directives

The following directives are required for the module to start.

Host

The module connects to this IP address or hostname. If additional hosts are specified on new lines, the module works in a failover configuration. If a destination becomes unavailable, the module automatically fails over to the next one. If the last destination becomes unavailable, the module fails over to the first destination.

The port number can be defined by appending it to the hostname or IP address using a colon as a separator (host:port). The default port is 514.

IPv6 addresses must be enclosed in square brackets ([addr]:port). For example, [2001:0db8:85a3:0:0:8a2e:0370:7334]:514.

When the Host directive is used with a hostname instead of an IP address, the hostname will be resolved to an IP address for each new connection. If a resolver, e.g. DNS, returns multiple IP addresses, the module will connect to the first IP address. If a single output instance is configured with multiple Host directives or the resolver returns multiple addresses for a name, these hosts are accessed in failover mode. If a Host directive is configured with a hostname, the product performs a name lookup and establishes the connection to the first reachable address in the returned set of addresses. The module will remain connected to that address until it is stopped, or the connection is severed. DNS changes are therefore not picked up by the module without intervention. If the connection fails to the first address of the set, the module will attempt to connect to the next address, until it reaches the end of the set of addresses. Then it performs a lookup on the next Host directive, if so configured. Once all options are exhausted, the module will start over from the first Host directive, cycling through them again until the connection can be re-established.

TLS/SSL directives

The following directives configure secure data transfer via TLS/SSL.

AllowExpired

Specifies if the connection should be allowed with an expired certificate. If set to TRUE, the remote host will be able to connect with an expired certificate. The default value is FALSE: the certificate must not be expired. This directive is only valid if RequireCert is set to TRUE.

AllowHostnameValidation

Specifies if the certificate FQDN should be validated against the server hostname or not. If set to TRUE, the connection will only be allowed if the certificate FQDN corresponds to the server hostname. The default value is FALSE: the remote server hostname is not validated.

AllowUntrusted

Specifies if the connection should be allowed regardless of the certificate verification results. If set to TRUE, the remote host will be able to connect with any unexpired certificate. The default value is FALSE: the remote host must present a trusted certificate.

CADir

Path to a directory containing certificate authority (CA) certificates. These certificates will be used to verify the certificate presented by the remote host. The certificate files must be named using the OpenSSL hashed format, i.e. the hash of the certificate followed by .0, .1 etc. To find the hash of a certificate using OpenSSL:

$ openssl x509 -hash -noout -in ca.crt

For example, if the certificate hash is e2f14e4a, then the certificate filename should be e2f14e4a.0. If there is another certificate with the same hash then it should be named e2f14e4a.1 and so on.

A remote host’s self-signed certificate (which is not signed by a CA) can also be trusted by including a copy of the certificate in this directory.

CAFile

Path of the certificate authority (CA) certificate that will be used to verify the certificate presented by the remote host. A remote host’s self-signed certificate (which is not signed by a CA) can be trusted by specifying the remote host certificate itself. In the case of certificates signed by an intermediate CA, the certificate specified must contain the complete certificate chain (certificate bundle).

CAPattern

This optional directive, supported only on Windows, defines a pattern for locating a suitable CA (Certificate Authority) certificate and its thumbprint in the native Windows Certificate Storage. The pattern must follow PCRE2 rules and use the format "SUBJECT=, CN=, DN=, SAN=" where DN is "CN=, O=, OU=, L=, ST=, C=". During configuration, this directive resolves into the corresponding CAThumbprint value. If multiple matching certificates are found, the first encountered thumbprint is selected. We recommend ensuring that the used certificate storage is well-maintained for optimal performance. This feature is not dynamic; the agent must be restarted if the certificate changes. This directive is mutually exclusive with the CAThumbprint directive.

Configuration examples:

CAPattern    'Test' + ' ' + 'Root'

CAPattern    $domain

A normal log output example would look like as follows:

matching pattern [DN=CN=Client\.example\.com;.*?SAN=DNS:Client\.example\.com] to certificate [SUBJECT=US, ClientState, ClientCity, ClientCompany, ClientUnit, Client.example.com, CN=Client.example.com; DN=CN=Client.example.com, O=ClientCompany, OU=ClientUnit, L=ClientCity, ST=ClientState, C=US; SAN=DNS:Client.example.com; DNS:www.Client.example.com; IP:127.0.0.3; ]

This directive is only supported on Windows.

CAThumbprint

This optional directive, supported only on Windows, specifies the thumbprint of the certificate authority (CA) certificate that will be used to verify the certificate presented by the remote host. The hexadecimal fingerprint string can be copied from Windows Certificate Manager (certmgr.msc). Whitespaces are automatically removed. The certificate must be added to a Windows certificate store that is accessible by NXLog Agent. This directive is mutually exclusive with the CADir, CAFile and CAPattern directives.

CertFile

Path of the certificate file that will be presented to the remote host during the SSL handshake.

CertKeyFile

Path of the private key file that was used to generate the certificate specified by the CertFile directive. This is used for the SSL handshake.

CertPattern

This optional directive, supported only on Windows, defines a pattern for identifying a corresponding certificate and its thumbprint within the native Windows Certificate Storage. The pattern must follow PCRE2 rules and use the format "SUBJECT=, CN=, DN=, SAN=" where DN is "CN=, O=, OU=, L=, ST=, C=". The certificate must be imported in PFX format into the Local Computer\Personal certificate store for NXLog Agent to locate it. During configuration, this directive is resolved into the corresponding CertThumbprint value. The first found thumbprint will be chosen if multiple certificates match the pattern. We recommend ensuring that the used certificate storage is well-maintained for optimal performance. This feature is not dynamic; the agent must be restarted if the certificate changes. This directive is mutually exclusive with the CertThumbprint directive.

Configuration examples:

CertPattern    $hostname + 'Cert'

CertPattern    DN=CN=Client\.example\.com;.*?SAN=DNS:Client\.example\.com

A normal log output example would look like as follows:

matching pattern [DN=CN=Client\.example\.com;.*?SAN=DNS:Client\.example\.com] to certificate [SUBJECT=US, ClientState, ClientCity, ClientCompany, ClientUnit, Client.example.com, CN=Client.example.com; DN=CN=Client.example.com, O=ClientCompany, OU=ClientUnit, L=ClientCity, ST=ClientState, C=US; SAN=DNS:Client.example.com; DNS:www.Client.example.com; IP:127.0.0.3; ]

CertThumbprint

This optional directive, supported only on Windows, specifies the thumbprint of the certificate that will be presented to the remote server during the HTTPS handshake. The hexadecimal fingerprint string can be copied from Windows Certificate Manager (certmgr.msc). Whitespaces are automatically removed. The certificate must be imported to the Local Computer\Personal certificate store in PFX format for NXLog Agent to find it. Run the following command to create a PFX file from the certificate and private key using OpenSSL:

$ openssl pkcs12 -export -out server.pfx -inkey server.key -in server.pem

When the global directive UseCNGCertificates is set to FALSE the private key associated with the certificate must be exportable.

If you generate the certificate request using Windows Certificate Manager, enable the Make private key exportable option from the certificate properties.
If you import the certificate with the Windows Certificate Import Wizard, make sure that the Mark this key as exportable option is enabled.
If you migrate the certificate and associated private key from one Windows machine to another, select Yes, export the private key when exporting from the source machine.

On the contrary, when the global directive UseCNGCertificates is set to TRUE the private key associated with the certificate does not have to be exportable. In cases like TPM modules, the private key is always nonexportable.

The usage of the directive is the same in all cases:

CertThumbprint    7c2cc5a5fb59d4f46082a510e74df17da95e2152

This directive is only supported on Windows and is mutually exclusive with the CertFile and CertKeyFile directives.

CRLDir

Path to a directory containing certificate revocation list (CRL) files. These CRL files will be used to check for certificates that were revoked and should no longer be accepted. The files must be named using the OpenSSL hashed format, i.e. the hash of the issuer followed by .r0, .r1 etc. To find the hash of the issuer of a CRL file using OpenSSL:

$ openssl crl -hash -noout -in crl.pem

For example if the hash is e2f14e4a, then the filename should be e2f14e4a.r0. If there is another file with the same hash then it should be named e2f14e4a.r1 and so on.

CRLFile

Path of the certificate revocation list (CRL) which will be used to check for certificates that have been revoked and should no longer be accepted. Example to generate a CRL file using OpenSSL:

$ openssl ca -gencrl -out crl.pem

DHFile

This optional directive specifies a file with dh-parameters for Diffie-Hellman key exchange. These parameters can be generated with dhparam(1ssl). If this directive is not specified, default parameters will be used. See the OpenSSL Wiki for further details.

KeyPass

Passphrase of the private key specified by the CertKeyFile directive. A passphrase is required when the private key is encrypted.

The following example generates a private key with Triple DES encryption using OpenSSL:

$ openssl genrsa -des3 -out server.key 2048

This directive is not required for passwordless private keys.

LoadCertificateChains

If set to TRUE, try to load higher-level certificates from the referenced PEM file which may contain only one certificate or the whole chain. The default value is FALSE: certificates will be instead loaded from the operating system certification storage.

This directive is only supported on Windows.

RequireCert

Specifies if the remote host must present a certificate. If set to TRUE and a certificate is not presented during the SSL handshake, the connection will be refused. The default value is TRUE: each connection must use a certificate.

SearchAllCertStores

This optional directive, supported only on Windows, if set to TRUE, enables the loading of all available Windows certificates into NXLog Agent for use during remote certificate verification. Any required certificates must be added to a Windows certificate store that NXLog Agent can access. This directive is mutually exclusive with the CAThumbprint, CADir, and CAFile directives.

Sigalgs

The signature algorithm parameter that is being sent to the Windows SSL library. Allowed values depend on the available encryption providers.

This directive is only supported on Windows.

SNI

This optional directive specifies the hostname used for Server Name Indication (SNI). If not specified, it defaults to the hostname in the Host directive.

SSLCipher

This optional directive can be used to set the permitted cipher list for TLSv1.2 and below, overriding the default. Use the format described in the ciphers(1ssl) man page. For example specify RSA:!COMPLEMENTOFALL to include all ciphers with RSA authentication but leave out ciphers without encryption.

If RSA or DSA ciphers with Diffie-Hellman key exchange are used, DHFile can be set for specifying custom dh-parameters.

SSLCiphersuites

This optional directive can be used to set the permitted cipher list for TLSv1.3. Use the same format as in the SSLCipher directive. Refer to the OpenSSL documentation for a list of valid TLS v1.3 cipher suites. The default value is:

TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

SSLCompression

Specifies if data compression is enabled when sending data over the network. The compression mechanism is based on the zlib compression library. The default value is FALSE: compression is disabled.

Some Linux packages (for example, Debian) use the OpenSSL library provided by the OS and may not support the zlib compression mechanism. The module will emit a warning on startup if the compression support is missing. The generic deb/rpm packages are bundled with a zlib-enabled libssl library.

SSLProtocol

This directive can be used to set the allowed SSL/TLS protocol(s). It takes a comma-separated list of values which can be any of the following: SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3. By default, the TLSv1.2 and TLSv1.3 protocols are allowed. Note that the OpenSSL library shipped by Linux distributions may not support SSLv2 and SSLv3, and these will not work even if enabled with this directive.

UseCNGCertificates

If set to TRUE, the module uses the Windows Cryptography API: Next Generation (CNG) to access the private keys associated with certificates identified by a thumbprint.

This directive is only supported on Windows.

Optional directives

LocalPort

This optional directive specifies the local port number of the connection. If this is not specified, a random high port number will be used, which is not always ideal in firewalled network environments.

Due to the required TIME-WAIT delay in closing connections, attempts to bind to LocalPort may fail. In such cases, the message Address already in use will be written to nxlog.log. If the situation persists, it could impede network performance.

OutputType

See the OutputType directive in the list of common module directives. The default is LineBased_LF.

Reconnect

This optional directive sets the reconnect interval in seconds. If it is set, the module attempts to reconnect in every defined second. If it is not set, the reconnect interval will start at 1 second and double with every attempt. If the duration of the successful connection is greater than the current reconnect interval, then the reconnect interval will be reset to 1 sec.

The Reconnect directive must be used with caution. If it is used on multiple systems, it can send reconnect requests simultaneously to the same destination, potentially overloading the destination system. It may also cause NXLog Agent to use unusually high system resources or cause NXLog Agent to become unresponsive.

ReconnectOnData

This optional directive defines the behavior when the connection with the remote host is lost. When set to TRUE, the module only attempts to reconnect when it has data to send. The default value is FALSE; it will always keep a connection open with the remote host.

TCPNoDelay

This boolean directive is used to turn off the network optimization performed by Nagle’s algorithm. Nagle’s algorithm is a network optimization tweak that tries to reduce the number of small packets sent out to the network, by merging them into bigger frames, and by not sending them to the other side of the session before receiving the ACK. If this directive is unset, the TCP_NODELAY socket option will not be set.

Procedures

The following procedures are exported by om_ssl.

reconnect();

Force a reconnection. This can be used from a Schedule block to periodically reconnect to the server.

The reconnect() procedure must be used with caution. If configured, it can attempt to reconnect after every event sent, potentially overloading the destination system.

Examples

Example 1. Sending logs to another {agent) instance

This configuration reads log messages from a socket and sends them in the NXLog Binary format to another NXLog Agent instance.

nxlog.conf

<Input uds>
    Module          im_uds
    UDS             tmp/socket
</Input>

<Output ssl>
    Module          om_ssl
    Host            example.com:23456
    CAFile          %CERTDIR%/ca.pem
    CertFile        %CERTDIR%/client-cert.pem
    CertKeyFile     %CERTDIR%/client-key.pem
    KeyPass         secret
    AllowUntrusted  TRUE
    OutputType      Binary
</Output>

Example 2. Sending logs to another NXLog Agent instance with failover

This configuration sends logs to another NXLog Agent instance in a failover configuration (multiple Hosts defined).

nxlog.conf

<Output ssl>
    Module  om_ssl
    Host    192.168.1.2:23456
    Host    192.168.1.3:23456
    Host    example.com:1514
    CAFile  %CERTDIR%/ca.pem
</Output>