EMQX 节点 Cookie 配置安全修复:`` 字符截断问题与非法字符校验机制

原创2026-09-22 23:56:111,928 阅读
文章标签:物联网IoT协议消息队列后端消息路由数据集成认证鉴权可观测性云原生

EMQX 节点 Cookie 配置安全修复:# 字符截断问题与非法字符校验机制

导读

本文基于 EMQX 开源仓库 changes/ee/fix-16545.en.md 变更记录,深入讲解 EMQX 中 node.cookie(节点 Cookie)配置的一个真实缺陷修复:当 Cookie 中包含 # 字符时,此前只有 # 之前的片段会生效,例如配置 abc#d 实际得到的 Cookie 只有 abc;同时,本次修复还为 Cookie 新增了非法字符校验,明确拒绝反斜杠(\)、单引号(')、双引号(")和空格。读完本文,你将了解 Cookie 在 EMQX 集群认证与节点间通信中的核心作用、该缺陷的成因与影响、底层校验实现,以及如何在多节点集群与容器化部署中正确、安全地配置 node.cookie。

一、node.cookie 是什么:EMQX 节点间信任的钥匙

在 EMQX 中,node.cookie 是配置在 node 配置段下的一个核心参数。根据 emqx_conf_schema.erl 中的字段定义,它是一个必填(required)、只读(readOnly)且敏感(sensitive) 的字符串配置项,重要性等级为 HIGH。

它在集群中的语义可以从 rel/i18n/emqx_conf_schema.hocon 的官方说明中概括为:

  • Cookie 是一个随机字符串,同一 EMQX 集群内的所有节点必须配置相同的值;
  • 不同 EMQX 集群之间应使用彼此不同的 Cookie;
  • 其作用是防止属于不同集群的 EMQX 节点意外地互相连接(即作为集群成员准入的信任凭据)。

底层实现上,EMQX 基于 Erlang/OTP 的分布式能力构建,节点间通过 Erlang 分布式协议通信,而 Erlang 的 -setcookie 正是这一信任机制的载体。从 emqx_conf_schema.erl 的注释可以看到一个关键设计细节:

%% NOTE: intentionally NOT mapped to "vm_args.-setcookie".
%% The cookie is passed to the Erlang VM via the `-setcookie`
%% command-line flag from `bin/emqx` instead, so the resolved
%% secret is never written to the generated vm.<time>.args file
%% on disk. This also lets `bin/emqx` resolve `file://` sources
%% (which the VM/HOCON layer cannot do, as the cookie is needed
%% before the VM starts).

即:node.cookie 不会被映射到 vm_args.-setcookie 写入磁盘上的 vm.<time>.args 文件,而是由 bin/emqx 启动脚本在启动 VM 时通过 -setcookie 命令行参数注入。这样既避免了敏感凭据以明文形式落盘,也使得 file:// 形式的 Cookie 来源(见下文)可以在 VM 启动前被解析。<a href="https://link.gitcode.com/i/71007bb5246ba506a06a4f6e6ebe5613" target="_blank">apps/emqx/etc/vm.args.cloud</a> 中的注释也印证了 node.name/node.cooke 这类配置与 VM 参数 -name/-setcookie 的对应关系。

二、缺陷描述:# 字符导致 Cookie 被截断

原变更记录(changes/ee/fix-16545.en.md)描述的缺陷非常具体:

Fixed node.cookie handling of # character. Previously, if the cookie contained #, only the prefix before # would take effect. For example, if abc#d was configured, only abc was used as the cookie.

也就是说,如果运维人员在配置中写入类似 node.cookie = "abc#d" 的值,实际生效的 Cookie 只有 abc,#d 被静默丢弃。这种"配置值与实际生效值不一致"的问题非常隐蔽,会造成两类严重后果:

  1. 集群成员互信失败:同一集群内,如果不同节点的配置文件中 # 前后片段一致(例如都写了 abc#d 但实际都只生效了 abc),表面上看起来"配置相同",实际上各节点以 abc 作为真实 Cookie 仍能互连,问题不会被立刻发现;
  2. 配置迁移不一致:如果某个节点以 abc#d 为期望值、另一节点以其他形式配置,两个节点实际使用的 Cookie 不同,将导致节点间握手失败、集群无法组建;而日志中的报错又不会直接提示是 # 截断所致,排查成本高。

