Eclipse Mosquitto 1.3.4 版本解析：require_certificate 客户端证书请求行为的修复与 TLS 监听器配置实践

• 后端
• 消息队列
• 消息路由

Mosquitto 1.3.4 是项目历史上一款典型的缺陷修复（bugfix）版本，于 2014 年 8 月 6 日发布，与 1.3.2、1.3.3 间隔极短。其核心改动聚焦在 Broker 的 TLS 行为上：当require_certificate为 false 时不再向客户端索要证书，并回退掉了 1.3.2 中错误引入的不完整功能。阅读本文后，你将理解 Mosquitto TLS 监听器下客户端证书请求的确切语义、require_certificate与use_identity_as_username等配置项的协同关系，以及如何在当前仓库源码中定位和验证这一修复的实现细节。

版本发布背景：缺陷修复与 Debian 打包审查

发布公告明确指出，1.3.4 是一个缺陷修复版本，其快速迭代的诱因是Debian 开发者对 mosquitto 软件包进行的审查（www/posts/2014/08/version-1-3-4-released.md）。这是一次"确保尽可能无缺陷的版本进入 Debian"的契机，体现了上游项目对发行版集成质量的重视。仓库中的 ChangeLog.txt 与发布文档完全对应，记录了 1.3.4（20140806）的两条 Broker 修复：

• 当require_certificate为 false 时，不再向客户端请求证书。
• 回退 1.3.2 中错误包含的不完整功能。

对比相邻版本记录可以发现，1.3.2（20140713）与 1.3.3（20140801）同样属于密集修复周期（如修复匿名 bridge 在本地 broker 上的错误处理、TLS 下 bridge 默认校验证书等），而 1.3.4 是这一轮针对 TLS 证书握手行为的收尾修复。

Broker 修复一：require_certificate为 false 时不再索要客户端证书

问题本质：TLS 监听器的双向认证语义

在 1.3.4 之前，启用 TLS 的监听器即使在require_certificate关闭（false）的情况下，也可能向客户端发起证书请求（CertificateRequest）。这会导致两个实际问题：

1. 没有客户端证书的普通 MQTT 客户端在握手阶段被要求提供证书，可能触发警告或连接异常；
2. 与"仅加密、不做客户端身份认证"的部署预期不符——默认 TLS 监听器的目标是加密网络流量，而非强制双向认证。

源码级实现：SSL_CTX_set_verify的分支选择

当前仓库中，这一行为在 src/net.c 的net__load_certificates()函数中得到精确体现：

