在 BYOC 中配置 TLS/SSL

EMQX BYOC 部署使用 TLS/SSL 加密协议，建立安全的加密通信通道，在数据传输过程中保护数据的机密性。本页概述了如何在单向和双向认证模式下启用 TLS/SSL 通信，确保 MQTT 系统的安全通信。

下表概述了单向和双向认证模式下的不同认证要求。

认证方式	是否支持自签名证书	服务器证书	证书链	私有秘钥	客户端 CA 证书
单向认证	不支持	需要	可选	需要	不需要
双向认证	不支持	需要	可选	需要	需要

单向认证模式

单向认证确保服务器（EMQX MQTT 代理）在 TLS/SSL 握手期间向客户端（设备或应用程序）呈现有效的证书。客户端通过将呈现的证书与受信任的证书颁发机构（CA）进行验证，以验证服务器的真实性。

在 BYOC 部署中，目前只接受受信任的 CA 颁发的证书。

证书组件

要为 BYOC 部署配置 TLS/SSL，请准备 PEM 编码的服务端证书文件及其对应的私钥文件。服务端证书文件可以包含以下证书组件：

• 服务器证书：这是由受信任的证书颁发机构（CA）颁发的证书，使 EMQX MQTT 代理能够与客户端建立安全连接。

• 证书链：如果服务端证书由中间 CA 签发，请包含相应的中间证书，以便客户端验证服务端证书。根证书为可选项。

请将与服务端证书对应的私钥准备为单独的 PEM 文件。

控制台配置和更新的证书要求

通过 EMQX Cloud 控制台创建或更新 BYOC TLS/SSL 配置时，EMQX Cloud 将按照以下规则验证提交的证书：

• 提供 PEM 格式的 X.509 证书。证书块之间只能包含空白字符。
• 按照服务端证书在前、各级中间证书在后的签发顺序排列证书。支持仅提供一张服务端证书，证书链最多包含 5 张证书。
• 服务端证书必须已生效，且距离到期至少还有 5 天。
• 证书必须通过编码、签名和证书链验证。
• 请提供 PKCS#1 或 PKCS#8 格式的无密码 PEM 私钥。私钥必须与服务端证书匹配。

使用双向 TLS 时，请提供一张或多张 PEM 格式的可信客户端 CA 证书。EMQX Cloud 会分别验证每张证书。这些证书无需组成有序证书链。仅服务端证书链受以下要求限制：最多包含 5 张证书，且首张证书至少剩余 5 天有效期。

EMQX Cloud 会在保存或应用 TLS/SSL 配置前验证证书输入。如果验证失败，当前证书和配置不会发生变化。

在 "byoc create" 命令中使用证书文件

初次部署时，BYOC Toolkit 会验证通过 --sslCertPath、--sslKeyPath 以及可选的 --clientCaPath 提供的文件。此验证与上述控制台验证相互独立。

在执行 ./byoc create 之前，请将服务端证书、私钥以及可选的客户端 CA 证书文件复制到 Ubuntu 环境。分别使用 --sslCertPath、--sslKeyPath 和可选的 --clientCaPath 指定各文件的绝对路径。详情请参阅创建部署。

创建双向认证

1. 登录 EMQX Cloud 控制台。
2. 进入部署详情，点击 + TLS/SSL 配置 按钮，配置证书内容，您可以上传文件或者直接填写证书内容:
   • TLS/SSL 认证类型：选择双向认证（客户端和服务端相互验证证书）。
   • 公钥证书：自定义的服务端证书（包括证书链：通常第三方机构签发证书时会提供，如缺失您可以前往 证书链补全）
   • 私钥：私有秘钥
   • 客户端 CA 证书：选择双向认证时，需要提供客户端的 CA 证书
3. 填写完成后，点击确认。

使用 MQTTX 测试双向 TLS

测试之前，请确保创建了认证信息，参考认证，您可以使用 MQTTX 连接和测试。在本教程中我们将使用用 MQTTX 进行测试：

1. 新建连接，输入 Name，Client ID 随机生成即可。
2. 选择 Host，填入部署的连接地址和端口。
   • 若选择 SSL 连接，选择 mqtts:// 和 8883 端口
   • 若选择 WebSocket with SSL，选择 wss:// 和 8084 端口
3. 输入创建的认证信息：用户名和密码。
4. 启用 SSL/TLS。
5. 选择证书：
   • 如果是 CA 机构认证的服务端证书，点击 Self signed，在 CA File 填入证书。
   • 双向认证还需填入客户端证书以及客户端密钥。
6. 点击右上角的连接。

您还可以查看双向认证教程视频了解每一步的设置。

更新证书

当证书即将到期或需要替换时，您可以在部署详情页更新现有的 TLS/SSL 证书。

1. 登录 EMQX Cloud 控制台。

2. 进入部署详情，在 TLS/SSL 配置部分找到需要更新的证书，点击操作列中的编辑图标。

3. 在弹出的 TLS/SSL 配置对话框中，填写新的证书内容，您可以上传文件或直接填写证书内容：

   • TLS/SSL 类型：证书类型不可更改，与当前证书一致。
   • 公钥证书和证书链：填入新的服务端证书内容（包括证书链）。
   • 私钥：填入与新证书对应的私钥。
   • 客户端 CA 证书：双向认证时，还需填入客户端 CA 证书。

   新服务端证书的通用名称（Common Name，CN）必须与部署域名匹配。当前验证使用 CN 进行此项检查，仅主题备用名称（Subject Alternative Name，SAN）匹配不满足要求。

4. 填写完成后，点击确认。

删除证书

Note

仅 BYOC v4 部署支持删除 TLS/SSL 证书。BYOC v5 部署不支持此操作。

删除证书会断开客户端到 8883 和 8084 的连接，请确保这不会影响到您的业务。

1. 登录 EMQX Cloud 控制台。
2. 进入部署详情，在 TLS/SSL 配置部分找到需要删除的证书，点击操作列中的删除图标。
3. 在对话框点击确定，完成删除。