Table of Contents

1 使用证书

1 使用证书

概览

Zabbix可以使用PEM格式的RSA证书，由公共或内部认证机构（CA）签名。根据预先配置的CA证书进行证书验证。不支持自签名证书。可以选择使用证书撤销列表（CRL）。每个Zabbix组件只能配置一个证书。

有关如何设置和操作内部CA的更多信息，如何生成证书请求并签名，如何撤销证书，您可以找到许多在线操作，例如 OpenSSL PKI Tutorialv1.1 .

证书配置参数

参数	是否必须	描述
TLSCAFile	yes	包含用于对等证书验证的顶级CA证书的文件的完整路径名。在具有多个成员的证书链的情况下，它们必须被排序：较低级别的CA证书，然后是较高级别的CA证书。来自多个CA的证书可以包含在单个文件中。
TLSCRLFile	no	包含证书吊销列表的文件的完整路径名。看证书吊销清单 (CRL)。
TLSCertFile	yes	包含证书（证书链）的文件的完整路径名。在有几个成员的证书链中，它们必须排序:首先是server、proxy或agent证书，然后是低级CA证书，然后是高级CA证书。
TLSKeyFile	yes	包含私钥的文件的完整路径名。设置此文件的访问权限—它必须只有Zabbix用户可读。
TLSServerCertIssuer	no	-允许的服务器证书颁发者。
TLSServerCertSubject	no	允许的服务器证书主题。

Configuration examples

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

Below are detailed steps for configuring:

Zabbix server
Zabbix proxy
Zabbix agent

在Zabbix server上配置证书

1. 为了验证对等证书，Zabbix server必须有权访问具有顶级自签名根CA证书的文件。例如，如果我们期望来自两个独立的根ca的证书，我们可以将它们的证书放入文件“/home/zabbix/zabbi_ca_file”中，如下所示：

Certificate:
           Data:
               Version: 3 (0x2)
               Serial Number: 1 (0x1)
           Signature Algorithm: sha1WithRSAEncryption
               Issuer: DC=com, DC=zabbix, O=Zabbix SIA, OU=Development group, CN=Root1 CA
                   ...
               Subject: DC=com, DC=zabbix, O=Zabbix 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=Zabbix SIA, OU=Development group, CN=Root2 CA
                   ...
               Subject: DC=com, DC=zabbix, O=Zabbix 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. 将Zabbix server证书链放入文件中，例如， /home/zabbix/zabbix_server.crt:

Certificate:
           Data:
               Version: 3 (0x2)
               Serial Number: 1 (0x1)
           Signature Algorithm: sha1WithRSAEncryption
               Issuer: DC=com, DC=zabbix, O=Zabbix SIA, OU=Development group, CN=Signing CA
               ...
               Subject: DC=com, DC=zabbix, O=Zabbix SIA, OU=Development group, CN=Zabbix 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=Zabbix SIA, OU=Development group, CN=Root1 CA
               ...
               Subject: DC=com, DC=zabbix, O=Zabbix 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-----

这里第一个是Zabbix server证书，然后是中间CA证书。

不鼓励客户端和服务器证书使用除上述属性之外的任何属性，因为这可能会影响证书验证过程。例如，如果设置了X509v3扩展密钥用法或Netscape证书类型，OpenSSL可能无法建立加密连接。另请参阅：使用X.509 v3证书扩展的限制。

3. 例如，将Zabbix server私钥放入文件中， /home/zabbix/zabbix_server.key:

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

4. 在Zabbix server配置文件中编辑TLS参数，如下所示：

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

为Zabbix proxy配置基于证书的加密

1. 准备具有顶级CA证书、代理证书的文件（链）和私钥，如在Zabbixserver上配置证书中所述。编辑参数 TLSCAFile, TLSCertFile, TLSKeyFile 在 proxy 相应地配置。

2. 对于主动模式 proxy 编辑 TLSConnect 参数:

TLSConnect=cert

