Parameter	Mandatory	Description
TLSCAFile	yes	包含用于对等证书验证的顶级 CA 证书的文件完整路径名。如果使用包含多个成员的证书链，请将较低级别的 CA 证书排在前面，然后是较高级别的 CA 证书。来自多个 CA 的证书可以包含在同一个文件中。
TLSCRLFile	no	包含证书吊销列表（CRL）的文件完整路径名。
TLSCertFile	yes	包含证书的文件完整路径名。如果使用包含多个成员的证书链，请将 server、proxy 或 agent 证书排在前面，然后是较低级别的 CA 证书，最后是较高级别的 CA 证书。
TLSKeyFile	yes	包含私钥的文件完整路径名。请通过设置适当的访问权限，确保只有 Zabbix 用户可以读取此文件。
TLSServerCertIssuer	no	允许的 server 证书颁发者。
TLSServerCertSubject	no	允许的 server 证书主题。

配置示例

在设置好必要的证书后，配置 Zabbix 组件使用基于证书的加密。

以下是配置的详细步骤：

Zabbix 服务器
Zabbix proxy
Zabbix agent

Zabbix 服务器

1. 准备 CA 证书文件。

为了验证对端证书，Zabbix 服务器必须能够访问包含顶级自签名根 CA 证书的文件。例如，如果需要来自两个独立根 CA 的证书，请将它们放入 /home/zabbix/zabbix_ca_file.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=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 服务器证书/证书链放入文件中，例如 /home/zabbix/zabbix_server.crt。第一个证书是 Zabbix 服务器证书，后面跟随中间 CA 证书：

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-----

客户端和服务器证书都只使用上述提到的属性，以避免影响证书验证过程。例如，如果使用 X509v3 Subject Alternative Name 或 Netscape Cert Type 扩展，OpenSSL 可能无法建立加密连接。有关更多信息，请参见 X.509 v3 证书扩展的使用限制。

3. 将 Zabbix 服务器私钥放入文件中，例如 /home/zabbix/zabbix_server.key：

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

4. 编辑 Zabbix 服务器配置文件中的 TLS 配置参数：

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

Zabbix proxy

1. 按照 Zabbix 服务器部分中的说明，准备顶级 CA 证书、Zabbix proxy 证书/证书链以及私钥文件。
然后，在 Zabbix proxy 配置文件中相应编辑 TLSCAFile、TLSCertFile 和 TLSKeyFile 参数。

2. 在 Zabbix proxy 配置文件中编辑其他 TLS 参数：

对于主动 proxy：TLSConnect=cert
对于被动 proxy：TLSAccept=cert

为提高 proxy 安全性，您还可以设置 TLSServerCertIssuer 和 TLSServerCertSubject 参数。
更多信息，请参见限制允许的证书颁发者和主题。

最终 proxy 配置文件中的 TLS 参数可能如下所示：

TLSConnect=cert
TLSAccept=cert
TLSCAFile=/home/zabbix/zabbix_ca_file.crt
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

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

转到：Administration > Proxies。
选择该 proxy，然后单击 Encryption 选项卡。

下面的示例中已填写 Issuer 和 Subject 字段。
有关为何以及如何使用这些字段的更多信息，请参见限制允许的证书颁发者和主题。

对于主动 proxy：

对于被动 proxy：

Zabbix agent

1. 按照 Zabbix 服务器部分中的说明，准备包含顶级 CA 证书、Zabbix agent 证书/证书链以及私钥的文件。
然后，相应地编辑 Zabbix agent 配置文件中的 TLSCAFile、TLSCertFile 和 TLSKeyFile 参数。

2. 编辑 Zabbix agent 配置文件中的其他 TLS 参数：

对于主动 agent：TLSConnect=cert
对于被动 agent：TLSAccept=cert

为提高 agent 安全性，您可以设置 TLSServerCertIssuer 和 TLSServerCertSubject 参数。
有关更多信息，请参见限制允许的证书颁发者和主题。

最终 agent 配置文件中的 TLS 参数可能如下所示。
请注意，此示例假定该主机由 proxy 监控，因此将其指定为证书 Subject：

TLSConnect=cert
TLSAccept=cert
TLSCAFile=/home/zabbix/zabbix_ca_file.crt
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

3. 为由此 agent 监控的主机在 Zabbix 前端中配置加密。

转到：数据采集 > 主机。
选择该主机并单击加密选项卡。

在下面的示例中，Issuer 和 Subject 字段已填写。
有关为何以及如何使用这些字段的更多信息，请参见限制允许的证书颁发者和主题。

Zabbix web service

