[comment]: # translation:outdated

[comment]: # ({09d7d659-09d7d659})
# 1 使用证书

[comment]: # ({/09d7d659-09d7d659})

[comment]: # ({109d2e4c-685d1488})
#### 概述

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

证书验证将根据预配置的CA证书执行。
可选地，可使用[证书吊销列表(CRL)](#certificate-revocation-lists-crl)。

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

有关设置和运营内部CA、生成和签署证书请求以及吊销证书的更多信息，请参考诸如[OpenSSL PKI Tutorial v2.0](http://pki-tutorial.readthedocs.org/en/latest/)等教程。

请仔细考虑并测试您的证书扩展。
更多详情，请参阅[X.509 v3证书扩展的使用限制](#limitations-on-using-x.509-v3-certificate-extensions)。

[comment]: # ({/109d2e4c-685d1488})

[comment]: # ({77ce4f81-a572d979})
#### 证书配置参数

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

| 参数 | 必选 | 描述 |
|--|-|--------|
| *TLSCAFile* | yes | 包含用于对等证书验证的Top级CA证书的file完整路径名。<br>若使用多级证书链，请按从低级CA证书到高级CA证书的顺序排列。<br>多个CA的证书可包含在单个file中。 |
| *TLSCRLFile* | no | 包含[证书吊销列表(CRL)](#certificate-revocation-lists-crl)的file完整路径名。 |
| *TLSCertFile* | yes | 包含证书的file完整路径名.<br>若使用含多级成员的证书链, 应按照服务器证书、proxy或agent证书优先的顺序排列, 随后是较低级别CA证书, 最后是较高级别CA证书. |
| *TLSKeyFile* | yes | 包含私钥的file的完整路径名.<br>通过设置适当的访问权限，确保该file只能由[Zabbix用户](/manual/installation/install#create-user-account)读取. |
| *TLSServerCertIssuer* | no | 允许的服务器证书颁发者。 |
| *TLSServerCertSubject* | no | 允许的服务器证书主题。 |

[comment]: # ({/77ce4f81-a572d979})

[comment]: # ({bc3e0bad-7b436c5a})
#### 配置示例

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

以下是详细的配置步骤：

-   [Zabbix server](#zabbix-server)
-   [Zabbix proxy](#zabbix-proxy)
-   [Zabbix agent](#zabbix-agent)

[comment]: # ({/bc3e0bad-7b436c5a})

[comment]: # ({f8f1e7f3-34bcf646})
##### Zabbix服务器

1\. 准备CA证书file.

为验证对等端证书，Zabbix server必须能访问包含Top级自签名根CA证书的file。
例如若需要两个独立根CA的证书，将其放入`/home/zabbix/zabbix_ca_file.crt`路径的file中：

```ini
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证书/证书链存入file，例如存放于`/home/zabbix/zabbix_server.crt`。
首证书为Zabbix server证书，后接中间CA证书：

```ini
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-----
```
::: noteclassic
仅使用上述属性配置客户端和服务端证书，以免影响证书验证流程。
例如若使用*X509v3 Subject Alternative Name*或*Netscape Cert Type*扩展，OpenSSL可能无法建立加密连接。
详见[X.509 v3证书扩展使用限制](#limitations-on-using-x.509-v3-certificate-extensions)。

:::

3\. 将Zabbix server私钥存入file，例如存放于`/home/zabbix/zabbix_server.key`：

```ini
-----BEGIN PRIVATE KEY-----
MIIEwAIBADANBgkqhkiG9w0BAQEFAASCBKowggSmAgEAAoIBAQC9tIXIJoVnNXDl
...
IJLkhbybBYEf47MLhffWa7XvZTY=
-----END PRIVATE KEY-----
```
4\. 在[Zabbix server configuration file](/manual/appendix/config/zabbix_server)中编辑TLS配置参数：

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

[comment]: # ({/f8f1e7f3-34bcf646})

[comment]: # ({2b08bd7a-54ac87c7})
##### Zabbix proxy

1\. 按照[Zabbix server](#zabbix-server)章节描述，准备包含Top级CA证书、Zabbix proxy证书/证书链及私钥的文件。
然后相应地在[Zabbix proxy configuration file](/manual/appendix/config/zabbix_proxy)中编辑`TLSCAFile`、`TLSCertFile`和`TLSKeyFile`参数。

2\. 在[Zabbix proxy configuration file](/manual/appendix/config/zabbix_proxy)中编辑其他TLS参数：

-   主动式proxy: `TLSConnect=cert`
-   被动式proxy: `TLSAccept=cert`

::: noteclassic
为增强proxy安全性，还可设置`TLSServerCertIssuer`和`TLSServerCertSubject`参数。
更多信息参见[限制允许的证书颁发者和主题](#restricting-allowed-certificate-issuer-and-subject)。

:::

最终proxy配置file中的TLS参数示例如下：

```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 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配置加密：

-   前往：*管理 → Proxies*
-   选择proxy并点击*加密*标签页

以下示例中已填写*颁发者*和*主题*字段。
关于为何及如何使用这些字段的详细信息，参见[限制允许的证书颁发者和主题](#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"}

[comment]: # ({/2b08bd7a-54ac87c7})

[comment]: # ({efca9f3c-d2f8a033})
##### Zabbix agent

1\. 按照[Zabbix server](#zabbix-server)章节描述，准备包含Top级CA证书、Zabbix agent证书/证书链及私钥的文件。
随后在[Zabbix agent configuration file](/manual/appendix/config/zabbix_agentd)中相应编辑`TLSCAFile`、`TLSCertFile`和`TLSKeyFile`参数。

2\. 在[Zabbix agent configuration file](/manual/appendix/config/zabbix_agentd)中编辑其他TLS参数：

-   主动式agent：`TLSConnect=cert`
-   被动式agent：`TLSAccept=cert`

::: noteclassic
为增强agent安全性，可设置`TLSServerCertIssuer`和`TLSServerCertSubject`参数。
更多信息参见[限制允许的证书颁发者和主题](#restricting-allowed-certificate-issuer-and-subject)。

:::

最终agent配置中的TLS参数file可能如下所示。
注意此示例假设主机由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
```
3\. 为由此agent监控的主机配置Zabbix前端加密。

-   前往：*配置 → 主机*。
-   选择主机并点击*加密*标签页。

下例中已填写*颁发者*和*主题*字段。
关于为何及如何使用这些字段的更多信息，参见[限制允许的证书颁发者和主题](#restricting-allowed-certificate-issuer-and-subject)。

![](../../../assets/en/manual/encryption/agent_config.png){width="600"}

[comment]: # ({/efca9f3c-d2f8a033})

[comment]: # ({edefb52c-d46d2d24})
##### Zabbix web服务

1\. 按照[Zabbix server](#zabbix-server)章节描述，准备包含Top级CA证书、Zabbix web服务证书/证书链及私钥的文件。
随后在[Zabbix web service configuration file](/manual/appendix/config/zabbix_web_service)中相应编辑`TLSCAFile`、`TLSCertFile`和`TLSKeyFile`参数。

2\. 在[Zabbix web service configuration file](/manual/appendix/config/zabbix_web_service)中编辑额外的TLS参数：`TLSAccept=cert`

最终web服务配置file中的TLS参数示例如下：

```ini
TLSAccept=cert
TLSCAFile=/home/zabbix/zabbix_ca_file
TLSCertFile=/home/zabbix/zabbix_web_service.crt
TLSKeyFile=/home/zabbix/zabbix_web_service.key
```
3\. 通过编辑[Zabbix server configuration file](/manual/appendix/config/zabbix_server)中的`WebServiceURL`参数，配置Zabbix server连接至启用TLS的Zabbix web服务：

```ini
WebServiceURL=https://example.com
```

[comment]: # ({/edefb52c-d46d2d24})

[comment]: # ({70caa4a5-0f34d758})
#### 限制允许的证书颁发者和主题

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

但这存在风险：任何持有有效证书的人都可以冒充他人（例如一个主机证书可能被用来冒充服务器）。
虽然在证书由专用内部CA签发且冒充风险较低的小型环境中可以接受，但在规模更大或对安全性要求更高的环境中可能不够充分。

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

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

```ini
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也不会接受来自此类服务器的请求。

[comment]: # ({/70caa4a5-0f34d758})

[comment]: # ({2ae6e266-a579e1c9})
##### Rules for matching `Issuer` and `Subject` strings

`Issuer`与`Subject`字符串的匹配规则如下:

-   `Issuer`和`Subject`字符串被独立检查。两者都是可选的。
-   未指定的string表示接受任何string。
-   字符串按原样比较且必须完全匹配。
-   支持UTF-8字符。但不支持通配符(`*`)或正则表达式。
-   实现了以下[RFC 4514](http://tools.ietf.org/html/rfc4514)要求 - 需要转义的字符(使用'`\`'反斜杠，U+005C):
    -   在string中的任意位置: '`"`' (U+0022), '`+`' (U+002B), '`,`' (U+002C), '`;`' (U+003B), '`<`' (U+003C), '`>`' (U+003E), '`\\`' (U+005C);
    -   在string开头: 空格(' ', U+0020)或井号('`#`', U+0023);
    -   在string结尾: 空格(' ', U+0020)。
-   不支持空字符(U+0000)。如果遇到空字符，匹配将失败。
-   不支持[RFC 4517](http://tools.ietf.org/html/rfc4517)和[RFC 4518](http://tools.ietf.org/html/rfc4518)标准。

例如，如果`Issuer`和`Subject`组织(`O`)字符串包含尾随空格，且`Subject`组织单位(`OU`)的string包含双引号，这些字符必须被转义:

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

[comment]: # ({/2ae6e266-a579e1c9})

[comment]: # ({76bd63f2-9b3a82cf})
##### 字段顺序与格式

Zabbix遵循[RFC 4514](http://tools.ietf.org/html/rfc4514)的建议，这些字段采用"反向"顺序排列，从最低级别字段(`CN`)开始，到中级字段(`OU`, `O`)，最后是最高级别字段(`DC`)。

```ini
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默认以Top级到低级顺序显示`Issuer`和`Subject`字符串。
在以下示例中，`Issuer`和`Subject`字段从Top级(`DC`)开始，以低级(`CN`)字段结束。
空格和字段分隔符的格式也会根据使用的选项而变化，因此不会匹配Zabbix要求的格式。

```bash
$ 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：

```bash
$ 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配置文件和前端：

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

[comment]: # ({/76bd63f2-9b3a82cf})

[comment]: # ({cb3afa18-29732466})
#### 使用X.509 v3证书扩展的限制

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

**主题备用名称扩展**

Zabbix不支持*主题备用名称*扩展，该扩展用于指定替代DNS名称（如IP地址或电子邮件地址）。
Zabbix仅能验证证书*Subject*字段中的值（参见[限制允许的证书颁发者和主题](#restricting-allowed-certificate-issuer-and-subject)）。
若证书包含`subjectAltName`字段，证书验证结果可能因编译Zabbix组件所使用的加密工具包而异。
因此，Zabbix可能根据这些组合接受或拒绝证书。

**扩展密钥用法扩展**

Zabbix支持*扩展密钥用法*扩展。
但使用时通常需要同时指定*clientAuth*（用于TLS WWW客户端认证）和*serverAuth*（用于TLS WWW服务器认证）属性。
例如：

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

尽管GnuTLS可能问题密钥用法违规警告，但通常仍会允许通信继续进行。

**名称约束扩展**

对*名称约束*扩展的支持因加密工具包而异。
请确保所选工具包支持此扩展。
若该部分被标记为关键，根据使用的具体工具包，此扩展可能限制Zabbix加载CA证书。

[comment]: # ({/cb3afa18-29732466})

[comment]: # ({1be6201b-35b25767})
#### 证书撤销列表(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 file仅在Zabbix启动时加载。
要update CRL，需重启Zabbix。

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

:::

[comment]: # ({/1be6201b-35b25767})