对于被动模式 proxy 编辑 TLSAccept 参数:

TLSAccept=cert

3. 现在您有了一个最小的基于证书的proxy配置。您可能更愿意通过设置“TLSServerCertIssuer”和“TLSServer CertSubject”参数来提高proxy安全性（请参阅限制允许的证书颁发者和主题 )。

4. 在正确的proxy配置文件中，TLS参数可能如下所示：

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

5. 在Zabbix前端为此proxy配置加密：

前往: Administration → Proxies
选择proxy并点击 Encryption 选项

在以下示例中，填写了Issuer和Subject字段-请参阅限制允许的证书颁发者和主题为什么以及如何使用这些字段。

对主动模式 proxy

对被动模式 proxy

Zabbix agent配置基于证书的加密

1.使用顶级CA证书，代理证书（链）和私钥准备文件，如在Zabbix server配置证书中所述。编辑参数TLSCAFile，TLSCertFile，TLSKeyFile在agent配置相应。

2. 对于主动模式检查编辑TLSConnect参数：

TLSConnect=cert

对于被动模式检查编辑TLSAccept参数：

TLSAccept=cert

3.现在，您有一个基于证书的最小agent配置。您可能希望通过设置TLSServerCertIssuer和TLSServerCertSubject参数提高agent安全性。(请参阅限制允许的证书发行者和主体)。

4. 在最终agent配置文件中，TLS参数可能如下所示：

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

(例如，假设主机是通过proxy监视的，因此是proxy证书主体。)

5. 在Zabbix前端为此agent配置加密：

前往: Configuration → Hosts
选择主机然后点击加密选项卡

在下面的示例中，发行者和主体字段填写 - 请参阅限制允许的证书发行者和主体原因以及如何使用这些字段。

Zabbix web service

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

2. Edit an additional TLS parameter in the Zabbix 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 Zabbix server to connect to the TLS-configured Zabbix web service by editing the WebServiceURL parameter in the Zabbix server configuration file:

WebServiceURL=https://example.com

限制允许的证书发行者和主体

当两个Zabbix组件（例如服务端和agent）建立TLS连接时，他们会检查对方的证书。如果对等证书由受信任的CA（具有预先配置的顶级证书TLSCAFile）签名有效，尚未过期且通过其他检查项，则可以进行通信。在最简单的情况下，不会检查证书发行者和主体。

这存在一个风险 - 任何拥有有效证书的人都可以冒充任何人（例如，主机证书可以用来模拟服务器）。在内部CA签发证书的小型环境中，这种风险可能是可以接受的，冒充的风险较低。

如果您的顶级CA用于签发其他证书而不应被Zabbix接受，或者你想降低冒充风险，您可以通过指定其发行者(Issuer)和主体(Subject)字符串来限制允许的证书。

例如，您可以在Zabbix proxy配置文件中写：

TLSServerCertIssuer=CN=Signing CA,OU=Development group,O=Zabbix SIA,DC=zabbix,DC=comTLSServerCertSubject=CN=Zabbix server,OU=Development group,O=Zabbix SIA,DC=zabbix,DC=com

通过这些设置，主动proxy将不会与证书中具有不同发行者或主体字符串的Zabbix server通信，被动proxy将不接受来自此类服务器的请求。

有关发行者或主体字符串匹配的说明：

独立检查发行者和主体字符串。两者都是可选的。
允许使用UTF-8字符。
未指定的字符串等同于任何字符串都被接受。
字符串按“原样”比较，它们必须完全一致才能匹配。
不支持通配符和正则表达式。
仅实现了RFC 4514轻量级目录访问协议(LDAP):可区分名称的字符串表示中的一些要求:
1. 转义字符 '"' (U+0022), '+' U+002B, ',' U+002C, ';' U+003B, '<' U+003C, '>' U+003E, '\' U+005C 在字符串中的任何地方。
2. 字符串开头的转义字符空格(' ' U+0020)或数字符号('#' U+0023)。
3. 转义字符空间(' ' U+0020)在字符串的结尾。
如果遇到空字符(U+0000) (RFC4514允许)，则匹配失败。
由于工作量太大，不支持RFC 4517轻量级目录访问协议(LDAP):语法和匹配规则和RFC 4518轻量级目录访问协议(LDAP):国际化字符串准备的要求。

