Go x/text/secure/precis OpaqueString 为什么不能等同任意二进制口令

如果你在 Go 里看到 precis.OpaqueString，很容易把“Opaque”理解成“什么字节都能装”。它真正描述的是密码或其他安全标签的 Unicode 字符串规范：输入要按 PRECIS 的 FreeformClass 解释，再执行指定的映射、规范化和校验。因此，它适合用户输入的口令字符串，不等于可以接收任意 []byte 密钥、随机数或二进制协议字段。

官方地址：https://pkg.go.dev/golang.org/x/text/secure/precis

结论先说：OpaqueString 解决的是“同一个口令字符串如何被一致地准备和比较”，不是“如何保存任意二进制秘密”。用户口令先按 profile 处理；随机字节、密钥和 nonce 则保持 []byte，交给对应的密码学 API。

先区分字符串口令和二进制秘密

Go 的 string 底层确实可以携带任意字节，但这不代表所有接收 string 的 API 都把它当作“无语义的字节数组”。precis.Profile 的文档把输入定义在 UTF-8 编码的 Unicode 字符串上，NewTransformer 也明确执行 UTF-8 字节的准备与强制处理。

所以，问题不在于名称里有没有 Opaque，而在于这条 API 链路是否要解释字符。口令通常来自文本输入，用户可能输入不同的 Unicode 空格或组合字符；随机密钥则要求每个字节按原样保留，二者是两种不同的数据契约。

OpaqueString 实际会处理哪些规则

官方 RFC 8265 将 OpaqueString 建立在 FreeformClass 上，并为 enforcement 规定了固定顺序。理解这些规则，就能看出它为什么不是任意二进制容器。

• 不做全角、半角宽度映射：与标识符 profile 不同，OpaqueString 保留这类字符差异，避免口令被无意合并。
• 非 ASCII 空格映射为普通空格：各种 Unicode 空白字符会被统一到 U+0020，减少输入法和复制过程造成的不可见差异。
• 不做大小写映射：A 和 a 不会因为 profile 自动变成同一个口令，避免产生错误接受。
• 执行 NFC：组合字符和预组合字符按 Unicode NFC 规范化，保证等价文本按同一准备规则进入后续计算。
• 没有 Bidi 规则：密码通常不展示，RFC 认为额外的方向性限制可能缩小口令字符集合。

这些行为会改变或拒绝某些输入的字符表示，但不会把 profile 变成二进制编码器。尤其是非 ASCII 空格映射和 NFC，都说明输入正在按字符语义被解释。

用 Profile API 规范化用户口令

对来自登录表单、配置文件或协议字段的文本口令，可以在交给既有密码哈希或认证计算前调用 OpaqueString.String。示例只演示规范化边界；生产环境仍应使用项目既有的密码哈希/KDF、盐和升级策略。

package password

import (
    "fmt"

    "golang.org/x/text/secure/precis"
)

func preparePassword(input string) (string, error) {
    // OpaqueString 按 Unicode 口令规则处理字符串，不负责保存或哈希密码。
    prepared, err := precis.OpaqueString.String(input)
    if err != nil {
        // 输入不符合 FreeformClass 时，把错误返回给认证层，不要静默替换。
        return "", fmt.Errorf("prepare password: %w", err)
    }
    // 调用方应把 prepared 交给既有的密码哈希/KDF，而不是直接存储明文。
    return prepared, nil
}

如果需要追加到已有缓冲区，也可以使用 Append；如果输入已经是 UTF-8 字节，则使用 Bytes 并保留错误结果。API 的返回值是“处理后的字符串/字节和错误”，不是“原样回显的字节”。

为什么任意二进制输入会在这里失去语义

任意二进制秘密可能包含零字节、非 UTF-8 序列，或者只是协议定义的随机字节。把它强行转换成字符串再送进 OpaqueString，会遇到两类风险：输入可能无法按 UTF-8 被接受；即使能接受，Unicode 规范化或空格映射也意味着它不是字节级不变的通道。

下面的示例故意使用一段不完整的 UTF-8 序列。它表达的是“这不是 OpaqueString 的输入契约”，不是一个密码破解或绕过示例。

package binarysecret

import (
    "fmt"

    "golang.org/x/text/secure/precis"
)

func rejectArbitraryBytes(raw []byte) error {
    // 0xc3 后缺少后续字节，故意构造非完整 UTF-8；二进制秘密不应靠 string 转换修复。
    _, err := precis.OpaqueString.Bytes(raw)
    if err != nil {
        // 保留原始错误，让调用方改走字节级协议，而不是静默替换字节。
        return fmt.Errorf("binary secret is not an OpaqueString: %w", err)
    }
    return nil
}

即使某段随机字节恰好“看起来像合法 UTF-8”，也不应因此把它当作口令字符串。是否允许规范化、是否允许空格折叠、是否要求跨语言可互操作，都应由上层协议决定；密钥材料则通常要求原样交给密钥派生、加解密或签名 API。

按场景选择正确的路径

如果业务确实需要把密钥变成可复制文本，应先明确编码格式，再把“编码后的文本”当作文本处理。不要直接把原始密钥的每个字节解释成 Unicode 字符，也不要依赖 string(raw) 让语义自动成立。

常见误区与排查顺序

1. 先问输入是“用户能输入的口令”还是“程序生成的秘密材料”。前者才进入 OpaqueString 的讨论范围。
2. 再确认双方是否使用同一个 profile 和同一套处理时机。客户端先处理、服务端再重复处理，可能造成协议不一致。
3. 检查是否把错误返回值丢掉。String、Bytes 和 Append 都可能因为输入不符合规则而失败。
4. 最后检查存储方案。规范化不是密码哈希，OpaqueString 也不会替代盐、KDF、升级策略和认证失败控制。

另外，pkg.go.dev 当前提示 precis 包仍在建设中，API 可能发生不兼容变化。对需要长期协议兼容的系统，应锁定依赖版本，并把 profile 选择写进协议或迁移说明，而不是只靠函数名猜行为。

结论

OpaqueString 中的 “Opaque” 指向口令在应用协议中的不透明语义，不是“任意字节原样通过”。它建立在 Unicode 字符串和 PRECIS 规则之上：非 ASCII 空格会映射、文本会做 NFC、大小写不会自动折叠，输入还必须满足相应的字符串类别。用户口令可按此规则准备后再进入认证计算；密钥、随机数、nonce 和其他二进制秘密应保持 []byte，按各自协议直接处理。

相关问题

• OpaqueString 会自动把大写密码转成小写吗？不会，RFC 8265 明确没有大小写映射规则。
• 非 ASCII 空格会保留吗？会被映射为普通空格 U+0020。
• OpaqueString 能替代密码哈希吗？不能，它只负责字符串的准备、强制和比较规则。
• 二进制密钥要转成文本怎么办？先使用协议规定的 Base64 或十六进制编码，再按文本字段处理。