See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-1263

From Zabbix.org
Jump to: navigation, search

Daemon communication encryption: TLS

ZBXNEXT-1263

Status: Work in progress

Owner: Andris Mednis

Summary

Zabbix should support encrypted communications between Zabbix components (server, proxies, agents and command-line utilities).

Encryption is optional and configurable for individual components (e.g. some proxies and agents can be configured to use encrypted communications with server while others can use unencrypted communications as before).

Specification

Cryptographic protocol

Initially, Transport Layer Security (TLS) protocol v.1.2 will be used for encrypted communications between Zabbix components.

With time newer versions of TLS protocol (e.g. v1.3) can be supported, with maintaining backward compatibility with TLS 1.2 which can be used by older agent versions.

Communication ports

Zabbix daemon programs use one listening port for encrypted and unencrypted incoming connections. Adding an encryption does not require opening new ports on firewalls.

Cryptographic libraries

Zabbix will rely on cryptographic libraries as much as possible for encrypted communications.

Zabbix should not rely on just one particular library. Several cryptographic libraries with possible choice between them in configuration/compilation step should be supported. This will avoid tight architectural ties between Zabbix and one particular library and will provide a possibility of switching to other library if a security vulnerability is found in one of them.

It is proposed to support libraries:

  • PolarSSL (recently renamed to mbed TLS)(1.3.x branch starting from version 1.3.9. mbed TLS 2.x initially will not be supported.)
  • GnuTLS (from version 3.1.18)
  • OpenSSL (from version 1.0.1)

Certificates and keys

Zabbix should support using certificates signed by a certificate authority and pre-shared keys (PSK) as supported by TLS 1.2. Self-signed certificates will not be supported.

Initially only certificates with RSA keys will be supported.

Both communicating parties (TLS client and server) should use certificates to identify themselves or a PSK. Only one certificate can be configured for use by a Zabbix component. Choosing between multiple certificates is not supported.

Only one PSK can be configured for use by agent and proxy (for communicating with server). Multiple PSKs can be configured in Zabbix server for communicating with different agents and proxies.

Changes in configuration options

Three new options need to be added to "configure" script:

--with-mbedtls[=DIR]  --with-gnutls[=DIR]  --with-openssl[=DIR]

These options are optional and mutually exclusive. It should be possible to compile Zabbix without them if encryption support is not required.

Changes in configuration files

Changes in server configuration file

New parameters will be added to server configuration file:

  • TLSCAFile - full pathname of a file containing the top-level CA(s) certificates for peer certificate verification
  • TLSCRLFile - full pathname of a file containing revoked certificates
  • TLSCertFile - full pathname of a file containing the server certificate or certificate chain
  • TLSKeyFile - full pathname of a file containing the server private key

Changes in proxy and agentd configuration files

New parameters will be added to proxy and agentd configuration files:

  • TLSConnect - what outgoing connection to use (either "unencrypted", "psk", or "cert")
  • TLSAccept - what incoming connections to accept (list of "unencrypted", "psk", and "cert")
  • TLSCAFile - full pathname of a file containing the top-level CA(s) certificates for peer certificate verification
  • TLSCRLFile - full pathname of a file containing revoked certificates
  • TLSServerCertIssuer - allowed server certificate issuer
  • TLSServerCertSubject - allowed server certificate subject
  • TLSCertFile - full pathname of a file containing the proxy or agentd certificate or certificate chain
  • TLSKeyFile - full pathname of a file containing the proxy or agentd private key
  • TLSPSKIdentity - PSK-identity string
  • TLSPSKFile - full pathname of a file containing the proxy or agentd pre-shared key (PSK)

Changes in commandline options

New options for zabbix_sender

  • --tls-connect - how to connect to server or proxy (either "unencrypted", "psk", or "cert")
  • --tls-ca-file - full pathname of a file containing the top-level CA(s) certificates for peer certificate verification
  • --tls-crl-file - full pathname of a file containing revoked certificates
  • --tls-server-cert-issuer - allowed server certificate issuer
  • --tls-server-cert-subject - allowed server certificate subject
  • --tls-cert-file - full pathname of a file containing certificate or certificate chain
  • --tls-key-file - full pathname of a file containing private key
  • --tls-psk-identity - PSK-identity string
  • --tls-psk-file - full pathname of a file containing the pre-shared key (PSK)

New options for zabbix_get

  • --tls-connect - how to connect to agent (either "unencrypted", "psk", or "cert")
  • --tls-ca-file - full pathname of a file containing the top-level CA(s) certificates for peer certificate verification
  • --tls-crl-file - full pathname of a file containing revoked certificates
  • --tls-agent-cert-issuer - allowed agent certificate issuer
  • --tls-agent-cert-subject - allowed agent certificate subject
  • --tls-cert-file - full pathname of a file containing certificate or certificate chain
  • --tls-key-file - full pathname of a file containing private key
  • --tls-psk-identity - PSK-identity string
  • --tls-psk-file - full pathname of a file containing the pre-shared key (PSK)

