runtime/secret 接入密码处理函数的封装方式

我第一次把 runtime/secret 放进密码处理代码时，最容易犯的错是把它当成“自动清空所有密码”的开关。它真正解决的是更窄、也更有价值的一段问题：把处理机密信息的临时计算包进一个边界，让运行时尽快擦除函数调用期间产生的部分寄存器、栈和临时堆数据。

官方资料：https://pkg.go.dev/runtime/secret

比较稳妥的接入方式，是让封装接收一个“取得密码”的函数和一个“处理密码”的函数，把两者放进同一个 secret.Do 回调；需要留在外部的结果则提前由调用方分配，再在回调里复制出去。这样做不会替你选择 Argon2、bcrypt 等密码算法，也不会替你解决日志、配置文件和密钥托管问题，但能把机密计算的生命周期说清楚。

把密码处理函数接入 runtime/secret 的重点，不是给敏感数据套一层函数名，而是明确 secret.Do 的边界、输入所有权和输出复制点。

先确认 runtime/secret 的工作边界

runtime/secret 是实验性包，只有在构建时启用 GOEXPERIMENT=runtimesecret 才存在。官方资料还说明，当前它主要支持 Linux 的 amd64 和 arm64；不支持的平台会直接执行回调，因此不能把它当成所有部署环境都具备的擦除保证。

secret.Do 接受一个无返回值的函数。函数执行期间，运行时会处理与这段调用树相关的临时存储；但全局变量、仍被外部引用的堆对象、指针地址携带的信息，以及调用方已经长期持有的原始输入，都不在“自动替你管理”的范围内。

还有一个容易被忽略的事实：如果闭包里创建了一个本来不应该被擦除、却需要返回给调用方的结果，应该把结果复制到由调用方创建的存储中。这个复制点就是封装 API 最值得写进注释的地方。

把输入和处理函数放进同一个封装

下面这个封装故意把“读取密码”和“执行密码处理”都抽成回调。调用方把输入所有权交给 load 返回的字节切片，封装在处理结束后负责清理它；真实项目中，process 应该调用经过评估的密码哈希或密钥派生实现，而不是把示例里的占位处理当成安全算法。

package secretwrap

import "runtime/secret"

// WithPasswordSecret 在一个 secret.Do 边界内处理密码字节。
// load 返回的切片所有权转交给本函数，process 不应把 raw 保存到边界外。
func WithPasswordSecret(load func() []byte, process func([]byte) error) error {
	var processErr error

	secret.Do(func() {
		raw := load()
		// 输入由本函数接管，处理结束后清零，减少明文继续留存的时间。
		defer clear(raw)
		if raw == nil {
			processErr = ErrNilPassword
			return
		}
		// 真正的项目在这里调用 Argon2id、bcrypt 等专用密码处理函数。
		processErr = process(raw)
	})

	return processErr
}

这里的关键不是 clear(raw) 这行本身，而是所有权约定：load 返回的字节不能再被其他 goroutine、缓存或全局变量继续引用，否则清零会同时改变那些引用看到的内容。若输入来自不可变字符串，字符串本身也不会因为这个封装就被擦除，所以更适合在更靠近机密来源的位置完成字节化和生命周期管理。

示例里的 ErrNilPassword 需要在包内定义，或者改成项目已有的错误。为了让错误判断保持稳定，不建议把密码内容拼进错误字符串。

输出结果要在边界外提前准备

密码验证往往只需要返回一个布尔值，派生密钥则需要返回一段结果。对于第二种情况，可以先在调用方创建结果缓冲区，再在 secret.Do 内写入它。这样结果的生命周期由调用方掌握，不会因为“返回值是在闭包里产生的”而把边界写得含糊。

package secretwrap

import (
	"crypto/sha256"
	"runtime/secret"
)

