runtime/secret 与普通 byte 切片如何划分使用边界

runtime/secret 和普通 []byte 不是二选一的容器：[]byte 继续负责承载数据，secret.Do 负责划出一段敏感计算生命周期。公开消息、密文、摘要和需要长期保留的结果仍用普通 byte 切片；密钥、共享秘密、派生中间值和只应短暂存在的缓冲，应尽量在 secret.Do 的调用树内创建、使用并失去引用。

最关键的边界是：把调用方已经持有的敏感 []byte 捕获进闭包，并不会让原来的底层数组自动变成“安全内存”。官方文档保证的是 f 使用的寄存器和栈，以及 f 内创建且最终不可达的堆分配；它没有定义一个新的 secret byte 类型。

官方包文档：https://pkg.go.dev/runtime/secret

Go 1.26 发布说明：https://go.dev/doc/go1.26

runtime/secret 适合缩短密码学临时数据的内存寿命，不是密钥存储、权限控制、磁盘加密或通用内存保险箱。

先明确接口目标：它管生命周期，不管数据类型

runtime/secret 目前只有两个核心函数：Do(func()) 执行一棵调用树，Enabled() 报告当前 goroutine 是否处于秘密模式。包里没有 SecretBytes、Key 或自定义 allocator，这已经提示了它的设计意图：它给计算划作用域，而不是替换 []byte。

Go 官方说明，Do 返回前会擦除该调用树使用的寄存器和栈；在作用域内产生的堆分配，要等程序丢掉所有引用且垃圾回收器发现不可达后才擦除。它也能覆盖 panic 和 runtime.Goexit 场景，但 panic 值如果引用了作用域内对象，会延迟相关分配的擦除。

因此 API 设计不应该暴露“这是 secret byte 还是普通 byte”这样的伪类型选择，而应明确四件事：谁创建敏感输入、谁拥有输出、哪些值允许逃出作用域、平台不支持时怎么处理。

按数据敏感性划分两种使用区域

这个划分有一个实用判断法：如果值在操作完成后仍需要被缓存、写入网络或交给上层，它通常属于调用方普通内存；如果值只为了完成本次密码学操作而存在，它才适合在 Do 内部物化。

参数设计：敏感输入应该在作用域内物化

下面这种接口看似把 key 包进了 Do，其实 key 的底层数组早已由调用方在外部创建。闭包只是引用它，原始分配的所有权和寿命没有改变：

func badSign(key, message []byte) []byte {
    var tag []byte
    secret.Do(func() {
        // key 在进入 Do 前已经存在，原始底层数组不会因此自动受保护
        mac := hmac.New(sha256.New, key)
        _, _ = mac.Write(message)
        tag = mac.Sum(nil)
    })
    return tag
}

更清晰的调用方需求是“在敏感作用域内加载一次密钥”，而不是“传入一个已经长期存在的 key 切片”。可以把参数改成加载函数、硬件句柄或一次性解封装函数，让真实密钥尽可能晚地物化。需要注意的是，加载器自身也不能把秘密长期缓存到全局变量里，否则 runtime/secret 无法覆盖那份缓存。

如果上游只能提供现成 []byte，接口文档应明确：调用方仍负责那份输入的销毁策略。可以在 Do 内复制一份短生命周期工作副本，但这只保护副本，不能抹掉原始数组，也不能消除此前发生的复制。

输出设计：只让非敏感结果跨出边界

官方文档建议，若 Do 内的函数需要产生不应被擦除的结果，应把结果复制到调用方创建的分配中。这个规则很适合 HMAC、签名或公钥导出：密钥与中间状态留在内部，公开结果写入外部预分配缓冲。

package secretops

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

var ErrSecretModeUnavailable = errors.New("secret mode unavailable")

// Sign 在 secret.Do 内加载密钥，只把公开的 HMAC 标签复制到外层。
func Sign(loadKey func() []byte, message []byte) ([]byte, error) {
    // 输出由调用方作用域创建，Do 返回后仍可安全使用。
    tag := make([]byte, sha256.Size)
    unavailable := false

    secret.Do(func() {
        // 对保护有硬要求时，在敏感作用域内检查是否真的启用。
        if !secret.Enabled() {
            unavailable = true
            return
        }

        // 加载器在 Do 内物化密钥，避免让 API 接收长期持有的 key 切片。
        key := loadKey()
        mac := hmac.New(sha256.New, key)
        _, _ = mac.Write(message) // hash.Hash 的 Write 按约定不会返回错误

        // Sum 的临时结果留在 Do 内，只把公开标签复制到外层缓冲。
        copy(tag, mac.Sum(nil))
    })

    if unavailable {
        return nil, ErrSecretModeUnavailable
    }
    return tag, nil
}