Front-end changes

Configuration of host

In addition to existing tabs (Host, Templates, IPMI, Macros, Host Inventory) a new tab Encryption will be added with the following elements:

  • Connections to host - select field with three options No encryption, PSK and Certificate;
  • Connections from host - three checkboxes: No encryption, PSK and Certificate;
  • PSK identity - text field with maximum length 128 characters. Visible only when at least one option (select or checkbox) PSK is selected;
  • PSK - text field with maximum length 512 characters. Visible only when at least one option (select or checkbox) PSK is selected;
  • Issuer - text field with maximum length 1024 characters. Visible only when at least one option (select or checkbox) Certificate is selected;
  • Subject - text field with maximum length 1024 characters. Visible only when at least one option (select or checkbox) Certificate is selected.

Configuration of proxy

In Configuration of proxy in addition to existing tab Proxy a new tab Encryption will be added with the following elements:

  • Connections to proxy - select field with three options No encryption, PSK and Certificate;
  • Connections from proxy - three checkboxes: No encryption, PSK and Certificate;
  • PSK identity - text field with maximum length 128 characters. Visible only when at least one option (select or checkbox) PSK is selected;
  • PSK - text field with maximum length 512 characters. Visible only when at least one option (select or checkbox) PSK is selected;
  • Issuer - text field with maximum length 1024 characters. Visible only when at least one option (select or checkbox) Certificate is selected;
  • Subject - text field with maximum length 1024 characters. Visible only when at least one option (select or checkbox) Certificate is selected.

Configuration of host prototype

In addition to existing tabs (Host, Templates, IPMI, Macros, Host Inventory) a new tab Encryption will be added with the following elements:

  • Connections to host - select field with three options No encryption, PSK and Certificate. Field is disabled;
  • Connections from host - three checkboxes: No encryption, PSK and Certificate. Field is disabled;
  • PSK identity - text field with maximum length 128 characters. Visible only when at least one option (select or checkbox) PSK is selected. Field is disabled;
  • PSK - text field with maximum length 512 characters. Visible only when at least one option (select or checkbox) PSK is selected. Field is disabled;
  • Issuer - text field with maximum length 1024 characters. Visible only when at least one option (select or checkbox) Certificate is selected. Field is disabled;
  • Subject - text field with maximum length 1024 characters. Visible only when at least one option (select or checkbox) Certificate is selected. Field is disabled.

All elements disabled are values are taken from host, just like in other tabs.

Detailed description of elements

  • Issuer. A UTF-8 text input field, up to 1024 UTF-8 characters (4096 bytes). Stored into DB table “hosts” field “tls_issuer”.
  • Subject. A UTF-8 text input field, up to 1024 UTF-8 characters (4096 bytes). Stored into DB table “hosts” field “tls_subject”.
  • PSK identity. A UTF-8 text input field, up to 128 characters (i.e. 512 bytes). Stored into DB table “hosts” field “tls_psk_identity”.
  • PSK. A text input field for entering up to 512 bytes of pre-shared key value, (allows to specify up to 256-byte PSK as a hex string). Stored into DB table “hosts” field “tls_psk”.
  • Connections to host and Connections to proxy allow to choose one of fixed values:
    • No encryption
    • PSK
    • Certificate.
  • Default value is No encryption. Stored into DB table “hosts” field “tls_connect” with values:
    • 1 – default value for a new host and proxy or if No encryption was chosen
    • 2 – if PSK identity was chosen
    • 4 – if Certificate was chosen.
  • Connections from host and Connections from proxy allow to select one, two or all three values - No encryption, PSK and Certificate. By default, No encryption is selected. Stored into DB table “hosts” field “tls_accept” with bitwise "OR" combination of values:
    • 1 – if No encryption was selected;
    • 2 – if PSK was selected;
    • 3 – if both No encryption and PSK were selected;
    • 4 – if Certificate was selected;
    • 5 – if both No encryption and Certificate were selected;
    • 6 – if both PSK and Certificate were selected;
    • 7 – if all three options No encryption, PSK and Certificate were selected.

Show/hide rules for fields in Encryption tab

  • If Connections to host (proxy) is set to Certificate or Connections from host (proxy) includes a value Certificate then Issuer and Subject input fields are visible for editing. Otherwise these input fields are hidden and empty.
  • If Connections to host (proxy) is set to PSK or Connections from host (proxy) includes a value PSK then PSK Identity and PSK input fields are visible for editing. Otherwise these input fieds are hidden and empty.

Validation

  • If Connections to host (proxy) is set to PSK or Connections from host (proxy) includes a value PSK, then both PSK Identity and PSK input fields must be filled in.
  • In the PSK input field allowed characters are a pair of hex digits: 0-9, a-f, A-F. For example '0A' and not 'A'.
  • Connections to host (proxy) must only have value 1, 2 or 4.
  • Connections from host (proxy) must have only value 1, 2, 3, 4, 5, 6 or 7.
  • If no checkbox No encryption, PSK or Certificate was selected, user should be prompted to select at least one encryption type.