从配置语法层面可以推断该缺陷的根源:EMQX 的配置采用 HOCON 格式,在 HOCON 中 # 是注释起始字符;同时在 shell/启动脚本上下文中,# 也常被解释为注释起始。因此包含 # 的 Cookie 在配置解析或脚本传递过程中,# 之后的内容被当作注释截断,最终只有前缀生效。这属于典型的"配置值与运行值不一致"隐患,本次修复正是针对这一行为。

三、修复内容:新增 Cookie 非法字符校验

在修复 # 处理问题的同时,本次变更新增了启动期校验,从源头拒绝容易引发解析歧义的字符。原变更记录明确列出被禁止的字符:

Added validation to reject problematic characters: backslash, single quote, double quote, and space.

即 Cookie 中不允许出现以下四个字符:

字符 说明
\ 反斜杠
' 单引号
" 双引号
空格

四、源码级剖析:校验逻辑的实现与判定规则

4.1 校验器挂载位置

在 emqx_conf_schema.erl 的 node.cookie 字段定义中,校验器通过以下方式挂载:

{"cookie",
    sc(
        string(),
        #{
            required => true,
            'readOnly' => true,
            sensitive => true,
            desc => ?DESC(node_cookie),
            importance => ?IMPORTANCE_HIGH,
            converter => fun emqx_schema:password_converter/2,
            validator => fun validate_cookie/1
        }
    )},

可以看到,Cookie 还经过 emqx_schema:password_converter/2 转换器处理,并标记为 sensitive,说明它在配置输出、日志打印等场景中会被脱敏处理。

4.2 校验规则实现

校验逻辑位于 emqx_conf_schema.erl,共分两层:

第一层:基本约束(validate_cookie/1)

validate_cookie("") ->
    throw("Cookie must be non-empty string");
validate_cookie(Cookie) when is_list(Cookie) ->
    case length(Cookie) > 255 of
        true ->
            throw("Cookie cannot be more than 255 bytes");
        false ->
            validate_cookie_chars(Cookie)
    end.
  • Cookie 不能为空字符串("Cookie must be non-empty string");
  • Cookie 长度不能超过 255 字节("Cookie cannot be more than 255 bytes")。

第二层:字符校验(validate_cookie_chars/1)