1. 按照 Zabbix 服务器部分中的说明，准备顶级 CA 证书、Zabbix web service 证书/证书链以及私钥文件。
然后，在 Zabbix web service 配置文件中相应地编辑 TLSCAFile、TLSCertFile 和 TLSKeyFile 参数。

2. 在 Zabbix web service 配置文件中编辑一个额外的 TLS 参数：TLSAccept=cert

最终的 web service 配置文件中的 TLS 参数可能如下所示：

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

3. 通过编辑 Zabbix 服务器配置文件中的 WebServiceURL 参数，将 Zabbix 服务器配置为连接到已配置 TLS 的 Zabbix web service：

WebServiceURL=https://example.com:443/report

限制允许的证书颁发者和主题

当两个 Zabbix 组件（例如，服务器和 agent）建立 TLS 连接时，它们会相互验证对方的证书。如果对端证书由受信任的 CA 签名（在 TLSCAFile 中预先配置了顶级证书），证书有效、未过期，并且通过了其他检查，那么组件之间的通信就可以继续。在这种最简单的情况下，不会验证证书颁发者和主题。

不过，这会带来风险：任何持有有效证书的人都可以冒充其他人（例如，主机证书可用于冒充服务器）。在证书由专用的内部 CA 签发、且冒充风险较低的小型环境中，这可能是可以接受的，但在更大规模或更注重安全的环境中，这可能并不够。

如果您的顶级 CA 签发了一些不应被 Zabbix 接受的证书，或者您希望降低冒充风险，可以通过指定允许的证书颁发者和主题来限制可接受的证书。

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

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

使用这些设置后，主动 proxy 将不会与证书颁发者或主题不同的 Zabbix 服务器通信。同样，被动 proxy 也不会接受来自此类服务器的请求。

`Issuer` 和 `Subject` 字符串的匹配规则

Issuer 和 Subject 字符串的匹配规则如下：

Issuer 和 Subject 字符串分别独立检查。两者都是可选的。
未指定的字符串表示接受任意字符串。
字符串按原样比较，且必须完全匹配。
支持 UTF-8 字符。但是，不支持通配符（*）或正则表达式。
已实现以下 RFC 4514 要求 - 需要转义的字符（使用 \ 反斜杠，U+005C）：
- 在字符串中的任意位置："（U+0022）、+（U+002B）、,（U+002C）、;（U+003B）、<（U+003C）、>（U+003E）、\\（U+005C）；
- 在字符串开头：空格（`，U+0020）或数字符号（#`，U+0023）；
- 在字符串结尾：空格（，U+0020）。
不支持空字符（U+0000）。如果遇到空字符，匹配将失败。
不支持 RFC 4517 和 RFC 4518 标准。

例如，如果 Issuer 和 Subject 的组织（O）字符串包含尾随空格，且 Subject 的组织单位（OU）字符串包含双引号，则这些字符必须转义：

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

字段顺序和格式

Zabbix 遵循 RFC 4514 的建议，该规范为这些字段指定了“反向”顺序：从最低级别字段（CN）开始，依次到中间级别字段（OU、O），最后是最高级别字段（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

相比之下，OpenSSL 默认会以从高层到低层的顺序显示 Issuer 和 Subject 字符串。在下面的示例中，Issuer 和 Subject 字段以最高级别（DC）开头，以最低级别（CN）结尾。空格和字段分隔符的格式也会因所使用的选项而异，因此不会与 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

要为 Zabbix 正确格式化 Issuer 和 Subject 字符串，请使用以下选项调用 OpenSSL：

$ 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

这样输出将按反向顺序排列，以逗号分隔，并可用于 Zabbix 配置文件和前端：

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 证书扩展的限制

在 Zabbix 中实现 X.509 v3 证书时，某些扩展可能无法得到完全支持，或者可能导致行为不一致。

Subject Alternative Name 扩展

Zabbix 不支持 Subject Alternative Name 扩展，该扩展用于指定其他 DNS 名称，例如 IP 地址或电子邮件地址。 Zabbix 只能验证证书中 Subject 字段的值（请参见限制允许的证书颁发者和 Subject）。如果证书包含 subjectAltName 字段，证书验证结果可能会因用于编译 Zabbix 组件的具体加密工具包而异。因此，Zabbix 可能会根据这些组合接受或拒绝证书。

Extended Key Usage 扩展

Zabbix 支持 Extended Key Usage 扩展。不过，如果使用该扩展，通常要求同时指定 clientAuth（用于 TLS WWW 客户端认证）和 serverAuth（用于 TLS WWW 服务器认证）属性。例如：