int net__load_certificates(struct mosquitto__listener *listener) { #ifdef WITH_TLS int rc; if(listener->require_certificate){ SSL_CTX_set_verify(listener->ssl_ctx, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, client_certificate_verify); }else{ SSL_CTX_set_verify(listener->ssl_ctx, SSL_VERIFY_NONE, client_certificate_verify); } ...

关键差异在于 OpenSSL 的验证模式：

这就是 1.3.4 修复的落点：当require_certificate为 false 时，服务端不再发送 CertificateRequest，从而避免无证书客户端被无谓地索要证书。而client_certificate_verify回调（src/net.c）则负责在双向认证场景下处理证书有效性细节——例如当disable_client_cert_date_checks开启时，可豁免对证书有效期（X509_V_ERR_CERT_NOT_YET_VALID/X509_V_ERR_CERT_HAS_EXPIRED）的检查。

默认值与配置解析

require_certificate的默认值为false。监听器初始化时在 src/listeners.c 中被显式清零：

#ifdef WITH_TLS listener->require_certificate = false; listener->use_identity_as_username = false; listener->use_subject_as_username = false; listener->use_username_as_clientid = false; listener->disable_client_cert_date_checks = false; #endif

配置解析位于 src/conf.c，仅在编译期启用 TLS（WITH_TLS）时生效，通过conf__parse_bool()接受true/false布尔值，并且该选项只对监听器（listener）上下文有效：

}else if(!strcmp(token, "require_certificate")){ #ifdef WITH_TLS REQUIRE_LISTENER_OR_DEFAULT_LISTENER(token); if(conf__parse_bool(&token, "require_certificate", &cur_listener->require_certificate, &saveptr)){ return MOSQ_ERR_INVAL; } #else log__printf(NULL, MOSQ_LOG_WARNING, "Warning: TLS support not available."); #endif

该布尔标志最终保存在监听器结构体的require_certificate字段中（见 src/mosquitto_broker_internal.h）。

配置手册中的语义描述

在 man/mosquitto.conf.5.xml 中，该选项被描述为：默认情况下，启用 SSL/TLS 的监听器类似于 HTTPS Web 服务器——服务端持有由 CA 签名的证书，客户端负责校验其可信性，整体目标是加密网络流量。将require_certificate设为true后，连接该监听器的客户端必须提供有效证书，连接才能继续，从而可以在 MQTT 自身的认证机制之外控制对 broker 的访问权限。

与require_certificate协同的认证选项

use_identity_as_username：用证书 CN 作为用户名

当require_certificate为 true 时，可同时设置use_identity_as_username true，用客户端证书中的CN（Common Name）值作为用户名。此时该监听器将不再使用password_file进行密码校验（man/mosquitto.conf.5.xml）。

源码中，证书提取逻辑位于 src/security_default.c：当监听器设置了use_identity_as_username或use_subject_as_username时，若客户端没有有效的 TLS 会话（!context->ssl），将直接以认证失败（MOSQ_ERR_AUTH）断开连接——这是对"必须持有合法证书"这一约束的二次强制。同时，src/handle_connect.c 在 CONNECT 处理阶段也会读取该标志来填充用户名。

use_subject_as_username：用完整 subject 作为用户名

与上一项类似，use_subject_as_username使用客户端证书的完整 subject（形如CN=test client,OU=Production,O=Server,...）作为用户名。两者都开启时，use_identity_as_username优先（man/mosquitto.conf.5.xml）。

WebSocket 监听器中的对应行为

TLS 同时覆盖 WebSocket 监听器场景。在 src/websockets.c 中，require_certificate被映射为 libwebsockets 的选项：

if(listener->require_certificate){ info.options |= LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT; }

这意味着 1.3.4 的修复同样适用于通过 WebSocket 接入的 MQTT over TLS 连接：当require_certificate为 false 时，WebSocket 握手也不会强制要求客户端证书。

Broker 修复二：回退 1.3.2 中不完整的功能

发布公告的第二条修复是"回退 1.3.2 中错误包含的不完整功能"（Backout incomplete functionality that was incorrectly included in 1.3.2）。这是软件工程中的标准做法：当某个版本引入了尚未完成、无法保证正确性的功能时，后续版本会将其整体回退，以恢复稳定状态，而不是在缺陷未定的前提下继续叠加。仓库中的 ChangeLog.txt 同样记录了这条改动。

由于这是历史版本的行为调整，当前代码库中已无法直接看到被回退功能的具体代码——回退意味着相关代码已被移除或改写。这一点体现了发布说明与代码库之间的时间差：发布文档描述的是当时版本的变更，而当前仓库反映的是后续多个版本演化的结果。在引用历史发布说明时，应将其视为版本快照而非对当前代码的完整描述。

验证路径：如何在仓库中复核这些修复

如果你希望基于当前仓库验证或复现相关行为，可以参考以下路径：

• 配置解析：src/conf.c 中的require_certificate解析分支，确认布尔值与监听器作用域；
• 握手行为：src/net.c 的net__load_certificates()，确认SSL_VERIFY_NONE与SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT的切换；
• 证书校验回调：src/net.c 的client_certificate_verify()，理解有效期豁免逻辑；
• 配置手册：man/mosquitto.conf.5.xml，获取选项的官方语义描述；
• 发布记录：ChangeLog.txt 与 www/posts/2014/08/version-1-3-4-released.md，对照版本变更与发布说明。

一个可复现的配置示例（基于当前仓库的配置语法）：

listener 8883 cafile /etc/mosquitto/ca.crt certfile /etc/mosquitto/server.crt keyfile /etc/mosquitto/server.key require_certificate false

当require_certificate保持默认 false 时，客户端只需校验服务端证书即可建立加密连接；将其改为true并配合use_identity_as_username，即可把监听器升级为基于客户端证书的双向认证模式。

小结

Mosquitto 1.3.4 虽然是一个小而聚焦的缺陷修复版本，但它解决了一个对 TLS 部署至关重要的握手语义问题：服务端是否请求客户端证书，必须严格遵循require_certificate配置。从 src/net.c 的SSL_CTX_set_verify分支到 src/websockets.c 的 libwebsockets 选项映射，这一行为在源码层面形成了完整闭环。理解这条修复，也就理解了 Mosquitto 中"单向加密"与"双向认证"两种 TLS 监听器模式的本质区别，以及require_certificate、use_identity_as_username、use_subject_as_username三者之间的配置协同关系。

• 后端
• 消息队列
• 消息路由