��Ĳ�

Table of Contents

1 Using certificates

1 Using certificates

Overview

��Ĳ� can use RSA certificates in PEM format, signed by a public or an in-house certificate authority (CA).

Certificate verification is performed against a pre-configured CA certificate. Optionally, Certificate Revocation Lists (CRL) can be used.

Each ��Ĳ� component can have only one certificate configured.

For more information on setting up and operating an internal CA, generating and signing certificate requests, and revoking certificates, refer to tutorials such as the .

Carefully consider and test your certificate extensions. For more details, see Limitations on using X.509 v3 certificate extensions.

Certificate configuration parameters

The following configuration parameters are supported for setting up certificates on ��Ĳ� components.

Parameter	Mandatory	Description
TLSCAFile	yes	Full pathname of a file containing the top-level CA(s) certificates for peer certificate verification. If using a certificate chain with multiple members, order the certificates with lower level CA(s) certificates first, followed by higher level CA(s) certificates. Certificates from multiple CAs can be included in a single file.
TLSCRLFile	no	Full pathname of a file containing Certificate Revocation Lists (CRL).
TLSCertFile	yes	Full pathname of a file containing the certificate. If using a certificate chain with multiple members, order the certificates with the server, proxy, or agent certificate first, followed by lower level CA(s) certificates, and concluded by higher level CA(s) certificates.
TLSKeyFile	yes	Full pathname of a file containing the private key. Ensure that this file is readable only by the ��Ĳ� user by setting appropriate access rights.
TLSServerCertIssuer	no	Allowed server certificate issuer.
TLSServerCertSubject	no	Allowed server certificate subject.

Configuration examples

After setting up the necessary certificates, configure ��Ĳ� components to use certificate-based encryption.

Below are detailed steps for configuring:

��Ĳ� server
��Ĳ� proxy
��Ĳ� agent

��Ĳ� server

1. Prepare the CA certificate file.

In order to verify peer certificates, ��Ĳ� server must have access to the file containing the top-level, self-signed root CA certificates. For example, if certificates from two independent root CAs are needed, place them into a file at /home/zabbix/zabbix_ca_file.crt:

Certificate:
           Data:
               Version: 3 (0x2)
               Serial Number: 1 (0x1)
           Signature Algorithm: sha1WithRSAEncryption
               Issuer: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=Root1 CA
                   ...
               Subject: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=Root1 CA
               Subject Public Key Info:
                   Public Key Algorithm: rsaEncryption
                       Public-Key: (2048 bit)
                   ...
               X509v3 extensions:
                   X509v3 Key Usage: critical
                       Certificate Sign, CRL Sign
                   X509v3 Basic Constraints: critical
                       CA:TRUE
                   ...
       -----BEGIN CERTIFICATE-----
       MIID2jCCAsKgAwIBAgIBATANBgkqhkiG9w0BAQUFADB+MRMwEQYKCZImiZPyLGQB
       ....
       9wEzdN8uTrqoyU78gi12npLj08LegRKjb5hFTVmO
       -----END CERTIFICATE-----
       Certificate:
           Data:
               Version: 3 (0x2)
               Serial Number: 1 (0x1)
           Signature Algorithm: sha1WithRSAEncryption
               Issuer: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=Root2 CA
                   ...
               Subject: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=Root2 CA
               Subject Public Key Info:
                   Public Key Algorithm: rsaEncryption
                       Public-Key: (2048 bit)
                   ....
               X509v3 extensions:
                   X509v3 Key Usage: critical
                       Certificate Sign, CRL Sign
                   X509v3 Basic Constraints: critical
                       CA:TRUE
                   ....       
       -----BEGIN CERTIFICATE-----
       MIID3DCCAsSgAwIBAgIBATANBgkqhkiG9w0BAQUFADB/MRMwEQYKCZImiZPyLGQB
       ...
       vdGNYoSfvu41GQAR5Vj5FnRJRzv5XQOZ3B6894GY1zY=
       -----END CERTIFICATE-----

2. Place the ��Ĳ� server certificate/certificate chain into a file, for example, at /home/zabbix/zabbix_server.crt. The first certificate is the ��Ĳ� server certificate, followed by the intermediate CA certificate:

