基于 DTLS 的 CoAP

• 使用PEM证书文件配置SSL
• 其他配置属性
• 自签名证书生成
  • 自签名证书PEM文件
  • 由证书颁发机构（CA）签名的证书PEM文件
• 客户端示例

ThingsBoard支持在DTLS之上运行CoAP服务器，支持单向与双向DTLS。 DTLS配置需要有效的 ECDSA 证书。 ECDSA密钥比RSA密钥更小，更适合受限设备。 详见对比 文章。 建议使用受信任CA签发的有效SSL证书，避免在 自签名证书 相关问题上耗费时间。 以下说明如何为PEM文件格式或Java Keystore中的证书配置SSL。

使用PEM证书文件配置SSL

通过 configuration 文件、docker-compose或kubernetes脚本配置以下环境变量。 以 thingsboard.conf 为例：

1
2
3
4
5
6
7
...
export COAP_DTLS_ENABLED=true
export COAP_DTLS_CREDENTIALS_TYPE=PEM
export COAP_DTLS_PEM_CERT=server.pem
export COAP_DTLS_PEM_KEY=server_key.pem
export COAP_DTLS_PEM_KEY_PASSWORD=secret
...

说明：

• COAP_DTLS_ENABLED — 启用/禁用TLS支持；
• COAP_DTLS_CREDENTIALS_TYPE — 服务器凭据类型。PEM表示PEM证书文件；KEYSTORE表示Java keystore；
• COAP_DTLS_PEM_CERT — 服务器证书文件路径。可包含服务器证书或证书链，也可包含服务器私钥；
• COAP_DTLS_PEM_KEY — 服务器证书私钥文件路径。默认可选。若服务器证书文件中不含私钥则必须指定；
• COAP_DTLS_PEM_KEY_PASSWORD — 可选，服务器证书私钥密码。

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

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

• Linux：使用 /etc/thingsboard/conf 目录。确保文件权限与 thingsboard.conf 一致；使用相对路径，如 server.pem；
• Docker Compose：将卷挂载或使用现有卷至容器的 /config 目录；使用完整路径，如 /config/server.pem；
• K8S：将独立卷挂载至 /https-config 或类似目录；使用完整路径，如 /https-config/server.pem；
• Windows：使用 C:\Program Files (x86)\thingsboard\conf\ 目录。确保文件权限与 thingsboard.conf 一致；使用相对路径，如 server.pem；

其他配置属性

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

• COAP_DTLS_BIND_ADDRESS — 安全CoAP服务器绑定地址。默认值 0.0.0.0 表示所有接口；
• COAP_DTLS_BIND_PORT — 安全CoAP服务器绑定端口。默认值为 5684；
• TB_COAP_X509_DTLS_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT — 跳过客户端证书有效性校验。默认值为 false；
• TB_COAP_X509_DTLS_SESSION_INACTIVITY_TIMEOUT — DTLS会话最大空闲时间（毫秒）。默认值 86400000 表示一天；
• TB_COAP_X509_DTLS_SESSION_REPORT_TIMEOUT — 定期清理非活动会话的间隔（毫秒）。默认值 1800000 表示30分钟。

自签名证书生成

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

注意： 需在已安装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> 手动指定序列号。

客户端示例

参见以下资源：

• Access Token 认证 — 单向TLS 连接示例；
• X.509 证书认证 — 双向TLS 连接示例。