Table of Contents

1 使用证书

1 使用证书

概览

Zabbix 可以使用 PEM 格式的 RSA 证书，这些证书由公共或内部的证书颁发机构（CA）签发。

证书验证会针对预先配置的 CA 证书进行。可选地，可以使用证书吊销列表 (CRL)。

每个 Zabbix 组件只能配置一个证书。

有关设置和操作内部 CA、生成和签署证书请求以及撤销证书的更多信息，请参阅类似教程，如OpenSSL PKI 教程 v2.0。

仔细考虑并测试你的证书扩展。更多详情，请参见使用 X.509 v3 证书扩展的限制。

证书配置参数

以下配置参数支持在Zabbix组件上设置证书。

Parameter	Mandatory	Description
TLSCAFile	是	包含用于对等证书验证的顶级CA(s)证书的文件的完整路径名。如果使用包含多个成员的证书链，请先列出较低级别的CA(s)证书，然后是较高级别的CA(s)证书。可以将来自多个CAs的证书包含在单个文件中。
TLSCRLFile	否	包含证书撤销列表 (CRL)的文件的完整路径名。
TLSCertFile	是	包含证书的文件的完整路径名。如果使用包含多个成员的证书链，请先列出服务器、proxy或agent证书，然后是较低级别的CA(s)证书，最后是较高级别的CA(s)证书。
TLSKeyFile	是	包含私钥的文件的完整路径名。通过设置适当的访问权限，确保此文件仅可由Zabbix用户读取。
TLSServerCertIssuer	否	允许的服务器证书颁发者。
TLSServerCertSubject	否	允许的服务器证书主题。

配置示例

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

以下是详细步骤配置：

Zabbix server
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
       TLSCertFile=/home/zabbix/zabbix_server.crt
       TLSKeyFile=/home/zabbix/zabbix_server.key

Zabbix proxy

准备Top级CA证书文件，Zabbix proxy证书/证书链，以及私钥，具体如Zabbix server部分所述。然后，根据Zabbix proxy configuration file相应编辑TLSCAFile，TLSCertFile，和TLSKeyFile参数。
在Zabbix proxy configuration file中编辑其他TLS参数：

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

为了增强proxy的安全性，您还可以设置TLSServerCertIssuer和TLSServerCertSubject参数。更多信息，请参见Restricting allowed certificate issuer and subject。

最终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
       ```3. 在Zabbix前端为此proxy配置加密：
       
       - 请导航至：*Administration → Proxies*。
       - 选择proxy，然后点击*Encryption*标签。
       
       在下面的示例中，*Issuer*和*Subject*字段已填写。有关使用这些字段的原因和方法的更多信息，请参见[Restricting allowed certificate issuer and subject](#restricting-allowed-certificate-issuer-and-subject)。
       
       对于主动proxy：
       
       ![](../../../assets/en/manual/encryption/proxy_active_cert.png){width="600"}
       
       对于被动proxy：
       
       ![](../../../assets/en/manual/encryption/proxy_passive_cert.png){width="600"}
       
       
       #### Zabbix agent
       
       1. 准备包含顶级CA证书、Zabbix agent证书/证书链以及私钥的文件，具体操作请参考[Zabbix server](#zabbix-server)部分的说明。
       然后，根据[Zabbix agent配置文件](/manual/appendix/config/zabbix_agentd)中的说明，编辑`TLSCAFile`、`TLSCertFile`和`TLSKeyFile`参数。
       
       2. 在[Zabbix agent配置文件](/manual/appendix/config/zabbix_agentd)中编辑额外的TLS参数：
       
       -   对于主动agent：`TLSConnect=cert`
       -   对于被动agent：`TLSAccept=cert`
       
       ::: noteclassic
       为了增强agent的安全性，可以设置`TLSServerCertIssuer`和`TLSServerCertSubject`参数。
       更多详情，请参阅[限制允许的证书颁发者和主题](#restricting-allowed-certificate-issuer-and-subject)。
       :::
       
       最终agent配置文件中的TLS参数可能如下所示。
       请注意，示例假设主机由proxy监控，因此在证书主题中指定了proxy：
       
       ```ini
       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

在Zabbix前端为由该agent监控的主机配置加密。

导航至：数据收集 → 主机。
选择主机并点击加密标签。

在下面的示例中，颁发者和主题字段已填写。有关使用这些字段的原因和方法的更多信息，请参阅限制允许的证书颁发者和主题。

    ##### Zabbix Web 服务

1. 根据Zabbix 服务器章节中的描述，准备顶级 CA 证书、Zabbix Web 服务证书/证书链和私钥的文件。然后，在Zabbix Web 服务配置文件中相应地编辑TLSCAFile、TLSCertFile和TLSKeyFile参数。

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

在最终的 Web 服务配置文件中，TLS 参数可能如下所示：

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

3. 通过在Zabbix 服务器配置文件中编辑WebServiceURL参数，配置 Zabbix 服务器以连接到配置了 TLS 的 Zabbix Web 服务：

WebServiceURL=https://example.com

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

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

然而，这存在风险：任何持有有效证书的人都可以冒充其他人（例如，主机证书可以用来冒充server）。虽然在小型环境中，证书由专门的内部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 server通信。同样，被动proxy不会接受来自此类server的请求。

匹配 `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字段中的值（参见限制允许的证书签发者和主题）。如果证书包含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扩展的支持在不同的加密工具包中有所不同。确保您选择的工具包支持此扩展。如果将此部分标记为关键，根据使用的具体工具包，此扩展可能会限制Zabbix加载CA证书。

证书吊销列表 (CRL)

如果证书遭到破坏，证书颁发机构 (CA) 可以通过将其包含在证书吊销列表 (CRL) 中来撤销该证书。 CRL 通过配置文件进行管理，可以在服务器、proxy 和 agent 的配置文件中使用 TLSCRLFile 参数指定。例如：

ini TLSCRLFile=/home/zabbix/zabbix_crl_file.crt在这种情况下，zabbix_crl_file.crt 可能包含来自多个 CA 的 CRL，其内容可能如下所示：

ini -----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，请确保证书链中的每个 Top 级和中间 CA 都有对应的 CRL（即使它是空的）包含在 TLSCRLFile 中。

Documentation