尧图网页设计 
密码学【免费下载链接】BLAKE3the official Rust and C implementations of the BLAKE3 cryptographic hash function项目地址https://gitcode.com/GitHub_Trending/bl/BLAKE3点击查看免费下载b3sum --check是 BLAKE3 官方 Rust/C 实现仓库中命令行工具b3sum的校验模式它读取一份校验清单checkfile即普通b3sum命令的输出重新哈希清单中列出的所有文件并在全部哈希一致时返回成功。本文以 b3sum/what_does_check_do.md 为骨架结合 b3sum/src/main.rs 的源码实现与 b3sum/tests/cli_tests.rs、b3sum/src/unit_tests.rs 的测试用例逐层剖析把文件路径表示为文本这一看似简单的行为背后新行、反斜杠、非法 Unicode、Windows 路径分隔符等边界情况如何被精确定义与处理。读完本文你将完整掌握--check的精确语义、checkfile 的跨平台可移植性设计以及每一条正式规则在源码中的落点。一、简单场景drop-in 替代 md5sum大多数时候b3sum --check是md5sum --check及其他 Coreutils 哈希工具的 drop-in 替代品它消费一份 checkfile一次普通b3sum命令的输出重新哈希其中列出的所有文件若全部哈希仍然正确则返回成功。在包含三个文件的目录里运行b3sum a b c/d输出如下$ echo hi a $ echo lo b $ mkdir c $ echo stuff c/d $ b3sum a b c/d 0b8b60248fad7ac6dfac221b7e01a8b91c772421a15b387dd1fb2d6a94aee438 a 6ae4a57bbba24f79c461d30bcb4db973b9427d9207877e34d2d74528daa84115 b 2d477356c962e54784f1c5dc5297718d92087006f6ee96b08aeaf7f3cd252377 c/d每行的格式是64位小写十六进制哈希 文件路径哈希与路径之间是两个空格。将其通过管道喂给--check进程以状态码 0成功退出并打印$ b3sum a b c/d | b3sum --check a: OK b: OK c/d: OK如果删掉b、修改c/d的内容再用同一份 checkfile 校验进程以非零状态码失败退出并打印$ b3sum a b c/d checkfile $ rm b $ echo more stuff c/d $ b3sum --check checkfile a: OK b: FAILED (No such file or directory (os error 2)) c/d: FAILED在这类典型场景中b3sum与md5sum的成功输出完全相同失败输出也非常相似找不到文件时附带操作系统错误信息哈希不匹配时仅输出FAILED。命令行用法与退出码语义--check的实际参数定义位于 b3sum/src/main.rs 的Inner结构体中短选项-c且与--derive-key、--keyed、--length、--raw、--tag、--no-names互斥只能与--quiet联用--quiet要求必须配合--check用于跳过每个文件的OK打印但不会隐藏FAILED。在 b3sum/README.md 中列出的完整用法为Usage: b3sum [OPTIONS] [FILE]... Arguments: [FILE]... Files to hash, or checkfiles to check Options: -c, --check Read BLAKE3 sums from the [FILE]s and check them --quiet Skip printing OK for each checked filecheckfile 既可以作为命令行参数传入也可以通过-或 stdin 管道传入b3sum/src/main.rs 的check_one_checkfile对-路径走 stdin 分支。退出码的精确语义在main函数中实现b3sum/src/main.rs用一个files_failed计数器累计失败行数任一失败则最终std::process::exit(1)全部通过则exit(0)失败时还会向 stderr 打印汇总警告例如b3sum: WARNING: 1 computed checksum did NOT match单复数形式会随失败数量变化。计数器使用saturating_add递增源码注释特别指出这保证了计数器永不溢出从而保证files_failed 0即表示存在不匹配这一判断的可靠性。二、重要警示--check 不是目录完整性工具[!CAUTION]b3sum --check与所有 Coreutils 的--check特性一样只能告诉你某些文件路径是否发生了变化无法一般性地告诉你某个目录是否发生了变化。如果你用b3sum my_dir/* CHECKFILE创建 checkfile那么在向my_dir添加新文件之后b3sum --check CHECKFILE仍会成功。而在不改动其他内容的情况下添加新文件往往足以执行任意代码——例如在 Python 中遮蔽一个import或往.git/hooks里安装东西。这很容易造成混淆因此不建议在新代码中把--check当作安全工具使用。这段警示直接写在该文档的醒目位置是所有使用者必须记住的第一条边界--check校验的是已列出文件的哈希而不是目录的快照。要做目录级完整性需要另行设计文件清单的哈希或目录遍历方案。三、转义换行与反斜杠由于 checkfile 格式也就是b3sum的常规输出格式是换行分隔的文本必须考虑文件路径中包含换行符甚至更糟时会发生什么。假设创建一个名为x[换行]x3 个字符的文件例如用 Python 一行创建 open(x\nx, w)对它执行b3sum$ b3sum x* \af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262 x\nx注意两点其一b3sum在行首放了一个单独的\字符表示该文件路径包含转义序列--check需要先反转义其二b3sum把文件路径中的换行符替换成两字符转义序列\n。类似地如果路径包含回车符或反斜杠输出中会分别转义为\r和\\。到目前为止这些行为与md5sum完全一致Coreutils 在 v9.0即 2021 年 9 月引入了\r转义。源码中的转义实现输出侧的转义由filepath_to_string完成b3sum/src/main.rs它返回(字符串, 是否转义)二元组let mut is_escaped false; if filepath_string.contains([\\, \n, \r]) { filepath_string filepath_string .replace(\\, \\\\) .replace(\n, \\n) .replace(\r, \\r); is_escaped true; }当is_escaped为真时输出前会在行首打印一个\见hash_one_input中if is_escaped { print!(\\); }。注意这里有一个细节转义判定与替换是按路径整体处理的只要路径中含反斜杠、换行、回车三者之一整条路径的所有相关字符都会被转义并加前缀。对应的单元测试在 b3sum/src/unit_tests.rs 的test_filepath_to_string中对路径f\\ \t\r\nooUnix 下期望得到f\\\\ \t\\r\\noo且is_escaped为真Windows 下由于反斜杠会被归一化为正斜杠期望值为f/ \t\\r\\noo。检查侧的反转义实现检查侧的反转义由unescape完成b3sum/src/main.rs它逐段查找\并严格匹配后续字符n unescaped.push_str(\n), r unescaped.push_str(\r), \\ unescaped.push_str(\\), _ bail!(Invalid backslash escape),任何非\n、\r、\\的转义序列都会直接报错行尾孤立的反斜杠i path.len() - 1不成立同样报错。单元测试 b3sum/src/unit_tests.rs 的test_parse_check_line验证了fo\r\n\n\ro反转为fo\r\n\n\ro真实路径、fo\n\\o反转为fo\n\o真实路径也验证了非法转义fo\o与截断转义foo\均失败。集成测试 b3sum/tests/cli_tests.rs 的test_check_invalid_characters还以整行\...\a验证了b3sum: Invalid backslash escape的 stderr 输出与 WARNING 汇总。四、非法 Unicodeb3sum 与 md5sum 的分歧点除了上述换行与反斜杠转义md5sum会把所有其他路径字节原样复制到输出中其输出编码是ASCII 加上命令行拿到的任意字节。这带来两个问题打印非 UTF-8 内容不太体面Windows 支持问题。Unix 与 Windows 的路径表示差异Unix 与 Windows 对文件路径的底层表示有根本差异Unix 路径通常是 UTF-8Windows 路径通常是 UTF-16。文件abc在 Unix 上通常表示为字节[97, 98, 99]在 Windows 上则通常表示为字节[97, 0, 98, 0, 99, 0]。如果沿用md5sum的做法就无法实现在 Unix 上创建 checkfile、在 Windows 上检查或反向的可移植性。一个更可移植的做法是把平台相关的字节转换为某种一致的 Unicode 编码实践中就是 UTF-8理论上可以是任何编码当--check需要打开文件时再把 Unicode 表示转换回平台相关字节。这样abc乃至abc[换行]def这类常见情况都能正常工作。不是所有字节都是合法 UTF-8/UTF-16但上面通常二字意味着例外并非每个可能的字节序列都是合法 UTF-8也不是每个 16 位宽字符序列都是合法 UTF-16。例如字节 0xFF255永远不会出现在任何 UTF-8 字符串中Python 解码它会直接报错 b\xFF.decode(UTF-8) UnicodeDecodeError: utf-8 codec cant decode byte 0xff in position 0: invalid start byte但遗憾的是我们确实可以创建名字里带这个字节的文件至少在 Linux 上可以macOS 通常不行 open(by\xFFy, w)也就是说某些文件路径根本无法用 Unicode 表示。把平台字节转成一致 Unicode 编码的方案并不能覆盖一切。b3sum对上述文件会输出$ b3sum y* af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262 yy路径中间的 是 Unicode 替换字符UFFFD。当遇到无法用 Unicode 表示的路径时b3sum把不可表示的部分替换为这些替换字符。而在检查侧为避免两个不同的非法路径之间产生任何混淆只要看到替换字符就自动判定失败见下文正式规则第 7 条及其源码实现check_for_invalid_characters。由此获得的五个重要性质配合下一节的其他细节这套设计保证了任何文件都可以在本地完成哈希任何名字为合法 Unicode 且不含 字符的文件都可以被检查检查有歧义或不可表示的路径总是失败checkfile 始终是合法 UTF-8checkfile 可以在 Unix 与 Windows 之间移植。源码层面输出侧的 UTF-8 转换正是OsStr::to_string_lossy见filepath_to_string第一行let unicode_cow filepath.to_string_lossy();它正是把非法 UTF-8 段替换为 UFFFD 的标准 Rust 机制而输入路径在 Rust 中的平台相关表示是OsStr/OsString。Windows 特有的路径归一化在filepath_to_string中还有一段 Windows 专属逻辑cfg!(windows)时所有反斜杠被替换为正斜杠if cfg!(windows) { filepath_string filepath_string.replace(\\, /); }源码注释解释了动机这避免了常见场景中大量丑陋的转义使 Windows 上生成的 checkfile 更可能移植到 Unix同时允许设定Windows 上 checkfile 不允许任何反斜杠的一刀切规则避免 Unix 的反斜杠在 Windows 上被误读为目录分隔符。五、正式规则--check 的完整精确语义原文档以 9 条正式规则总结了全部行为这里逐条列出后两条仅适用于 Windows哈希侧规则 1–4哈希时文件路径以平台相关编码表示可以容纳当前平台上的任意路径Rust 中即OsStr/OsString。输出时文件路径先转换为 UTF-8任何非 Unicode 片段替换为 Unicode 替换字符UFFFDRust 中即OsStr::to_string_lossy。然后如果路径包含任何反斜杠U005C或换行符U000A分别转义为\\与\n。最后任何包含转义序列的输出行行首加一个单独的反斜杠作为前缀。检查侧规则 5–7检查时每行按 UTF-8 解析、以换行符U000A分隔非法 UTF-8 视为错误。若行首是反斜杠则对路径部分进行反转义除\\与\n外的任何转义序列都是错误。若行首不是反斜杠则不做反转义路径部分的任何反斜杠按字面解释b3sum的输出永不含未转义反斜杠但手工拼写的 checkfile 里可能出现。最后若路径包含 Unicode 替换字符UFFFD或空字符U0000视为错误。Windows 专属规则 8–9输出时所有反斜杠U005C替换为正斜杠U002F。检查时反转义之后若路径仍含反斜杠视为错误。每条规则的源码落点规则 2、3、4 落在filepath_to_stringb3sum/src/main.rs规则 8 也在此实现。规则 5、6、7、9 落在parse_check_line及其调用的unescape与check_for_invalid_characters空行与行首斜杠parse_check_line先trim_end_matches([\r, \n])去掉尾部回车/换行因此 Windows 风格的\r\n行尾也能正确处理见 b3sum/tests/cli_tests.rs 中test_check用\r\n替换\n后校验仍全部 OK 的断言首字符为\则置is_escaped并去掉该前缀空行直接报Empty line。行格式解析无--tag的行按hash file从左侧切分因为文件名本身可能包含两个空格--tag产生的 BSD 风格行BLAKE3 (file) hash则从右侧切分文件名可能包含) 。单元测试分别验证了路径foo bar与foo) bar能正确还原b3sum/src/unit_tests.rs。哈希十六进制解析长度必须恰好为2 * blake3::OUT_LEN即 64 个十六进制字符仅接受小写0-9a-f大写字母Invalid hex报错路径之一见单元测试中大写A...用例与非法字符一律失败两个空格分隔符缺一不可单空格用例报错。非法字符检查check_for_invalid_characters依次拒绝空字符源码注释说明Unix 上空字符可能导致路径被静默截断、UFFFD 替换字符多个不同非法路径可能映射到同一 UTF-8 字符串必须杜绝这种混淆、以及 Windows 上的反斜杠。对应集成测试 b3sum/tests/cli_tests.rs 的test_check_invalid_characters分别验证了Null character in path、Unicode replacement character in path、Backslash in path三种 stderr 报错。非转义行中的字面反斜杠规则 6 的行首无反斜杠则按字面解释在parse_check_line中体现为file_str.to_string()原样保留单元测试验证了 Unix 下fo\a\no其中\a不是转义序列作为字面路径被接受同时\o、foo\等出现在转义行中则报Invalid backslash escape。安全取向宁可多失败不可误成功源码注释为这套严格规则给出了明确的设计哲学见 b3sum/src/main.rs 中check_for_invalid_characters上方的说明check命令是安全工具。校验失败得比应该失败的次数更多假阴性远好于校验在不应成功时成功假阳性。通过禁止被检查路径中的某些字符我们避免了一类两个不同路径相互混淆的假阳性。这正是规则 7、9 的精神内核在可移植性与安全性之间选择宁可拒绝可疑输入。六、校验输出格式与退出行为总结结合check_one_lineb3sum/src/main.rs的实现校验时的输出与退出行为可归纳为每个文件打印路径: OK或路径: FAILED打开失败时打印路径: FAILED (操作系统错误)。报告时会把转义前缀还原显示is_escaped时重新在file_string前补回\与 checkfile 中的写法一致。哈希比较使用blake3::Hash的相等判断源码注释明确其为常数时间比较。任一失败则累计计数最终 stderr 打印b3sum: WARNING: N computed checksum(s) did NOT match进程以状态码 1 退出全部通过则以 0 退出。解析失败如空行、非法十六进制、非法转义、非法字符不打印FAILED行而是打印b3sum: 错误信息并计入失败总数。集成测试 b3sum/tests/cli_tests.rs 的test_check完整覆盖了普通输出与--tag输出均可作为 checkfile 通过 stdin 校验、Windows 风格行尾、同一 checkfile 传入两次时输出重复两遍、篡改文件后b: FAILED、删除文件后b: FAILED (文件打开错误)、--quiet抑制 OK 但保留 FAILED以及每次失败后的 WARNING 汇总文本。七、结语与进一步阅读b3sum --check的复杂度全部源于把文件路径表示为文本这一操作换行与反斜杠需要转义非 UTF-8 字节需要替换字符兜底Unix 与 Windows 的路径表示差异需要归一化而检查侧则用遇到歧义宁可失败的原则换取安全性。这 9 条正式规则既是行为规范也几乎逐条对应 b3sum/src/main.rs 中的实现函数并被 b3sum/tests/cli_tests.rs 与 b3sum/src/unit_tests.rs 的用例双向锁定。如需继续深入建议按以下顺序阅读仓库内容行为规范原文b3sum/what_does_check_do.md命令行入口与全部参数b3sum/src/main.rs端到端校验测试含--tag、--quiet、Windows 行尾b3sum/tests/cli_tests.rs行解析与转义的单元测试b3sum/src/unit_tests.rs工具用法速查与安装方式b3sum/README.md赞分享密码学【免费下载链接】BLAKE3the official Rust and C implementations of the BLAKE3 cryptographic hash function项目地址https://gitcode.com/GitHub_Trending/bl/BLAKE3点击查看免费下载相关推荐b3sum --check 行为精解BLAKE3 校验文件中文件路径的文本表示、转义规则与跨平台可移植性b3sum check 行为精解BLAKE3 校验文件中文件路径的文本表示、转义规则与跨平台可移植性 b3sum 是 BLAKE3 哈希算法的官方命令行工具开发工具构建工具系统编程Zettlr 渲染边界情况深度剖析标签、链接、转义与高亮解析规则全解Zettlr 渲染边界情况深度剖析标签、链接、转义与高亮解析规则全解 本文以 Zettlr 渲染回归测试文档 Miscellaneous Rendering桌面应用前端知识管理科研上一篇ConsistentID部署指南高性能GPU环境下的模型优化方案下一篇GaLore训练日志挖掘使用ELK栈分析大规模实验数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 b3sum --check 行为全解析：文件路径文本化带来的边界情况与正式规则
密码学【免费下载链接】BLAKE3the official Rust and C implementations of the BLAKE3 cryptographic hash function项目地址https://gitcode.com/GitHub_Trending/bl/BLAKE3点击查看免费下载b3sum --check是 BLAKE3 官方 Rust/C 实现仓库中命令行工具b3sum的校验模式它读取一份校验清单checkfile即普通b3sum命令的输出重新哈希清单中列出的所有文件并在全部哈希一致时返回成功。本文以 b3sum/what_does_check_do.md 为骨架结合 b3sum/src/main.rs 的源码实现与 b3sum/tests/cli_tests.rs、b3sum/src/unit_tests.rs 的测试用例逐层剖析把文件路径表示为文本这一看似简单的行为背后新行、反斜杠、非法 Unicode、Windows 路径分隔符等边界情况如何被精确定义与处理。读完本文你将完整掌握--check的精确语义、checkfile 的跨平台可移植性设计以及每一条正式规则在源码中的落点。一、简单场景drop-in 替代 md5sum大多数时候b3sum --check是md5sum --check及其他 Coreutils 哈希工具的 drop-in 替代品它消费一份 checkfile一次普通b3sum命令的输出重新哈希其中列出的所有文件若全部哈希仍然正确则返回成功。在包含三个文件的目录里运行b3sum a b c/d输出如下$ echo hi a $ echo lo b $ mkdir c $ echo stuff c/d $ b3sum a b c/d 0b8b60248fad7ac6dfac221b7e01a8b91c772421a15b387dd1fb2d6a94aee438 a 6ae4a57bbba24f79c461d30bcb4db973b9427d9207877e34d2d74528daa84115 b 2d477356c962e54784f1c5dc5297718d92087006f6ee96b08aeaf7f3cd252377 c/d每行的格式是64位小写十六进制哈希 文件路径哈希与路径之间是两个空格。将其通过管道喂给--check进程以状态码 0成功退出并打印$ b3sum a b c/d | b3sum --check a: OK b: OK c/d: OK如果删掉b、修改c/d的内容再用同一份 checkfile 校验进程以非零状态码失败退出并打印$ b3sum a b c/d checkfile $ rm b $ echo more stuff c/d $ b3sum --check checkfile a: OK b: FAILED (No such file or directory (os error 2)) c/d: FAILED在这类典型场景中b3sum与md5sum的成功输出完全相同失败输出也非常相似找不到文件时附带操作系统错误信息哈希不匹配时仅输出FAILED。命令行用法与退出码语义--check的实际参数定义位于 b3sum/src/main.rs 的Inner结构体中短选项-c且与--derive-key、--keyed、--length、--raw、--tag、--no-names互斥只能与--quiet联用--quiet要求必须配合--check用于跳过每个文件的OK打印但不会隐藏FAILED。在 b3sum/README.md 中列出的完整用法为Usage: b3sum [OPTIONS] [FILE]... Arguments: [FILE]... Files to hash, or checkfiles to check Options: -c, --check Read BLAKE3 sums from the [FILE]s and check them --quiet Skip printing OK for each checked filecheckfile 既可以作为命令行参数传入也可以通过-或 stdin 管道传入b3sum/src/main.rs 的check_one_checkfile对-路径走 stdin 分支。退出码的精确语义在main函数中实现b3sum/src/main.rs用一个files_failed计数器累计失败行数任一失败则最终std::process::exit(1)全部通过则exit(0)失败时还会向 stderr 打印汇总警告例如b3sum: WARNING: 1 computed checksum did NOT match单复数形式会随失败数量变化。计数器使用saturating_add递增源码注释特别指出这保证了计数器永不溢出从而保证files_failed 0即表示存在不匹配这一判断的可靠性。二、重要警示--check 不是目录完整性工具[!CAUTION]b3sum --check与所有 Coreutils 的--check特性一样只能告诉你某些文件路径是否发生了变化无法一般性地告诉你某个目录是否发生了变化。如果你用b3sum my_dir/* CHECKFILE创建 checkfile那么在向my_dir添加新文件之后b3sum --check CHECKFILE仍会成功。而在不改动其他内容的情况下添加新文件往往足以执行任意代码——例如在 Python 中遮蔽一个import或往.git/hooks里安装东西。这很容易造成混淆因此不建议在新代码中把--check当作安全工具使用。这段警示直接写在该文档的醒目位置是所有使用者必须记住的第一条边界--check校验的是已列出文件的哈希而不是目录的快照。要做目录级完整性需要另行设计文件清单的哈希或目录遍历方案。三、转义换行与反斜杠由于 checkfile 格式也就是b3sum的常规输出格式是换行分隔的文本必须考虑文件路径中包含换行符甚至更糟时会发生什么。假设创建一个名为x[换行]x3 个字符的文件例如用 Python 一行创建 open(x\nx, w)对它执行b3sum$ b3sum x* \af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262 x\nx注意两点其一b3sum在行首放了一个单独的\字符表示该文件路径包含转义序列--check需要先反转义其二b3sum把文件路径中的换行符替换成两字符转义序列\n。类似地如果路径包含回车符或反斜杠输出中会分别转义为\r和\\。到目前为止这些行为与md5sum完全一致Coreutils 在 v9.0即 2021 年 9 月引入了\r转义。源码中的转义实现输出侧的转义由filepath_to_string完成b3sum/src/main.rs它返回(字符串, 是否转义)二元组let mut is_escaped false; if filepath_string.contains([\\, \n, \r]) { filepath_string filepath_string .replace(\\, \\\\) .replace(\n, \\n) .replace(\r, \\r); is_escaped true; }当is_escaped为真时输出前会在行首打印一个\见hash_one_input中if is_escaped { print!(\\); }。注意这里有一个细节转义判定与替换是按路径整体处理的只要路径中含反斜杠、换行、回车三者之一整条路径的所有相关字符都会被转义并加前缀。对应的单元测试在 b3sum/src/unit_tests.rs 的test_filepath_to_string中对路径f\\ \t\r\nooUnix 下期望得到f\\\\ \t\\r\\noo且is_escaped为真Windows 下由于反斜杠会被归一化为正斜杠期望值为f/ \t\\r\\noo。检查侧的反转义实现检查侧的反转义由unescape完成b3sum/src/main.rs它逐段查找\并严格匹配后续字符n unescaped.push_str(\n), r unescaped.push_str(\r), \\ unescaped.push_str(\\), _ bail!(Invalid backslash escape),任何非\n、\r、\\的转义序列都会直接报错行尾孤立的反斜杠i path.len() - 1不成立同样报错。单元测试 b3sum/src/unit_tests.rs 的test_parse_check_line验证了fo\r\n\n\ro反转为fo\r\n\n\ro真实路径、fo\n\\o反转为fo\n\o真实路径也验证了非法转义fo\o与截断转义foo\均失败。集成测试 b3sum/tests/cli_tests.rs 的test_check_invalid_characters还以整行\...\a验证了b3sum: Invalid backslash escape的 stderr 输出与 WARNING 汇总。四、非法 Unicodeb3sum 与 md5sum 的分歧点除了上述换行与反斜杠转义md5sum会把所有其他路径字节原样复制到输出中其输出编码是ASCII 加上命令行拿到的任意字节。这带来两个问题打印非 UTF-8 内容不太体面Windows 支持问题。Unix 与 Windows 的路径表示差异Unix 与 Windows 对文件路径的底层表示有根本差异Unix 路径通常是 UTF-8Windows 路径通常是 UTF-16。文件abc在 Unix 上通常表示为字节[97, 98, 99]在 Windows 上则通常表示为字节[97, 0, 98, 0, 99, 0]。如果沿用md5sum的做法就无法实现在 Unix 上创建 checkfile、在 Windows 上检查或反向的可移植性。一个更可移植的做法是把平台相关的字节转换为某种一致的 Unicode 编码实践中就是 UTF-8理论上可以是任何编码当--check需要打开文件时再把 Unicode 表示转换回平台相关字节。这样abc乃至abc[换行]def这类常见情况都能正常工作。不是所有字节都是合法 UTF-8/UTF-16但上面通常二字意味着例外并非每个可能的字节序列都是合法 UTF-8也不是每个 16 位宽字符序列都是合法 UTF-16。例如字节 0xFF255永远不会出现在任何 UTF-8 字符串中Python 解码它会直接报错 b\xFF.decode(UTF-8) UnicodeDecodeError: utf-8 codec cant decode byte 0xff in position 0: invalid start byte但遗憾的是我们确实可以创建名字里带这个字节的文件至少在 Linux 上可以macOS 通常不行 open(by\xFFy, w)也就是说某些文件路径根本无法用 Unicode 表示。把平台字节转成一致 Unicode 编码的方案并不能覆盖一切。b3sum对上述文件会输出$ b3sum y* af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262 yy路径中间的 是 Unicode 替换字符UFFFD。当遇到无法用 Unicode 表示的路径时b3sum把不可表示的部分替换为这些替换字符。而在检查侧为避免两个不同的非法路径之间产生任何混淆只要看到替换字符就自动判定失败见下文正式规则第 7 条及其源码实现check_for_invalid_characters。由此获得的五个重要性质配合下一节的其他细节这套设计保证了任何文件都可以在本地完成哈希任何名字为合法 Unicode 且不含 字符的文件都可以被检查检查有歧义或不可表示的路径总是失败checkfile 始终是合法 UTF-8checkfile 可以在 Unix 与 Windows 之间移植。源码层面输出侧的 UTF-8 转换正是OsStr::to_string_lossy见filepath_to_string第一行let unicode_cow filepath.to_string_lossy();它正是把非法 UTF-8 段替换为 UFFFD 的标准 Rust 机制而输入路径在 Rust 中的平台相关表示是OsStr/OsString。Windows 特有的路径归一化在filepath_to_string中还有一段 Windows 专属逻辑cfg!(windows)时所有反斜杠被替换为正斜杠if cfg!(windows) { filepath_string filepath_string.replace(\\, /); }源码注释解释了动机这避免了常见场景中大量丑陋的转义使 Windows 上生成的 checkfile 更可能移植到 Unix同时允许设定Windows 上 checkfile 不允许任何反斜杠的一刀切规则避免 Unix 的反斜杠在 Windows 上被误读为目录分隔符。五、正式规则--check 的完整精确语义原文档以 9 条正式规则总结了全部行为这里逐条列出后两条仅适用于 Windows哈希侧规则 1–4哈希时文件路径以平台相关编码表示可以容纳当前平台上的任意路径Rust 中即OsStr/OsString。输出时文件路径先转换为 UTF-8任何非 Unicode 片段替换为 Unicode 替换字符UFFFDRust 中即OsStr::to_string_lossy。然后如果路径包含任何反斜杠U005C或换行符U000A分别转义为\\与\n。最后任何包含转义序列的输出行行首加一个单独的反斜杠作为前缀。检查侧规则 5–7检查时每行按 UTF-8 解析、以换行符U000A分隔非法 UTF-8 视为错误。若行首是反斜杠则对路径部分进行反转义除\\与\n外的任何转义序列都是错误。若行首不是反斜杠则不做反转义路径部分的任何反斜杠按字面解释b3sum的输出永不含未转义反斜杠但手工拼写的 checkfile 里可能出现。最后若路径包含 Unicode 替换字符UFFFD或空字符U0000视为错误。Windows 专属规则 8–9输出时所有反斜杠U005C替换为正斜杠U002F。检查时反转义之后若路径仍含反斜杠视为错误。每条规则的源码落点规则 2、3、4 落在filepath_to_stringb3sum/src/main.rs规则 8 也在此实现。规则 5、6、7、9 落在parse_check_line及其调用的unescape与check_for_invalid_characters空行与行首斜杠parse_check_line先trim_end_matches([\r, \n])去掉尾部回车/换行因此 Windows 风格的\r\n行尾也能正确处理见 b3sum/tests/cli_tests.rs 中test_check用\r\n替换\n后校验仍全部 OK 的断言首字符为\则置is_escaped并去掉该前缀空行直接报Empty line。行格式解析无--tag的行按hash file从左侧切分因为文件名本身可能包含两个空格--tag产生的 BSD 风格行BLAKE3 (file) hash则从右侧切分文件名可能包含) 。单元测试分别验证了路径foo bar与foo) bar能正确还原b3sum/src/unit_tests.rs。哈希十六进制解析长度必须恰好为2 * blake3::OUT_LEN即 64 个十六进制字符仅接受小写0-9a-f大写字母Invalid hex报错路径之一见单元测试中大写A...用例与非法字符一律失败两个空格分隔符缺一不可单空格用例报错。非法字符检查check_for_invalid_characters依次拒绝空字符源码注释说明Unix 上空字符可能导致路径被静默截断、UFFFD 替换字符多个不同非法路径可能映射到同一 UTF-8 字符串必须杜绝这种混淆、以及 Windows 上的反斜杠。对应集成测试 b3sum/tests/cli_tests.rs 的test_check_invalid_characters分别验证了Null character in path、Unicode replacement character in path、Backslash in path三种 stderr 报错。非转义行中的字面反斜杠规则 6 的行首无反斜杠则按字面解释在parse_check_line中体现为file_str.to_string()原样保留单元测试验证了 Unix 下fo\a\no其中\a不是转义序列作为字面路径被接受同时\o、foo\等出现在转义行中则报Invalid backslash escape。安全取向宁可多失败不可误成功源码注释为这套严格规则给出了明确的设计哲学见 b3sum/src/main.rs 中check_for_invalid_characters上方的说明check命令是安全工具。校验失败得比应该失败的次数更多假阴性远好于校验在不应成功时成功假阳性。通过禁止被检查路径中的某些字符我们避免了一类两个不同路径相互混淆的假阳性。这正是规则 7、9 的精神内核在可移植性与安全性之间选择宁可拒绝可疑输入。六、校验输出格式与退出行为总结结合check_one_lineb3sum/src/main.rs的实现校验时的输出与退出行为可归纳为每个文件打印路径: OK或路径: FAILED打开失败时打印路径: FAILED (操作系统错误)。报告时会把转义前缀还原显示is_escaped时重新在file_string前补回\与 checkfile 中的写法一致。哈希比较使用blake3::Hash的相等判断源码注释明确其为常数时间比较。任一失败则累计计数最终 stderr 打印b3sum: WARNING: N computed checksum(s) did NOT match进程以状态码 1 退出全部通过则以 0 退出。解析失败如空行、非法十六进制、非法转义、非法字符不打印FAILED行而是打印b3sum: 错误信息并计入失败总数。集成测试 b3sum/tests/cli_tests.rs 的test_check完整覆盖了普通输出与--tag输出均可作为 checkfile 通过 stdin 校验、Windows 风格行尾、同一 checkfile 传入两次时输出重复两遍、篡改文件后b: FAILED、删除文件后b: FAILED (文件打开错误)、--quiet抑制 OK 但保留 FAILED以及每次失败后的 WARNING 汇总文本。七、结语与进一步阅读b3sum --check的复杂度全部源于把文件路径表示为文本这一操作换行与反斜杠需要转义非 UTF-8 字节需要替换字符兜底Unix 与 Windows 的路径表示差异需要归一化而检查侧则用遇到歧义宁可失败的原则换取安全性。这 9 条正式规则既是行为规范也几乎逐条对应 b3sum/src/main.rs 中的实现函数并被 b3sum/tests/cli_tests.rs 与 b3sum/src/unit_tests.rs 的用例双向锁定。如需继续深入建议按以下顺序阅读仓库内容行为规范原文b3sum/what_does_check_do.md命令行入口与全部参数b3sum/src/main.rs端到端校验测试含--tag、--quiet、Windows 行尾b3sum/tests/cli_tests.rs行解析与转义的单元测试b3sum/src/unit_tests.rs工具用法速查与安装方式b3sum/README.md赞分享密码学【免费下载链接】BLAKE3the official Rust and C implementations of the BLAKE3 cryptographic hash function项目地址https://gitcode.com/GitHub_Trending/bl/BLAKE3点击查看免费下载相关推荐b3sum --check 行为精解BLAKE3 校验文件中文件路径的文本表示、转义规则与跨平台可移植性b3sum check 行为精解BLAKE3 校验文件中文件路径的文本表示、转义规则与跨平台可移植性 b3sum 是 BLAKE3 哈希算法的官方命令行工具开发工具构建工具系统编程Zettlr 渲染边界情况深度剖析标签、链接、转义与高亮解析规则全解Zettlr 渲染边界情况深度剖析标签、链接、转义与高亮解析规则全解 本文以 Zettlr 渲染回归测试文档 Miscellaneous Rendering桌面应用前端知识管理科研上一篇ConsistentID部署指南高性能GPU环境下的模型优化方案下一篇GaLore训练日志挖掘使用ELK栈分析大规模实验数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考