%% There is technically no such limit for 'erl' command,
%% but hard to handle these chars in bash for commands 'ctl', 'remote' etc.,
%% so, why not be nice, don't use them at all.
validate_cookie_chars(Cookie) ->
    InvalidChars = [$\\, $', $", $\s],
    case find_invalid_cookie_char(Cookie, InvalidChars) of
        ok ->
            ok;
        {error, Char} ->
            throw("Cookie cannot contain character: " ++ describe_char(Char))
    end.

非法字符集合为 [$\\, $', $", $\s],即反斜杠、单引号、双引号、空格。源码注释给出了这一限制的深层理由:虽然 erl 命令本身对 Cookie 字符没有硬性限制,但这些字符在 bash 环境中会给 emqx ctl、emqx remote 等需要拼接命令行参数的辅助命令带来转义难题,因此直接从配置源头禁止,属于"从根源规避运维风险"的设计。

对每个非法字符,describe_char/1 会生成可读的错误描述(见 emqx_conf_schema.erl):

describe_char($\\) -> "backslash (\\)";
describe_char($') -> "single quote (')";
describe_char($") -> "double quote (\")";
describe_char($\s) -> "space".

4.3 校验失败的错误信息

结合校验器实现与测试用例,可以整理出校验失败时的完整错误文案:

场景 错误信息
Cookie 为空 Cookie must be non-empty string
Cookie 超过 255 字节 Cookie cannot be more than 255 bytes
包含反斜杠 Cookie cannot contain character: backslash (\)
包含单引号 Cookie cannot contain character: single quote (')
包含双引号 Cookie cannot contain character: double quote (")
包含空格 Cookie cannot contain character: space

五、测试验证:完整覆盖六类非法输入

本次修复带有配套的单元测试,位于 emqx_conf_schema_tests.erl 的 validate_cookie_test_/0,通过 emqx_hocon:load_and_check/2 加载真实的 HOCON 配置片段来验证配置校验行为。六个用例逐一覆盖了上述六类非法输入:

  • 空 Cookie:node {cookie = "", data_dir = "."},断言返回 {error, #{reason := "Cookie must be non-empty string"}};
  • 超长 Cookie:用 256 个 a 构造 Cookie,断言返回 "Cookie cannot be more than 255 bytes";
  • 含反斜杠:"my\\cookie",断言返回 "Cookie cannot contain character: backslash (\\)";
  • 含单引号:"my'cookie",断言返回 "Cookie cannot contain character: single quote (')";
  • 含双引号:"my\"cookie",断言返回 "Cookie cannot contain character: double quote (\")";
  • 含空格:"my cookie",断言返回 "Cookie cannot contain character: space"。

这些用例直接使用真实的 HOCON 解析链路(hocon → emqx_hocon:load_and_check → schema 校验器),确保校验逻辑在真实配置加载流程中生效,而不只是函数级的孤立测试。这也意味着:配置了非法字符的 node.cookie 会在配置加载阶段直接报错,从而在节点启动前就暴露问题,避免带病启动后出现难以排查的集群互连故障。

六、正确配置 Cookie:多节点集群与容器化实践

6.1 标准配置形式

在 emqx.conf 或集群编排配置中,合法写法为:

node {
    cookie = "my-emqx-cluster-cookie-2026"
}

应遵循以下约束:

  • 使用随机生成的强字符串,且同一集群所有节点保持一致;
  • 禁止使用 #、\、'、" 和空格(其中后四类会被校验器直接拒绝,# 因历史截断问题也应彻底避免);
  • 长度在 1~255 字节之间;
  • 不同集群之间应使用不同 Cookie,防止跨集群节点误连。

6.2 通过环境变量注入

EMQX 支持通过环境变量覆盖配置。仓库测试与脚本中大量使用 EMQX_NODE__COOKIE 形式,例如 scripts/pkg-tests.sh:

export EMQX_NODE__COOKIE='ci-smoke-test-cookie'

以及 scripts/test/start-two-nodes-in-host.sh 中通过环境变量为两个节点设置 Cookie:

EMQX_NODE__COOKIE="${EMQX_NODE__COOKIE:-cookie1}"

这在容器化部署(docker run -e EMQX_NODE__COOKIE=...)和 CI 测试中非常实用,可避免把敏感凭据直接写死在配置文件中。

6.3 从文件或命名管道(FIFO)加载

根据 rel/i18n/emqx_conf_schema.hocon 的说明,Cookie 还支持 file:// 形式的来源,从而不必以明文存储在配置文件中:

node {
    cookie = "file:///run/emqx/cookie"
}

关于这一形式,官方说明中有几个关键使用前提:

  • 引用的路径可以是普通文件或 FIFO(命名管道);
  • 该文件只在节点启动时读取一次;
  • 若使用 FIFO,编排系统必须在每次启动时、且在调用任何其他 emqx 命令(如 emqx ctl)之前将 Cookie 写入管道——因为后续命令是从已运行节点获取 Cookie,而不会重新读取该文件。

6.4 集群场景下的配置一致性检查

由于 Cookie 是集群成员互信的凭据,推荐在部署后通过以下方式核验:

  • 使用 emqx ctl status 或集群管理命令确认节点成员关系是否符合预期;
  • 在配置变更(尤其是涉及 Cookie 的变更)后,确认所有节点的实际 Cookie 值一致;
  • 若配置了 file:// 来源,确认文件权限与内容在所有节点上一致,避免单节点读不到或读到不同值。

七、总结与建议

本次 fix-16545 修复从两个层面提升了 node.cookie 的健壮性:

  1. 修复了 # 字符导致的 Cookie 截断:此前 abc#d 实际只生效 abc,属于静默的配置-运行不一致问题;修复后该隐患被消除;
  2. 新增启动期非法字符校验:通过 emqx_conf_schema.erl 中的 validate_cookie/validate_cookie_chars 明确拒绝反斜杠、单引号、双引号与空格,并配套 emqx_conf_schema_tests.erl 中的六个测试用例覆盖全部错误分支,保证非法配置在启动前即被拦截。

对于使用 EMQX 的团队,建议在 Cookie 规划阶段就遵循"随机生成、集群一致、集群间互异、避开全部特殊字符"的纪律,并结合 EMQX_NODE__COOKIE 环境变量或 file:// 文件来源进行安全分发,从而从配置源头规避集群互信故障。

登录后查看全文
emqx