基于 SSL 的 MQTT

• 使用PEM证书文件配置SSL
• 使用Java Keystore配置SSL
• 额外配置属性
• 自签名证书生成
  • 自签名证书PEM文件
  • 由证书颁发机构（CA）签名的证书PEM文件
• 将 PEM 证书和私钥转换为 PKCS12 keystore
  • 提示与最佳实践
• 将证书添加到Java Truststore在基于Java的应用中，truststore 是包含应用信任实体（证书颁发机构或服务器）证书的特殊密钥库。
• MQTT over WebSocket安全连接

TBMQ支持在SSL上运行MQTT服务器与MQTT over WebSocket，支持单向和双向SSL。

大多数TBMQ环境将负载均衡器作为设备与代理之间SSL连接的终止点。 即MQTT流量在设备与负载均衡器之间加密，在负载均衡器与代理服务之间解密。 该方式的优点为配置简单。 多数云负载均衡器（AWS、Google Cloud等）内置证书生成工具，并提供TCP上SSL的详细配置文档。 缺点为无法实现双向SSL，客户端证书信息不会从负载均衡器传递至代理服务。

尽管如此，仍可将TBMQ配置为MQTT的双向SSL，并避免在负载均衡器上终止SSL。 建议使用受信任CA签发的有效SSL证书，并避免在自签名证书问题上花费时间。 下方说明如何为PEM文件格式或Java Keystore中存储的证书配置SSL。

使用PEM证书文件配置SSL

通过配置文件、docker-compose或kubernetes脚本配置以下环境变量：

1
2
3
4
5
6
7
...
export LISTENER_SSL_ENABLED=true
export LISTENER_SSL_CREDENTIALS_TYPE=PEM
export LISTENER_SSL_PEM_CERT=server.pem
export LISTENER_SSL_PEM_KEY=server_key.pem
export LISTENER_SSL_PEM_KEY_PASSWORD=secret
...

其中：

• LISTENER_SSL_ENABLED — 启用/禁用SSL支持；
• LISTENER_SSL_CREDENTIALS_TYPE — 服务器凭证类型。PEM为pem证书文件；KEYSTORE为java keystore；
• LISTENER_SSL_PEM_CERT — 服务器证书文件路径。包含服务器证书或证书链，也可包含服务器私钥；
• LISTENER_SSL_PEM_KEY — 服务器证书私钥文件路径。默认可选。若服务器证书文件中未包含私钥则为必填；
• LISTENER_SSL_PEM_KEY_PASSWORD — 服务器证书私钥密码（可选）。

完成设置后，启动或重启TBMQ服务。

确保证书文件可被 TBMQ 进程访问：

• Docker Compose：将 volume 挂载到容器的 /config 目录；使用完整路径，如 /config/server.pem；
• K8S：将单独 volume 挂载到 /https-config 或类似目录。使用完整路径，如 /https-config/server.pem。

使用Java Keystore配置SSL

通过配置文件、docker-compose或kubernetes脚本配置以下环境变量：

1
2
3
4
5
6
7
8
...
export LISTENER_SSL_ENABLED=true
export LISTENER_SSL_CREDENTIALS_TYPE=KEYSTORE
export LISTENER_SSL_KEY_STORE_TYPE=PKCS12
export LISTENER_SSL_KEY_STORE=keystore.p12
export LISTENER_SSL_KEY_STORE_PASSWORD=tbmq
export LISTENER_SSL_KEY_PASSWORD=tbmq
...

其中：

• LISTENER_SSL_ENABLED — 启用/禁用SSL支持；
• LISTENER_SSL_CREDENTIALS_TYPE — 服务器凭据类型。PEM为pem证书文件；KEYSTORE为java keystore；
• LISTENER_SSL_KEY_STORE_TYPE — 密钥库类型（JKS或PKCS12）；
• LISTENER_SSL_KEY_STORE — 存放SSL证书或证书链的密钥库路径，亦可包含服务器私钥；
• LISTENER_SSL_KEY_STORE_PASSWORD — 访问密钥库的密码；
• LISTENER_SSL_KEY_PASSWORD — 访问服务器私钥的密码。

完成配置后，启动或重启TBMQ服务器。

确保 keystore 文件可被 TBMQ 进程访问：

• Docker Compose：将 volume 挂载到容器的 /config 目录；使用完整路径，如 /config/keystore.p12；
• K8S：将单独 volume 挂载到 /https-config 或类似目录。使用完整路径，如 /https-config/keystore.p12。

额外配置属性

可通过配置文件、docker-compose或kubernetes脚本配置以下环境变量：

• LISTENER_SSL_BIND_ADDRESS — MQTT服务器的绑定地址。默认 0.0.0.0 表示所有接口；
• LISTENER_SSL_BIND_PORT — MQTT服务器的绑定端口。默认 8883；
• LISTENER_SSL_PROTOCOL — SSL协议名。默认 TLSv1.2。详见 java doc。

自签名证书生成

以下说明用于生成自有证书文件，适用于测试环境，耗时且不推荐用于生产环境。

注意： 需在已安装openssl的Linux类系统上执行以下步骤。

可选择为服务器创建自签名证书，或按进阶步骤创建CA签名的服务器证书。 两种方式都能实现同一目标：用有效证书保护服务器。

自签名证书PEM文件