颁发者和主题字符串中的字段顺序和格式都很重要! Zabbix遵循RFC 4514的建议，并使用字段的“倒序”。

相反的顺序可以通过下面的例子来说明:

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

注意，它以低级别(CN)字段开始，然后到中级(OU, O)字段，最后以顶级(DC)字段结束。

OpenSSL默认显示证书颁发者和主题字段的“正常”顺序，取决于使用的其他选项:

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

在这里，Issuer和Subject字符串以顶级字段(DC)开始，以低级字段(CN)结束，空格和字段分隔符取决于所使用的选项。这些值在Zabbix发行人和主题字段中都不匹配!

要获得在Zabbix中可用的正确的发行者和主题字符串，需要使用特殊选项调用OpenSSL -nameopt esc_2253,esc_ctrl,utf8,dump_nostr,dump_unknown,dump_der,sep_comma_plus,dn_rev,sname:

$ 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
       issuer= CN=Signing CA,OU=Development group,O=Zabbix SIA,DC=zabbix,DC=com
       subject= CN=Zabbix proxy,OU=Development group,O=Zabbix SIA,DC=zabbix,DC=com

现在字符串字段是倒序的，字段是用逗号分隔的，可以在Zabbix配置文件和前端使用。

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 RFC 4514 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.
RFC 4517 and RFC 4518 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=Zabbix server,OU=Development group \"5\",O=\ Example SIA\ ,DC=example,DC=com

Field order and formatting

Zabbix follows the recommendations of RFC 4514, 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=Zabbix SIA,DC=zabbix,DC=com
       TLSServerCertSubject=CN=Zabbix proxy,OU=Development group,O=Zabbix 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 Zabbix.

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

To format Issuer and Subject strings correctly for Zabbix, 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 Zabbix configuration files and frontend:

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

使用X.509 v3证书扩展的限制

主题备用名称（subjectAltName） 扩展名。
Zabbix不支持来自_subjectAltName_扩展名的替代主体名称（如IP地址，电子邮件地址）。只能在Zabbix中检查“主体”字段的值（请参阅限制允许的证书发行者和主体）。如果证书使用_subjectAltName_扩展名，那么结果取决于加密工具包的特定组合。Zabbix组件被编译（可能工作或不工作，Zabbix可能拒绝接受来自对等体的证书）
扩展密钥使用扩展。
如果使用，则通常需要 clientAuth（TLS WWW客户端身份验证）和serverAuth（TLS WWW服务器身份验证）。
例如，被动检查的zabbix agent是作为TLS服务器，所以"serverAuth必须在agent证书设置。对于主动检查agent证书需要clientAuth进行设置。GnuTLS*在违规使用情况下发出警告，但允许通信进行。
名称限制扩展。
并不是所有的加密工具包都支持它。此扩展可能会阻止Zabbix加载CA证书，此部分被标记为_关键(critical)（取决于特定的加密工具包）。

证书吊销列表（CRL）

如果证书被破坏，CA可以通过将其包括在CRL中来撤销它。CRL可以使用参数“TLSCRLFile”在server、proxy和agent配置文件中配置。例如

TLSCRLFile=/home/zabbix/zabbix_crl_file

其中“zabbix_crl_file”可能包含来自几个CAs的CRLs，参考如下：

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

CRL文件仅在Zabbix启动时加载。CRL更新需要重新启动。

如果Zabbix组件是用OpenSSL编译的，并且使用了CRL，那么证书链中的每个顶级和中级CA都必须在“TLSCRLFile”中具有相应的CRL（可以为空）。

Documentation