Go x/text/secure/precis OpaqueString 怎样准备区分大小写的口令文本

我在处理国际化登录表单时，最容易踩的坑不是哈希算法，而是“哈希之前到底拿什么字符串去算”。如果业务要求口令区分大小写，又允许用户输入 Unicode 文本，直接把原始字符串交给后续逻辑会让不同入口的规范化策略不一致。

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

这类场景可以把 precis.OpaqueString 当作统一的口令准备与执行入口：它不做大小写映射，因此不会把 Abc 折叠成 abc；成功得到处理结果后，再交给密码哈希或校验组件。它不是哈希算法，也不替代密码存储方案。

先分清 OpaqueString 负责什么

golang.org/x/text/secure/precis 实现的是 PRECIS 字符串准备、执行和比较相关能力。官方包文档将 OpaqueString 定义为适合密码和其他安全标签的 profile，同时提醒这个包仍在建设中，API 可能发生不兼容变化。

“区分大小写”在这里不是额外开关，而是 profile 的规则边界：OpaqueString 没有大小写映射规则。它会按 Freeform 字符类检查允许的 Unicode 码点，并在执行阶段处理非 ASCII 空格和 NFC 规范化，但不会因为大小写不同就主动合并两个口令。

用 OpaqueString.String 取得处理后的文本

最直接的 API 是 Profile.String。它接收 Go 字符串，返回处理后的字符串和错误。错误不能被忽略：输入不符合 profile 规则时，调用方应该拒绝本次注册或登录，而不是继续拿未经处理的原文计算。

package passwordprep

import (
	"errors"
	"fmt"

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

var ErrEmptyPassword = errors.New("password is empty after PRECIS processing")

// PreparePassword 只负责统一准备口令，不负责哈希和持久化。
func PreparePassword(raw string) (string, error) {
	prepared, err := precis.OpaqueString.String(raw)
	if err != nil {
		return "", fmt.Errorf("prepare password: %w", err) // 输入不符合 profile 时停止后续处理
	}
	if prepared == "" {
		return "", ErrEmptyPassword // 规范化后为空时不能当成有效口令
	}
	return prepared, nil // 大小写仍属于结果的一部分
}

这段函数有两个重要边界。第一，String 的结果才是后续密码处理的输入；第二，空结果要在应用层明确拒绝。RFC 8265 对密码要求在规范化和映射后不能是零字节，不能因为输入在进入 profile 前看起来非空，就跳过结果检查。

例如，英文大写和小写不会被 OpaqueString 自动折叠；而某些 Unicode 空格会按规则映射到普通空格，组合字符则可能通过 NFC 形成稳定表示。这里的“稳定”是为了让不同输入路径使用同一套规则，不等于弱化密码策略。

注册和登录必须共用同一条处理路径

我更推荐把准备动作抽成独立函数，让注册与登录都调用它，再把成功结果交给密码哈希库。这样可以避免注册时处理了文本，登录时却直接拿请求原文校验的分叉。

package auth

import (
	"fmt"

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

// CanonicalPasswordBytes 统一产出哈希或校验前使用的 UTF-8 字节。
func CanonicalPasswordBytes(raw string) ([]byte, error) {
	prepared, err := precis.OpaqueString.String(raw)
	if err != nil {
		return nil, fmt.Errorf("invalid password text: %w", err) // 不把非法文本送入哈希流程
	}
	if prepared == "" {
		return nil, fmt.Errorf("password must not be empty") // 处理后仍要检查空结果
	}
	return []byte(prepared), nil // 实际项目随后交给密码哈希/校验库
}

func registerInput(raw string) ([]byte, error) {
	return CanonicalPasswordBytes(raw) // 注册与登录使用相同的 profile
}

func loginInput(raw string) ([]byte, error) {
	return CanonicalPasswordBytes(raw) // 登录不能自行转小写或跳过规范化
}

这里没有把密码写入日志，也没有试图自行比较明文。真正的密码哈希实现应由专门组件完成；文章中的函数只解决“进入哈希或校验前使用哪一份文本”这个问题。另一个值得保留的事实是，大小写保留并不意味着可以把口令明文存储在数据库里。

不要把 OpaqueString 当成大小写不敏感比较器

如果你的业务确实需要比较两个已经处理过的口令文本，仍然要明确比较语义。OpaqueString 的规范比较要求准备和执行后进行精确的字节级匹配；它不是“忽略大小写”的快捷方式。认证系统通常不应自己做明文比较，而应先处理候选口令，再交给哈希校验组件。

相反，用户名常常会采用另外的 profile，例如 UsernameCaseMapped 或 UsernameCasePreserved。不要因为用户名采用了大小写折叠，就把相同策略套到密码上；不同字段有不同的安全目标。

上线前我会重点看这几个边界

1. 包版本：官方文档明确提示 precis 仍在建设中，升级依赖时要查看 API 变化并固定模块版本。
2. 统一入口：注册、登录、改密和重置密码都调用同一个准备函数，避免某个入口额外调用 strings.ToLower。
3. 结果优先：只有 String 成功且结果非空时，才把文本交给后续哈希或验证逻辑。
4. 迁移策略：旧系统如果曾经先转小写或采用了其他规范化，切换 profile 可能改变口令语义，应设计一次性迁移或重新认证策略。
5. 秘密最小暴露：不要在错误消息、日志和埋点中打印原始口令或处理后的口令。

常见问题

OpaqueString 会把大写字母变成小写吗？

不会。它没有大小写映射规则，所以大小写仍然是口令语义的一部分；是否允许用户使用大小写，仍由你的密码策略决定。

调用 OpaqueString.String 后是不是就完成密码加密了？

不是。它完成的是 PRECIS profile 相关的字符串处理，不是密码哈希或加密。成功结果仍应交给专门的密码哈希组件，并按该组件的验证接口使用。

为什么不能直接把原始字符串转成 []byte 去哈希？

直接转字节会跳过 profile 的允许字符、空格映射和 NFC 规则，注册与登录可能对看起来相同的输入采用不同字节。先统一准备，再处理字节，边界更清楚。

Unicode 空格会被保留吗？

OpaqueString 的执行规则会把非 ASCII 空格映射为普通 SPACE；这不是大小写折叠。应用仍应对处理后的空结果和业务长度做明确判断。

小结

用 Go 的 precis.OpaqueString 准备区分大小写的国际化口令时，可以记住这条顺序：原始 UTF-8 文本进入 profile，处理成功且非空后，再交给密码哈希或校验组件。OpaqueString 保留大小写、执行规定的规范化，但不负责哈希、不负责存储，也不应被当成大小写不敏感比较器。把这条路径固定在注册、登录和改密流程之间，迁移时再单独评估旧系统的大小写规则。