这是更简单的方式，由服务器自行生成并签署证书，适用于基础测试或无需证书颁发机构（CA）的小型部署。 生成服务器自签名PEM证书及私钥可使用以下命令：

1
2
openssl ecparam -out server_key.pem -name secp256r1 -genkey
openssl req -new -key server_key.pem -x509 -nodes -days 365 -out server.pem 

如不想用密码保护私钥，可加 -nodes（no DES的缩写），否则会要求输入”至少4个字符”的密码。

days 参数（365）可改为任意数字以影响有效期。随后会提示输入”Country Name”等，可直接按Enter使用默认值。

添加 -subj '/CN=localhost' 可跳过证书内容相关提问（将localhost替换为你的域名）。

自签名证书不经第三方校验，除非事先导入浏览器。如需更高安全性，应使用由证书颁发机构（CA）签名的证书。

由证书颁发机构（CA）签名的证书PEM文件

本方法通过创建证书颁发机构（CA）来签署服务器证书，适合需要更高安全性的场景， 尤其是计划管理多张证书或需要专用CA进行签名时。

生成CA私钥：

1
openssl ecparam -out ca_key.pem -name secp256r1 -genkey

生成自签名CA证书：

1
openssl req -new -x509 -key ca_key.pem -days 365 -out ca.pem

将生成有效期为365天的自签名CA证书”ca.pem“。按提示填写证书信息（如Common Name：My Root CA）。

生成服务器私钥：

1
openssl ecparam -out server_key.pem -name secp256r1 -genkey

将生成 EC私钥server_key.pem。

创建证书签名请求（CSR）：

1
openssl req -new -key server_key.pem -out server.csr

“server.csr“包含待CA签名的服务器信息。

最后，使用CA签署服务器证书：

1
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca_key.pem -CAcreateserial -out server.pem -days 365

该命令将生成由CA签名的服务器证书”server.pem“。

-req：表示输入为证书签名请求（CSR）。 -CA 与 -CAkey：指定用于签署服务器证书的CA证书“ca.pem”及其私钥“ca_key.pem”。

-CAcreateserial 会自动生成序列号文件”ca.srl“以记录该CA的证书序列号。 签署多张证书时很有用。若不希望生成”ca.srl“，可将 -CAcreateserial 换成 -set_serial <serial_number> 手动指定序列号。

It is recommended to include the ca.pem file in TBMQ’s Truststore. This is especially important if you plan to issue client certificates signed by the same CA that signed the server certificate. By doing so, TBMQ will be able to validate these client certificates during the TLS handshake, allowing secure MQTT client connections.

为此，需将服务器证书与CA证书拼接以创建证书链：

1
cat server.pem ca.pem > serverChain.pem

然后将生成的 serverChain.pem 文件在TBMQ中配置，设置以下环境变量：

1
LISTENER_SSL_PEM_CERT=serverChain.pem

这可确保服务器证书与CA证书被正确识别，在使用客户端证书时启用安全双向认证。

将 PEM 证书和私钥转换为 PKCS12 keystore

确保具备以下文件：

• server.pem – 公钥证书（可含链）；
• server_key.pem – 私钥； *（可选）ca.pem – root 或 intermediate CA 证书。

执行以下命令创建 PKCS12 keystore 文件 (keystore.p12)：

1
2
3
4
5
6
7
openssl pkcs12 -export \
  -in server.pem \
  -inkey server_key.pem \
  -certfile ca.pem \
  -out keystore.p12 \
  -name tbmq \
  -passout pass:changeit

-certfile ca.pem \ 行为可选，若有 CA 证书链则包含。

将 changeit 替换为所需 keystore 密码。该密码会在环境变量中引用。

提示与最佳实践

• 生产环境建议使用 PKCS12 (.p12) 格式，比 JKS 更具互操作性。
• 导出时确保证书链完整（含 intermediates）。

将证书添加到Java Truststore在基于Java的应用中，truststore 是包含应用信任实体（证书颁发机构或服务器）证书的特殊密钥库。

将证书加入truststore可确保使用该truststore运行的Java应用会接受由该证书或其颁发CA签名的SSL/TLS连接。

1
keytool -importcert -file CERT.pem -alias ALIAS -keystore keystore.p12 -storepass KEYSTOREPASS

参数说明：

• -importcert — 告知 keytool 将证书导入指定keystore/truststore。
• -file CERT.pem — 要导入的证书文件路径。
• -alias ALIAS — 密钥库中引用该证书的唯一名称。
• -keystore keystore.p12 — 将添加证书的Java keystore/truststore文件（.jks或 .p12）。若不存在则会创建。
• -storepass KEYSTOREPASS — 保护密钥库的密码。

请确保使用相应的 Keystore参数 在TBMQ中启用MQTTS。

使用 keytool 命令前，系统需安装Java Development Kit (JDK)。

MQTT over WebSocket安全连接

要启用MQTT over WebSockets (WSS)，可按上述相同SSL配置步骤操作。 在配置文件、Docker Compose或Kubernetes清单中使用对应的WebSocket专用环境变量（如 LISTENER_WSS_ENABLED、LISTENER_WSS_CREDENTIALS_TYPE 等）即可。

使用PEM或Keystore的SSL配置对原始MQTT over TLS和WebSocket over TLS端点同样适用。