这个示例表达的是边界，不是完整密钥管理方案。loadKey 的实现仍要负责安全来源、访问控制和错误处理；若它必须返回错误，可以使用外部定义的非敏感哨兵状态，避免把包含路径、数据片段或内部对象的复杂错误从敏感作用域带出去。

错误模型：区分不支持、业务失败和 panic

secret.Do 本身没有返回值，因此包装 API 要提前决定错误如何跨边界。建议把错误分成三类：

• 能力不可用：使用包外预定义的哨兵错误，例如 ErrSecretModeUnavailable。需要强保护的服务应 fail closed，而不是悄悄继续。
• 普通业务失败：在进入 Do 前完成参数长度、算法选择和公开元数据校验，减少敏感区内的错误分支。
• 敏感计算失败：只向外传播不含秘密的状态码或哨兵，不把密钥、明文、内部缓冲或其格式化内容写进错误。

官方说明 Do 会在 panic 或 runtime.Goexit 时继续履行擦除语义，但 panic 看起来会像从 Do 发出。不要把 panic 当常规错误通道，更不要在 panic 值中携带指向敏感分配的对象。

分配策略：普通 byte 可以增长，秘密缓冲尽量定长

Do 内的堆分配会增加运行时追踪和后续擦除成本。官方特别提醒，append 扩容或向 map 插入导致的新分配会让整块新分配都被擦除，而不只是秘密部分。连续增长会叠加这些成本。

因此秘密区里的 byte 使用策略应更保守：

• 知道长度时用固定数组或一次性 make([]byte, n)，避免反复 append。
• 不要把敏感值塞进会持续扩容的 map、日志缓冲或通用对象池。
• 用完后立即断开所有引用；堆擦除仍要等 GC 发现不可达，不是 Do 返回瞬间必然完成。
• 公开输入可以从外层只读引用，但要确认底层算法不会把秘密结果追加回这块外部缓冲。

Go 1.27 的发布说明补充，秘密模式内创建的 goroutine 会继承该模式。不过并发会让生命周期和引用关系更难推断；除非算法确实需要，敏感计算仍应保持短小、同步和边界清晰。

兼容策略：把实验开关与平台能力放在接口外层

runtime/secret 是实验包，不受 Go 1 兼容承诺约束，并且只有在构建时启用 GOEXPERIMENT=runtimesecret 才存在。Go 1.26 发布说明和当前包文档都把支持范围限定为 Linux 的 amd64 与 arm64；在不支持的平台上，Do 只会直接调用 f。

构建实验版本时可以显式设置环境变量：

# 仅为实验构建启用 runtime/secret；未启用时包本身不可用
GOEXPERIMENT=runtimesecret GOOS=linux GOARCH=amd64 go build ./cmd/secret-demo

# arm64 Linux 使用同一实验开关，并显式选择目标架构
GOEXPERIMENT=runtimesecret GOOS=linux GOARCH=arm64 go build ./cmd/secret-demo

工程上不要把实验包直接散落到业务层。更稳妥的做法是在内部定义一个小接口，例如 RunSensitive(func() error) error，由带实验构建标签的文件接入 runtime/secret，普通构建则明确返回“不支持”。这样未来 API 变化、实验名调整或平台范围扩大时，只改适配层。

最终决策表

几个常见问题

在 Do 里手动把 key 每个字节设为 0，还有必要吗？

手动清零只能作用于你持有的那一块数组，无法覆盖编译器、寄存器、栈或算法内部产生的副本。它可以是调用方管理外部输入的一部分，但不能替代 runtime/secret 的调用树保护，也不能证明所有复制都被清除。

可以把密钥放到全局变量，再在 Do 里读取吗？

不应把全局密钥当作受 runtime/secret 保护。官方明确指出保护不扩展到 f 写入的全局变量；长期全局引用也与缩短秘密寿命的目标相反。

Do 返回后，内部所有堆内存是否立即归零？

不是。程序必须先丢掉全部引用，随后还要等垃圾回收器发现这些对象不可达。Do 提供及时擦除机制，但堆擦除的具体时刻仍受可达性与 GC 调度影响。

最终边界可以浓缩成一句话：普通 byte 决定数据放在哪里，runtime/secret 决定敏感计算的临时存储应活多久。先把输入所有权、输出性质和降级策略设计清楚，再决定哪些 byte 切片进入 Do，会比给每个敏感参数换一个类型名更可靠。