EMQX 节点 Cookie 配置安全修复:`` 字符截断问题与非法字符校验机制
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.cookiehandling of#character. Previously, if the cookie contained#, only the prefix before#would take effect. For example, ifabc#dwas configured, onlyabcwas used as the cookie.
也就是说,如果运维人员在配置中写入类似 node.cookie = "abc#d" 的值,实际生效的 Cookie 只有 abc,#d 被静默丢弃。这种"配置值与实际生效值不一致"的问题非常隐蔽,会造成两类严重后果:
- 集群成员互信失败:同一集群内,如果不同节点的配置文件中
#前后片段一致(例如都写了abc#d但实际都只生效了abc),表面上看起来"配置相同",实际上各节点以abc作为真实 Cookie 仍能互连,问题不会被立刻发现; - 配置迁移不一致:如果某个节点以
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 的健壮性:
- 修复了
#字符导致的 Cookie 截断:此前abc#d实际只生效abc,属于静默的配置-运行不一致问题;修复后该隐患被消除; - 新增启动期非法字符校验:通过 emqx_conf_schema.erl 中的
validate_cookie/validate_cookie_chars明确拒绝反斜杠、单引号、双引号与空格,并配套 emqx_conf_schema_tests.erl 中的六个测试用例覆盖全部错误分支,保证非法配置在启动前即被拦截。
对于使用 EMQX 的团队,建议在 Cookie 规划阶段就遵循"随机生成、集群一致、集群间互异、避开全部特殊字符"的纪律,并结合 EMQX_NODE__COOKIE 环境变量或 file:// 文件来源进行安全分发,从而从配置源头规避集群互信故障。