runtime/secret 清除临时机密数据的使用边界

处理临时密钥、nonce 或解密后的短生命周期数据时，单纯把切片填零并不能说明所有副本都已经从运行时痕迹中消失。runtime/secret 提供的 Do 更适合包住一段尽量小的机密计算：在支持的平台上，函数返回前清除这段调用使用过的寄存器和栈；堆上的临时分配则要等对象不再可达，并由垃圾回收器发现后再清除。

官方地址：https://go.dev/src/runtime/secret/

这意味着它不是“调用一次就立即擦除所有机密字节”的万能函数。它是实验性能力，保护范围、平台行为和异常路径都需要一起读懂，才能决定是否把它放进生产代码。

先确认实验开关和使用场景

官方包文档把 runtime/secret 标记为实验性包，并要求构建时设置 GOEXPERIMENT=runtimesecret。它不受 Go 1 兼容性承诺约束，因此适合密码学实验、明确控制工具链的安全组件或需要评估运行时清除语义的项目，不适合把它当作稳定公共 API 随意嵌入所有服务。

# 只为当前命令打开运行时实验，不把设置永久写入开发环境
GOEXPERIMENT=runtimesecret go run .

先把边界缩小到一个问题：某段计算结束后，函数自己的寄存器和栈内容是否应该尽快不再保留。如果真正需求是“密钥永不进入普通进程内存”，那就已经超出这个包的职责，还需要硬件、密钥服务或进程隔离方案。

先用最小闭包包住机密计算

最小配方是让 secret.Do 接收一个闭包，把临时数据的创建、使用和不再需要的结果复制限制在这个边界里。闭包外只保留业务真正需要的非机密结果，不要把原始密钥、明文或包含它们的对象塞进返回值。

package main

import (
	"crypto/sha256"
	"fmt"

	"runtime/secret"
)

func main() {
	var shortDigest [8]byte

	secret.Do(func() {
		// 机密输入只在 Do 的调用边界内参与计算，示例不把原始值带出闭包。
		key := []byte("temporary-key-material")
		digest := sha256.Sum256(key)
		// 只复制业务需要的短摘要，避免返回仍含机密数据的切片。
		copy(shortDigest[:], digest[:])
	})

	// 输出的是非机密摘要片段，不代表可以读取或验证运行时内存清除结果。
	fmt.Printf("digest-prefix=%x\n", shortDigest)
}

这个例子有两个刻意的取舍：第一，Do 的范围尽可能小；第二，闭包外只接收已经定义为非机密的结果。图中的寄存器与栈属于返回前清除的边界，堆分配则仍受“引用是否全部消失”和 GC 何时观察到不可达的条件影响。

寄存器、栈和堆对象不是同一种清除时机

不要把“返回前清除”和“马上把所有内存填零”混为一谈。官方实现说明，Do 会在返回前处理函数使用的寄存器和栈；函数期间产生的堆分配，只有在程序放弃全部引用并且垃圾回收器注意到这些引用已经消失后才会被擦除。

因此，堆分配越多，跟踪和清理成本越可能增加。尤其是扩容切片或增长 map 时，新的整块分配可能被视为需要清除的对象，而不是只清理其中几个字段。把机密计算写成短小、少分配的函数，通常比在一个巨大的业务闭包里包住几十个步骤更容易控制代价。

还要注意引用关系：闭包把一个包含机密内容的切片存入全局缓存、长生命周期对象或另一个仍被使用的结构体时，堆对象并没有变成不可达，清除自然不会按“函数返回即完成”来理解。

全局变量、返回值和 panic 是最容易越界的地方

Do 的保护不延伸到函数写入的全局变量。下面这种写法虽然调用了 Do，但全局变量仍然是闭包外的长期引用，不能把它当作临时机密清除方案：

var leakedSecret []byte

func badPattern() {
	secret.Do(func() {
		// 全局引用会把数据带出 Do，不能依赖 Do 自动清理它。
		leakedSecret = []byte("secret-that-escapes")
	})
}

返回值也一样：如果返回的是指向机密堆分配的切片或结构体，调用方仍然持有引用，垃圾回收器就没有理由立即回收它。可以返回脱敏后的摘要、状态码或业务结果；如果确实要返回敏感对象，就必须把它的生命周期和清除策略交给调用方，而不是把责任推给 Do。

异常路径要单独设计。官方实现会让 f 引发的 panic 看起来像从 Do 本身产生；被 panic 值携带的堆对象，在 panic 值不再存活之前也不会被清除。runtime.Goexit 是不可恢复的退出路径，清除可能被调用栈更高处的 defer 推迟。

平台和异常边界要单独判断

当前官方源代码对 linux/amd64 和 linux/arm64 提供专门支持。其他平台上，Do 会直接调用传入的函数，这意味着代码仍能保持同一调用形式，但不能据此宣称获得相同的寄存器、栈和堆清除语义。

跨平台库可以把 Do 当作能力边界，而不能把它写成安全保证。发布前至少明确三件事：部署目标是否属于专门支持的平台；构建链是否稳定开启实验开关；不支持平台是否有进程隔离、外部密钥服务或其他降级方案。

把完整配方收敛到一个安全边界

下面的写法把“输入机密”“机密计算”“非机密结果”分开，便于后续替换实现。注释中的“清除”只描述官方运行时契约的范围，不代表可以观察到每一份机器内存副本：

package securecalc

import (
	"crypto/sha256"

	"runtime/secret"
)

// DigestPrefix 只返回已经约定为非机密的摘要前缀。
func DigestPrefix(input []byte) [8]byte {
	var result [8]byte
	secret.Do(func() {
		// 闭包内只做短计算，减少临时堆对象和引用逃逸的机会。
		digest := sha256.Sum256(input)
		// 只复制输出协议允许暴露的部分，原始输入不作为返回值带出。
		copy(result[:], digest[:])
	})
	return result
}

如果 input 本身由调用方长期持有，Do 不会替调用方把这份外部引用变成不可达；如果输入来自全局变量、缓存或日志，也要在它们各自的生命周期里处理。对于稳定性要求高的通用业务，优先使用成熟的密钥管理、短生命周期进程或专门密码学库，并把 runtime/secret 作为经过工具链和平台评估后的实验能力。

常见问题

调用 secret.Do 后，堆上的密钥会立即被填零吗？

不会。堆对象需要先没有任何引用，随后还要等垃圾回收器发现它不可达；寄存器和栈才是官方说明中在返回前处理的部分。

其他操作系统上还能调用 runtime/secret.Do 吗？

可以保持相同调用形式，但官方实现会在不支持的平台直接调用闭包，不能把这种行为当作同等的清除保证。

能不能把密钥写入全局变量，最后再调用 Do？

不建议。全局变量不在 Do 的保护范围内，应该把机密数据限制在短生命周期对象中，并避免把引用保存到全局状态、缓存或日志。