API changes

host.create, host.update, host.massupdate, proxy.create and proxy.update methods should support and validate new fields:

  • tls_connect
  • tls_accept
  • tls_issuer
  • tls_subject
  • tls_psk_identity
  • tls_psk

Validation:

 tls_connect can have values: 1, 2 or 4
 tls_accept can have values 1, 2, 3, 4, 5, 6 or 7.
 tls_psk_identity cannot be empty if either tls_connect or tls_accept have PSK set.
 tls_psk cannot be empty if either tls_connect or tls_accept have PSK set.
 tls_psk can have only hexadecimal character pairs 0-9, a-f, A-F.

hostprototype.create and hostprototype.update must locate and fill new fields from parent host.

XML import/export

XML import/export will support new properties <tls_connect>, <tls_accept>, <tls_issuer>, <tls_subject>, <tls_psk_identity> and <tls_psk> for each host:

 ...
 <host>
   ...
   <tls_connect>2</tls_connect>
   <tls_accept>7</tls_accept>
   <tls_issuer>issuer</tls_issuer>
   <tls_subject>subject</tls_subject>
   <tls_psk_identity>PSK identity</tls_psk_identity>
   <tls_psk>FFFFFF</tls_psk>
   ...
 </host>
 ...

Translation strings

  • Certificate
  • Connections from host
  • Connections from proxy
  • Connections to host
  • Connections to proxy
  • Encryption
  • Incorrect value used for PSK field. Only hexadecimal characters are supported.
  • Issuer
  • No encryption
  • PSK
  • CERT
  • PSK cannot be empty.
  • PSK identity
  • PSK identity cannot be empty.

Database changes

The following fields will be added to hosts table:

FIELD  |tls_connect      |t_integer       |'1' |NOT NULL   |ZBX_PROXY
FIELD  |tls_accept       |t_integer       |'1' |NOT NULL   |ZBX_PROXY
FIELD  |tls_issuer       |t_varchar(1024) |''  |NOT NULL   |ZBX_PROXY   // By whom the certificate should be issued.
FIELD  |tls_subject      |t_varchar(1024) |''  |NOT NULL   |ZBX_PROXY   // To whom the certificate should be issued.
FIELD  |tls_psk_identity |t_varchar(128)  |''  |NOT NULL   |ZBX_PROXY   // For storing PSK-identity as UTF-8 string.
FIELD  |tls_psk          |t_varchar(512)  |''  |NOT NULL   |ZBX_PROXY   // For storing PSK as a hex-encoded string.

Outgoing connections from

  • server to a passive proxy
  • server or proxy to an agent (for passive checks)

will be specified by the value of tls_connect field.

Acceptable incoming connections from

  • active proxies to server
  • active agents to server/proxy (for active checks)
  • zabbix_sender to server/proxy (for trapper items)

will be specified by the value of tls_accept field.

tls_connect and tls_accept fields use the 3 least significant bits to encode values (0 - no, 1 - yes):

b2 b1 b0
 |  |  \- unencrypted
 |  \---- TLS with PSK
 \------- TLS with certificate

For tls_connect field exactly 1 of the 3 bits must be set to 1.

For tls_accept field at least 1 of the 3 bits must be set to 1.

Default value for tls_connect and tls_accept fields is 1 (connect/accept unencrypted).

Documentation

Out of scope

Java gateway component is currently out of scope.

Opening TCP connections with resuming of TLS session (by using session caching or session tickets) is currently out of scope.

zabbix_agent (started from inetd) will not support encryption.

Matching of Issuer, Subject and PSK Identity strings according to RFC 4517 and RFC 4518 is currently out of scope. Exact string matching will be used instead.

MS Windows Zabbix sender DLL library component is currently out of scope.

ChangeLog

  • 2015.02.23 TLSCaPath configuration parameter removed because GnuTLS versions on major Linux distributions do not yet support gnutls_certificate_set_x509_trust_dir() function.
  • 2015.05.29 Encryption tab for hosts and proxies in PHP frontend - added enable/disable and validation rules.
  • 2015.06.05 Encryption tab for hosts and proxies in PHP frontend - changed field names, show/hide and validation rules.
  • 2015.06.09 Added new section Changes in commandline options describing zabbix_sender and zabbix_get new options.
  • 2015.06.17 Renamed some zabbix_get and zabbix_sender commandline options.
  • 2015.06.27 Minimum supported version of PolarSSL/mbed TLS set to 1.3.9.
  • 2015.07.08 Minimum supported version of GnuTLS set to 3.1.18, OpenSSL set to 1.0.1e. Certificate types limited to RSA.
  • 2015.07.16 Minimum supported version of OpenSSL set to 1.0.1.
  • 2015.08.04 mbed TLS 2.x initially not supported.