在被动检查中，Zabbix agent 作为 TLS 服务器运行时，agent 证书中必须包含 serverAuth 属性。
在主动检查中，agent 作为 TLS 客户端运行时，agent 证书中必须包含 clientAuth 属性。

虽然 GnuTLS 可能会针对密钥用途违规发出警告，但通常仍会允许通信在这些警告下继续进行。

Name Constraints 扩展

对 Name Constraints 扩展的支持在不同加密工具包之间有所差异。请确保您所选用的工具包支持此扩展。根据所使用的具体工具包，如果该部分被标记为 critical，此扩展可能会限制 Zabbix 加载 CA 证书。

证书吊销列表（CRL）

如果证书已被泄露，证书颁发机构（CA）可以通过将该证书加入证书吊销列表（CRL）来吊销它。 CRL 通过配置文件进行管理，并且可以在服务器、proxy 和 agent 配置文件中使用 TLSCRLFile 参数指定。例如：

TLSCRLFile=/home/zabbix/zabbix_crl_file.crt

在这种情况下，zabbix_crl_file.crt 可能包含来自多个 CA 的 CRL，内容可能如下所示：

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

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

如果 Zabbix 组件使用 OpenSSL 编译，并且使用了 CRL，请确保证书链中的每个顶级 CA 和中间 CA 都在 TLSCRLFile 中包含对应的 CRL（即使该 CRL 为空）。

证书问题排查

OpenSSL 与 CRL 一起使用时，证书链中的某些 CA 的 CRL 未包含在 `TLSCRLFile` 中

在 OpenSSL 对端情况下，TLS 服务器日志中：

failed to accept an incoming connection: from 127.0.0.1: TLS handshake with 127.0.0.1 returned error code 1: \
    file s3_srvr.c line 3251: error:14089086: SSL routines:ssl3_get_client_certificate:certificate verify failed: \
    TLS write fatal alert "unknown CA"

在 GnuTLS 对端情况下，TLS 服务器日志中：

failed to accept an incoming connection: from 127.0.0.1: TLS handshake with 127.0.0.1 returned error code 1: \
    file rsa_pk1.c line 103: error:0407006A: rsa routines:RSA_padding_check_PKCS1_type_1:\
    block type is not 01 file rsa_eay.c line 705: error:04067072: rsa routines:RSA_EAY_PUBLIC_DECRYPT:paddin

CRL 已过期或在服务器运行期间过期

[OpenSSL]{.underline}，在服务器日志中：

过期前：

<!-- -->

cannot connect to proxy "proxy-openssl-1.0.1e": TCP successful, cannot establish TLS to [[127.0.0.1]:20004]:\
    SSL_connect() returned SSL_ERROR_SSL: file s3_clnt.c line 1253: error:14090086:\
    SSL routines:ssl3_get_server_certificate:certificate verify failed:\
    TLS write fatal alert "certificate revoked"

过期后：

<!-- -->

cannot connect to proxy "proxy-openssl-1.0.1e": TCP successful, cannot establish TLS to [[127.0.0.1]:20004]:\
    SSL_connect() returned SSL_ERROR_SSL: file s3_clnt.c line 1253: error:14090086:\
    SSL routines:ssl3_get_server_certificate:certificate verify failed:\
    TLS write fatal alert "certificate expired"

这里的关键点是：在 CRL 有效时，已吊销的证书会被报告为“certificate revoked”。当 CRL 过期时，错误信息会变为“certificate expired”，这相当误导。

[GnuTLS]{.underline}，在服务器日志中：

过期前后相同：

<!-- -->

cannot connect to proxy "proxy-openssl-1.0.1e": TCP successful, cannot establish TLS to [[127.0.0.1]:20004]:\
      invalid peer certificate: The certificate is NOT trusted. The certificate chain is revoked.

自签名证书，未知 CA

[OpenSSL]{.underline}，在日志中：

error:'self signed certificate: SSL_connect() set result code to SSL_ERROR_SSL: file ../ssl/statem/statem_clnt.c\
      line 1924: error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed:\
      TLS write fatal alert "unknown CA"'

当服务器证书由于误操作具有相同的 Issuer 和 Subject 字符串时，就会观察到这种情况，尽管它是由 CA 签名的。Issuer 和 Subject 在顶级 CA 证书中可以相同，但在服务器证书中不能相同。（这同样适用于 proxy 和 agent 证书。）

要检查证书是否包含相同的 Issuer 和 Subject 条目，请运行：

openssl x509 -in <yourcertificate.crt> -noout -text

根（顶级）证书的 Issuer 和 Subject 具有相同的值是可以接受的。

What’s next?

使用预共享密钥进行加密

Docs

使用证书进行加密

概述

证书配置参数