// DeriveDemo 展示结果复制位置；它不是可直接用于生产的密码哈希算法。
func DeriveDemo(load func() []byte) ([]byte, error) {
	// 结果由调用方在 Do 之前分配，后续生命周期不由 secret.Do 接管。
	result := make([]byte, sha256.Size)
	var processErr error

	secret.Do(func() {
		raw := load()
		// 只有在本函数拥有 raw 时才能这样清理，借用的切片不要擅自改写。
		defer clear(raw)
		if len(raw) == 0 {
			processErr = ErrEmptyPassword
			return
		}
		sum := sha256.Sum256(raw)
		// 复制到外部缓冲区，明确告诉读者结果需要跨过 Do 边界。
		copy(result, sum[:])
	})

	if processErr != nil {
		return nil, processErr
	}
	return result, nil
}

这个例子只用 SHA-256 展示数据流，不能把它当成密码存储方案。生产系统要根据威胁模型选择密码哈希或密钥派生算法，并设置合适的参数；runtime/secret 只负责减少一部分临时机密数据的存留，不改变算法的抗暴力破解能力。

把异常和并发情况写进封装约定

secret.Do 返回后，调用方还需要知道几种特殊情况。官方文档说明，回调中的 panic 会像从 Do 发起一样传播；调用 runtime.Goexit 时，栈上更高层的 defer 可能让擦除延迟。因此不要在回调里把清理逻辑建立在“所有路径一定正常 return”的假设上。

在回调中创建 goroutine 也要谨慎。运行时会让回调期间创建的 goroutine 处于相同的 secret 模式，但这并不等于可以无限延长机密的生命周期。密码处理通常应该在一个短小、可等待的调用树中完成，避免把 raw 交给异步队列、后台缓存或长生命周期 worker。

另外，process 内如果把 raw 写入日志、错误包装、指标标签、全局变量或可序列化对象，后续再怎么调用 clear 都不能撤回已经泄露的副本。封装层能约束 API，却不能替业务代码决定所有副本的去向。

用实验构建开关接入项目

正式使用时，先把实验开关放到构建流程，而不是只在某台开发机的临时环境里设置。下面的命令只演示构建条件；它不会替你选择目标平台，也不会证明部署环境已经具备相同的 runtime 行为。

# 仅为启用 runtime/secret 实验包设置构建开关。
# Linux 目标还需要结合项目实际架构和 Go 工具链进行发布验证。
GOEXPERIMENT=runtimesecret go build ./...

建议把封装放在一个职责单一的包里，并在包注释中写清楚三件事：输入切片是否转移所有权、处理函数能否保存参数、结果哪些部分允许离开 Do。如果项目需要同时支持未启用实验的构建目标，可以通过构建标签提供替代实现，但替代实现必须明确它只提供功能兼容，不应暗示具备同等的擦除保证。

官方资料：https://go.dev/doc/go1.26；实现说明：https://go.dev/src/runtime/secret/doc.go。

常见误区与一张速查表

我更推荐先用这个封装把“谁拥有输入、谁保存输出、谁负责清理”写成接口约定，再决定是否需要 runtime/secret。如果连副本路径都没有梳理清楚，直接包一层 secret.Do 很容易形成安全感错觉；如果边界已经明确，它才会成为密码处理流程里一个可复用的生命周期工具。

相关问题

• runtime/secret.Enabled() 有什么用？它可以告诉当前 goroutine 是否处在 secret 模式，适合做运行条件判断，但不能代替输入所有权和副本审计。
• 不支持的平台会怎样？官方文档说明，Do 会直接调用回调，因此代码仍可能运行，但不能据此宣称获得同样的内存擦除行为。
• 能不能在 Do 里启动异步密码任务？可以启动并继承 secret 模式，但应尽量避免把机密参数交给长生命周期任务，优先同步完成并等待处理结束。
• runtime/secret 能替代密钥管理系统吗？不能。它不负责生成、轮换、授权、存储或撤销密钥，只覆盖运行中一段临时数据的处理边界。