Certificate:
           Data:
               Version: 3 (0x2)
               Serial Number: 1 (0x1)
           Signature Algorithm: sha1WithRSAEncryption
               Issuer: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=Signing CA
               ...
               Subject: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=�����Ĳ� server
               Subject Public Key Info:
                   Public Key Algorithm: rsaEncryption
                       Public-Key: (2048 bit)
                       ...
               X509v3 extensions:
                   X509v3 Key Usage: critical
                       Digital Signature, Key Encipherment
                   X509v3 Basic Constraints: 
                       CA:FALSE
                   ...
       -----BEGIN CERTIFICATE-----
       MIIECDCCAvCgAwIBAgIBATANBgkqhkiG9w0BAQUFADCBgTETMBEGCgmSJomT8ixk
       ...
       h02u1GHiy46GI+xfR3LsPwFKlkTaaLaL/6aaoQ==
       -----END CERTIFICATE-----
       Certificate:
           Data:
               Version: 3 (0x2)
               Serial Number: 2 (0x2)
           Signature Algorithm: sha1WithRSAEncryption
               Issuer: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=Root1 CA
               ...
               Subject: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=Signing CA
               Subject Public Key Info:
                   Public Key Algorithm: rsaEncryption
                       Public-Key: (2048 bit)
                   ...
               X509v3 extensions:
                   X509v3 Key Usage: critical
                       Certificate Sign, CRL Sign
                   X509v3 Basic Constraints: critical
                       CA:TRUE, pathlen:0
               ...
       -----BEGIN CERTIFICATE-----
       MIID4TCCAsmgAwIBAgIBAjANBgkqhkiG9w0BAQUFADB+MRMwEQYKCZImiZPyLGQB
       ...
       dyCeWnvL7u5sd6ffo8iRny0QzbHKmQt/wUtcVIvWXdMIFJM0Hw==
       -----END CERTIFICATE-----

Use only the attributes mentioned above for both client and server certificates to avoid affecting the certificate verification process. For example, OpenSSL might fail to establish an encrypted connection if X509v3 Subject Alternative Name or Netscape Cert Type extensions are used. For more information, see Limitations on using X.509 v3 certificate extensions.

3. Place the ��Ĳ� server private key into a file, for example, at /home/zabbix/zabbix_server.key:

-----BEGIN PRIVATE KEY-----
       MIIEwAIBADANBgkqhkiG9w0BAQEFAASCBKowggSmAgEAAoIBAQC9tIXIJoVnNXDl
       ...
       IJLkhbybBYEf47MLhffWa7XvZTY=
       -----END PRIVATE KEY-----

4. Edit the TLS configuration parameters in the ��Ĳ� server configuration file:

TLSCAFile=/home/zabbix/zabbix_ca_file
       TLSCertFile=/home/zabbix/zabbix_server.crt
       TLSKeyFile=/home/zabbix/zabbix_server.key

��Ĳ� proxy

1. Prepare files with the top-level CA certificates, the ��Ĳ� proxy certificate/certificate chain, and the private key as described in the ��Ĳ� server section. Then, edit the TLSCAFile, TLSCertFile, and TLSKeyFile parameters in the ��Ĳ� proxy configuration file accordingly.

2. Edit additional TLS parameters in the ��Ĳ� proxy configuration file:

For active proxy: TLSConnect=cert
For passive proxy: TLSAccept=cert

To improve proxy security, you can also set the TLSServerCertIssuer and TLSServerCertSubject parameters. For more information, see Restricting allowed certificate issuer and subject.

TLS parameters in the final proxy configuration file may look as follows:

TLSConnect=cert
       TLSAccept=cert
       TLSCAFile=/home/zabbix/zabbix_ca_file
       TLSServerCertIssuer=CN=Signing CA,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com
       TLSServerCertSubject=CN=�����Ĳ� server,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com
       TLSCertFile=/home/zabbix/zabbix_proxy.crt
       TLSKeyFile=/home/zabbix/zabbix_proxy.key

3. Configure encryption for this proxy in ��Ĳ� frontend:

Go to: Administration �� Proxies.
Select the proxy and click the Encryption tab.

In the examples below, the Issuer and Subject fields are filled in. For more information on why and how to use these fields, see Restricting allowed certificate issuer and subject.

For active proxy:

For passive proxy:

��Ĳ� agent

1. Prepare files with the top-level CA certificates, the ��Ĳ� agent certificate/certificate chain, and the private key as described in the ��Ĳ� server section. Then, edit the TLSCAFile, TLSCertFile, and TLSKeyFile parameters in the ��Ĳ� agent configuration file accordingly.

2. Edit additional TLS parameters in the ��Ĳ� agent configuration file:

For active agent: TLSConnect=cert
For passive agent: TLSAccept=cert

To improve agent security, you can set the TLSServerCertIssuer and TLSServerCertSubject parameters. For more information, see Restricting allowed certificate issuer and subject.

