EMQX QUIC Listener 修复：TLS 握手失败时同样导出会话密钥（SSLKEYLOGFILE）

后端物联网消息队列通信【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址https://gitcode.com/gh_mirrors/em/emqx点击查看免费下载本篇技术指南围绕 EMQX 开源仓库变更记录 fix-15614.en.md 中的一项 QUIC Listener 修复展开当启用 TLS 密钥日志key logging时即使 TLS 握手失败也要把会话密钥写入sslkeylogfile指定的文件。读者读完本文可以理解该修复的价值、sslkeylogfile配置项的正确用法与限制并能结合源码理清 EMQX 中 QUIC 监听器与密钥日志的底层工作链路。变更背景MQTT over QUIC 的排障难题EMQX 通过quicer基于 MsQuic 的 Erlang 绑定提供 MQTT over QUIC 监听器使用 TLS 1.3 加密传输。TLS 1.3 会话密钥无法像 TLS 1.2 时代那样由服务端单独导出预主密钥master secret用于第三方解密因此抓包工具如 Wireshark要解密 QUIC/TLS 1.3 流量必须依赖客户端或服务端主动导出的会话密钥——这正是SSLKEYLOGFILETLS key log机制的用途。在修复之前存在一个实际排障盲区当客户端与服务端的 TLS 握手失败时EMQX 不会把可能已经生成的TLS 会话密钥写入日志文件。而恰恰是握手失败这种场景开发者最需要解密流量来定位证书配置错误、密码套件不匹配、ALPN 协商失败等问题。本次变更修复了这一点只要启用了 TLS 密钥日志无论握手成功还是失败都会尝试导出密钥。配置方法QUIC 监听器的 sslkeylogfileEMQX 在 QUIC listener 的 schema 中定义了sslkeylogfile配置项位于 apps/emqx/src/emqx_schema.erl{sslkeylogfile, sc( string(), #{ desc ?DESC(fields_mqtt_quic_listener_sslkeylogfile), importance ?IMPORTANCE_HIDDEN } )},它的官方描述rel/i18n/emqx_schema.hocon明确说明了用途与限制Specify the path to the file on the local filesystem where the listener writes TLS session secrets for each connection, enabling decryption of the traffic.This cannot be changed at runtime.即sslkeylogfile用于指定一个本地文件路径监听器会把每条连接的 TLS 会话密钥写入该文件从而允许解密流量该配置不支持运行时热更新。结合 rel/config/examples/listeners.quic.conf.example 中 QUIC listener 的完整骨架一个可落地的配置示例如下listeners.quic.my_quick_listener_name { bind 14567 ## 或带 IP如 127.0.0.1:14567 enable_authn true ## 客户端认证开关 acceptors 16 ## socket 接收池大小 max_connections infinity ## 最大并发连接数 ## TLS 1.3 独占密码套件 ciphers TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_CHACHA20_POLY1305_SHA256 ## TLS 密钥日志写入会话密钥供 Wireshark 等工具解密流量 ## 注意该配置项为隐藏项importance hidden且不支持运行时修改 sslkeylogfile /tmp/quic_keys.log ssl_options { ## 留空 certfile/keyfile 时使用节点自生成证书 ## 也可将证书放入 etc/certs 后在此引用 # cacertfile ${EMQX_ETC_DIR}/certs/ca.pem # certfile ${EMQX_ETC_DIR}/certs/name.pem # keyfile ${EMQX_ETC_DIR}/certs/name.key verify verify_none ## 改为 verify_peer 可启用客户端证书校验 } }几点实操注意事项隐藏配置项sslkeylogfile的importance被标记为?IMPORTANCE_HIDDEN意味着它通常不在常规配置模板和文档中展示需要手动写入配置不可运行时修改描述中明确 This cannot be changed at runtime修改后需重启节点或按监听器热更新流程使其生效安全敏感key log 文件包含可解密全部 TLS 流量的会话密钥属于高敏感材料生产环境应严格限制文件权限并仅在排障期间开启用完即关。源码链路从配置到 quicer 的密钥导出本次修复的落点与 QUIC 监听器的启动参数组装逻辑密切相关。在 apps/emqx/src/emqx_listeners.erl 中QUIC 监听器启动时调用quicer:spawn_listener(Id, ListenOn, to_quicer_listener_opts(Name, Opts))do_start_listener(quic, Name, Id, #{bind : Bind} Opts) - ListenOn quic_listen_on(Bind), case [A || {quicer, _, _} A - application:which_applications()] of [_] - quicer:spawn_listener( Id, ListenOn, to_quicer_listener_opts(Name, Opts) ); [] - {ok, {skipped, quic_app_missing}} end.to_quicer_listener_opts/2apps/emqx/src/emqx_listeners.erl会把监听器的ssl_options与 QUIC 相关选项合并成 quicer 的 listener optionsto_quicer_listener_opts(Name, Opts) - DefAcceptors erlang:system_info(schedulers_online) * 8, SSLOpts maps:from_list(ssl_opts(Opts)), Opts1 maps:filter( fun (cacertfile, undefined) - false; (password, undefined) - false; (_, _) - true end, Opts ), Opts2 maps:merge( Opts#{alpn [mqtt], conn_acceptors max(DefAcceptors, maps:get(acceptors, Opts1, 0)), ...}, SSLOpts ), ...从源码结构可以推断sslkeylogfile属于被合并进 QUIC 监听器 TLS 配置的选项之一最终透传给底层quicer/MsQuic 栈当该项被设置后MsQuic 在 TLS 握手过程中会回调导出会话密钥。本次变更的核心在于让密钥导出回调不再以握手成功为前提——握手失败路径例如密钥协商中途出错也会触发导出从而让抓包工具仍能解密失败握手的流量帮助定位问题。典型应用场景用 Wireshark 解密失败的 QUIC 握手启用该功能后的典型排障流程在 QUIC listener 配置中加入sslkeylogfile指向一个可写文件重启节点使配置生效该配置不可运行时修改用支持 MQTT over QUIC 的客户端触发一次预期会失败的连接如证书错误、密码套件不匹配打开抓包文件在 Wireshark 的 TLS 首选项中指定该 key log 文件此时即使握手失败失败的 ClientHello/ServerHello 及后续 TLS 记录也能被解密从而核对证书链、ALPNmqtt、密码套件协商等细节。需要注意的是该功能仅适用于 QUIC listeneremqx_listeners.erl中current_conns(quic, ...)等分支也表明 QUIC 与 tcp/ssl/ws/wss 走的是不同的监听与统计路径配置时不要误把sslkeylogfile混入普通 TCP/TLS listener。小结本次修复changes/ee/fix-15614.en.md补齐了 EMQX QUIC Listener 在 TLS 握手失败场景下的密钥导出能力让开发者能够在最需要流量解密的时候拿到密钥。使用时牢记三点sslkeylogfile是隐藏配置项、不支持运行时修改、密钥日志文件本身是敏感数据需要妥善保管。相关实现可继续在 emqx_schema.erl、emqx_listeners.erl 与 QUIC 配置示例 listeners.quic.conf.example 中深入研读。赞分享后端物联网消息队列通信【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址https://gitcode.com/gh_mirrors/em/emqx点击查看免费下载相关推荐mitmproxy 如何把 SSLKEYLOGFILE 密钥日志接入 Wireshark 解密 TLS 流量mitmproxy 如何把 SSLKEYLOGFILE 密钥日志接入 Wireshark 解密 TLS 流量 用 mitmproxy 做 TLS 中间人代理时网络安全网络开发工具接口测试青龙面板SSL握手失败DH密钥长度不足完美修复方案青龙面板SSL握手失败DH密钥长度不足完美修复方案 你是否遇到青龙面板QingLong PanelSSL/TLS连接失败浏览器提示DH密钥长度不足的任务调度后端前端mitmproxy SSL 密钥日志全解借助 SSLKEYLOGFILE 在 Wireshark 中解密 TLS 流量mitmproxy SSL 密钥日志全解借助 SSLKEYLOGFILE 在 Wireshark 中解密 TLS 流量 当 mitmproxy 作为中间人代理网络安全网络开发工具接口测试创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考