The TLS parameters in the final agent configuration file may look as follows. Note that the example assumes that the host is monitored by a proxy, hence it is specified as the certificate Subject:

TLSConnect=cert
       TLSAccept=cert
       TLSCAFile=/home/zabbix/zabbix_ca_file
       TLSServerCertIssuer=CN=Signing CA,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com
       TLSServerCertSubject=CN=�����Ĳ� proxy,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com
       TLSCertFile=/home/zabbix/zabbix_agentd.crt
       TLSKeyFile=/home/zabbix/zabbix_agentd.key

3. Configure encryption in ��Ĳ� frontend for the host monitored by this agent.

Go to: Data collection �� Hosts.
Select the host and click the Encryption tab.

In the example below, the Issuer and Subject fields are filled in. For more information on why and how to use these fields, see Restricting allowed certificate issuer and subject.

��Ĳ� web service

1. Prepare files with the top-level CA certificates, the ��Ĳ� web service certificate/certificate chain, and the private key as described in the ��Ĳ� server section. Then, edit the TLSCAFile, TLSCertFile, and TLSKeyFile parameters in the ��Ĳ� web service configuration file accordingly.

2. Edit an additional TLS parameter in the ��Ĳ� web service configuration file: TLSAccept=cert

TLS parameters in the final web service configuration file may look as follows:

TLSAccept=cert
       TLSCAFile=/home/zabbix/zabbix_ca_file
       TLSCertFile=/home/zabbix/zabbix_web_service.crt
       TLSKeyFile=/home/zabbix/zabbix_web_service.key

3. Configure ��Ĳ� server to connect to the TLS-configured ��Ĳ� web service by editing the WebServiceURL parameter in the ��Ĳ� server configuration file:

WebServiceURL=https://example.com

Restricting allowed certificate issuer and subject

When two ��Ĳ� components (for example, server and agent) establish a TLS connection, they validate each other's certificates. If a peer certificate is signed by a trusted CA (with a pre-configured top-level certificate in TLSCAFile), is valid, has not expired, and passes other checks, then the communication between components can proceed. In this simplest case, the certificate issuer and subject are not verified.

However, this presents a risk: anyone with a valid certificate can impersonate anyone else (for example, a host certificate could be used to impersonate a server). While this may be acceptable in small environments where certificates are signed by a dedicated in-house CA and the risk of impersonation is low, it may not be sufficient in larger or more security-sensitive environments.

If your top-level CA issues certificates that should not be accepted by ��Ĳ� or if you want to reduce the risk of impersonation, you can restrict allowed certificates by specifying their issuer and subject.

For example, in the ��Ĳ� proxy configuration file, you could specify:

TLSServerCertIssuer=CN=Signing CA,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com
       TLSServerCertSubject=CN=�����Ĳ� server,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com

With these settings, an active proxy will not communicate with a ��Ĳ� server whose certificate has a different issuer or subject. Similarly, a passive proxy will not accept requests from such a server.

Rules for matching `Issuer` and `Subject` strings

The rules for matching Issuer and Subject strings are as follows:

Issuer and Subject strings are checked independently. Both are optional.
An unspecified string means that any string is accepted.
Strings are compared as is and must match exactly.
UTF-8 characters are supported. However, wildcards (*) or regular expressions are not supported.
The following requirements are implemented - characters that require escaping (with a '\' backslash, U+005C):
- anywhere in the string: '"' (U+0022), '+' (U+002B), ',' (U+002C), ';' (U+003B), '<' (U+003C), '>' (U+003E), '\\' (U+005C);
- at the beginning of the string: space (' ', U+0020) or number sign ('#', U+0023);
- at the end of the string: space (' ', U+0020).
Null characters (U+0000) are not supported. If a null character is encountered, the matching will fail.
and standards are not supported.

For example, if Issuer and Subject organization (O) strings contain trailing spaces and the Subject organizational unit (OU) string contains double quotes, these characters must be escaped:

TLSServerCertIssuer=CN=Signing CA,OU=Development head,O=\ Example SIA\ ,DC=example,DC=com
       TLSServerCertSubject=CN=�����Ĳ� server,OU=Development group \"5\",O=\ Example SIA\ ,DC=example,DC=com

Field order and formatting

��Ĳ� follows the recommendations of , which specifies a "reverse" order for these fields, starting with the lowest-level fields (CN), proceeding to the mid-level fields (OU, O), and concluding with the highest-level fields (DC).

TLSServerCertIssuer=CN=Signing CA,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com
       TLSServerCertSubject=CN=�����Ĳ� proxy,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com

In contrast, OpenSSL by default displays the Issuer and Subject strings in top-level to low-level order. In the following example, Issuer and Subject fields start with the top-level (DC) and end with the low-level (CN) field. The formatting with spaces and field separators also varies based on the options used, and thus will not match the format required by ��Ĳ�.

$ openssl x509 -noout -in /home/zabbix/zabbix_proxy.crt -issuer -subject
       issuer= /DC=com/DC=zabbix/O=�����Ĳ� SIA/OU=Development group/CN=Signing CA
       subject= /DC=com/DC=zabbix/O=�����Ĳ� SIA/OU=Development group/CN=�����Ĳ� proxy
       
       $ openssl x509 -noout -text -in /home/zabbix/zabbix_proxy.crt
       Certificate:
           ...
               Issuer: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=Signing CA
               ...
               Subject: DC=com, DC=zabbix, O=�����Ĳ� SIA, OU=Development group, CN=�����Ĳ� proxy

To format Issuer and Subject strings correctly for ��Ĳ�, invoke OpenSSL with the following options:

$ openssl x509 -noout -issuer -subject \
           -nameopt esc_2253,esc_ctrl,utf8,dump_nostr,dump_unknown,dump_der,sep_comma_plus,dn_rev,sname\
           -in /home/zabbix/zabbix_proxy.crt

The output will then be in reverse order, comma-separated, and usable in ��Ĳ� configuration files and frontend:

issuer= CN=Signing CA,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com
       subject= CN=�����Ĳ� proxy,OU=Development group,O=�����Ĳ� SIA,DC=zabbix,DC=com

Limitations on using X.509 v3 certificate extensions

When implementing X.509 v3 certificates within ��Ĳ�, certain extensions may not be fully supported or could result in inconsistent behavior.

Subject Alternative Name extension

��Ĳ� does not support the Subject Alternative Name extension, which is used to specify alternative DNS names such as IP addresses or email addresses. ��Ĳ� can only validate the value in the Subject field of the certificate (see Restricting Allowed Certificate Issuer and Subject). If certificates include the subjectAltName field, the outcome of certificate validation may vary depending on the specific crypto toolkits used to compile ��Ĳ� components. As a result, ��Ĳ� may either accept or reject certificates based on these combinations.

Extended Key Usage extension

��Ĳ� supports the Extended Key Usage extension. However, if used, it is generally required that both clientAuth (for TLS WWW client authentication) and serverAuth (for TLS WWW server authentication) attributes are specified. For example:

In passive checks, where ��Ĳ� agent operates as a TLS server, the serverAuth attribute must be included in the agent's certificate.
For active checks, where the agent operates as a TLS client, the clientAuth attribute must be included in the agent's certificate.

While GnuTLS may issue a warning for key usage violations, it typically allows communication to proceed despite these warnings.

Name Constraints extension

Support for the Name Constraints extension varies among crypto toolkits. Ensure that your chosen toolkit supports this extension. This extension may restrict ��Ĳ� from loading CA certificates if this section is marked as critical, depending on the specific toolkit in use.

Certificate Revocation Lists (CRL)

If a certificate is compromised, the Certificate Authority (CA) can revoke it by including the certificate in a Certificate Revocation List (CRL). CRLs are managed through configuration files and can be specified using the TLSCRLFile parameter in server, proxy, and agent configuration files. For example:

TLSCRLFile=/home/zabbix/zabbix_crl_file.crt

In this case, zabbix_crl_file.crt may contain CRLs from multiple CAs, and could look like this:

-----BEGIN X509 CRL-----
       MIIB/DCB5QIBATANBgkqhkiG9w0BAQUFADCBgTETMBEGCgmSJomT8ixkARkWA2Nv
       ...
       treZeUPjb7LSmZ3K2hpbZN7SoOZcAoHQ3GWd9npuctg=
       -----END X509 CRL-----
       -----BEGIN X509 CRL-----
       MIIB+TCB4gIBATANBgkqhkiG9w0BAQUFADB/MRMwEQYKCZImiZPyLGQBGRYDY29t
       ...
       CAEebS2CND3ShBedZ8YSil59O6JvaDP61lR5lNs=
       -----END X509 CRL-----

The CRL file is loaded only when ��Ĳ� starts. To update the CRL, restart ��Ĳ�.

If ��Ĳ� components are compiled with OpenSSL and CRLs are used, ensure that each top-level and intermediate CA in the certificate chains has a corresponding CRL (even if it is empty) included in the TLSCRLFile.

�����Ĳ�

Documentation