Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

runtime/secret 包详解

概述

runtime/secret 是 Go 1.26 引入的实验性安全特性包，为加密库开发者提供敏感数据保护机制。

核心功能：

  • 在敏感模式下执行函数
  • 自动擦除寄存器中的敏感数据
  • 自动擦除栈空间中的敏感数据
  • 自动擦除堆对象中的敏感数据（GC 触发）

重要说明：

  • ⚠️ 实验性特性：需要设置 GOEXPERIMENT=runtimesecret 启用
  • ⚠️ 平台限制：目前仅支持 linux/amd64 和 linux/arm64
  • ⚠️ 目标用户：主要面向加密库开发者，非通用用途

包导入

import "runtime/secret"

启用实验特性：

# 编译时启用
GOEXPERIMENT=runtimesecret go build

# 运行时启用
GOEXPERIMENT=runtimesecret ./your-program

基本使用

简单示例

package main

import (
    "fmt"
    "runtime/secret"
)

func main() {
    // 检查是否启用敏感模式
    if secret.Enabled() {
        fmt.Println("敏感模式已启用")
    } else {
        fmt.Println("敏感模式未启用")
    }

    // 在敏感模式下执行加密操作
    secret.Do(func() {
        // 敏感操作：密钥生成、加密、解密等
        performEncryption()
    })
}

func performEncryption() {
    // 加密逻辑
    key := generateSecretKey()
    encryptData(key)
    // 函数返回后，key 相关的寄存器和栈空间会被自动清零
}

运行结果：

敏感模式已启用

函数详解

D - Do

func Do(f func())

功能： 在敏感模式下执行函数 f，提供以下安全保证：

安全保证：

  1. 寄存器清零：f 使用过的寄存器会在返回前被清 0
  2. 栈空间清零：f 使用的栈空间会在返回前被清 0
  3. 堆对象擦除：f 产生的堆对象会在 GC 判定不可达时被擦除
  4. 异常安全：即使 f panic 或调用 runtime.Goexit()，擦除仍会进行

限制：

  • ⚠️ 不保护全局变量：全局变量中的敏感数据不会被自动擦除
  • ⚠️ 禁止启动 goroutine：不能在 f 中启动新的 goroutine
  • ⚠️ 堆擦除依赖 GC：堆对象的擦除依赖 GC 触发时机
  • ⚠️ panic 值可能泄露：panic 的值可能泄露内部引用

参数：

  • f func() - 要在敏感模式下执行的函数

返回值：

  • 无

示例 1：基本使用

package main

import (
    "runtime/secret"
)

func main() {
    secret.Do(func() {
        // 敏感操作
        key := []byte("super-secret-key-12345")
        useKey(key)
        // 函数返回后，key 相关的内存会被清零
    })
}

func useKey(key []byte) {
    // 使用密钥进行加密操作
    // ...
}

示例 2：加密操作

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "runtime/secret"
)

func encryptSecretData(plaintext, key []byte) ([]byte, error) {
    var ciphertext []byte
    var err error

    secret.Do(func() {
        // 在敏感模式下执行加密
        block, err := aes.NewCipher(key)
        if err != nil {
            return
        }

        aesgcm, err := cipher.NewGCM(block)
        if err != nil {
            return
        }

        nonce := make([]byte, aesgcm.NonceSize())
        ciphertext = aesgcm.Seal(nonce, nonce, plaintext, nil)
    })

    return ciphertext, err
}

示例 3：密钥生成

package main

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

func generateSecretKey() []byte {
    var key []byte

    secret.Do(func() {
        // 在敏感模式下生成密钥
        key = make([]byte, 32)
        if _, err := rand.Read(key); err != nil {
            panic(err)
        }
        // 使用密钥...
        useGeneratedKey(key)
    })

    return key
}

func useGeneratedKey(key []byte) {
    // 使用生成的密钥
    // ...
}

示例 4：临时数据清理

package main

import (
    "runtime/secret"
)

func processPassword(password []byte) {
    secret.Do(func() {
        // 处理密码
        hash := hashPassword(password)
        verifyHash(hash)
        // 函数返回后，password 和 hash 相关的内存会被清零
    })
}

func hashPassword(password []byte) []byte {
    // 密码哈希逻辑
    // ...
    return nil
}

func verifyHash(hash []byte) {
    // 验证哈希
    // ...
}

示例 5：嵌套调用

package main

import (
    "runtime/secret"
)

func outer() {
    secret.Do(func() {
        // 外层敏感操作
        key := generateKey()
        
        // 内层敏感操作
        secret.Do(func() {
            useKey(key)
        })
    })
}

func generateKey() []byte {
    return []byte("secret-key")
}

func useKey(key []byte) {
    // 使用密钥
    // ...
}

示例 6：错误处理

package main

import (
    "errors"
    "runtime/secret"
)

func safeOperation() (err error) {
    secret.Do(func() {
        // 敏感操作
        if someCondition() {
            err = errors.New("operation failed")
            // 即使返回错误，内存仍会被清零
        }
    })
    return err
}

func someCondition() bool {
    return false
}

示例 7：与 defer 配合

package main

import (
    "runtime/secret"
)

func operationWithCleanup() {
    secret.Do(func() {
        // 设置清理函数
        defer func() {
            // 清理逻辑
            cleanup()
        }()

        // 敏感操作
        performSensitiveOperation()
    })
}

func cleanup() {
    // 清理资源
    // ...
}

func performSensitiveOperation() {
    // 敏感操作逻辑
    // ...
}

示例 8：检查启用状态

package main

import (
    "fmt"
    "runtime/secret"
)

func main() {
    if secret.Enabled() {
        fmt.Println("敏感模式已启用 - 执行安全操作")
        secret.Do(func() {
            secureOperation()
        })
    } else {
        fmt.Println("敏感模式未启用 - 跳过安全操作")
        // 降级处理或返回错误
    }
}

func secureOperation() {
    // 安全敏感的操作
    // ...
}

E - Enabled

func Enabled() bool

功能： 检查敏感模式是否已启用。

返回值：

  • bool - 如果敏感模式已启用返回 true，否则返回 false

使用场景：

  1. 特性检测：在运行时检查是否启用了敏感模式
  2. 降级处理：根据启用状态决定是否执行安全操作
  3. 调试和日志：记录敏感模式的状态

示例 1：基本使用

package main

import (
    "fmt"
    "runtime/secret"
)

func main() {
    if secret.Enabled() {
        fmt.Println("敏感模式已启用")
    } else {
        fmt.Println("敏感模式未启用")
    }
}

运行结果：

敏感模式已启用

示例 2：条件执行

package main

import (
    "runtime/secret"
)

func processSecret(data []byte) {
    if secret.Enabled() {
        // 启用时：使用安全模式
        secret.Do(func() {
            secureProcess(data)
        })
    } else {
        // 未启用时：降级处理
        fallbackProcess(data)
    }
}

func secureProcess(data []byte) {
    // 安全处理逻辑
    // ...
}

func fallbackProcess(data []byte) {
    // 降级处理逻辑
    // ...
}

示例 3：日志记录

package main

import (
    "log"
    "runtime/secret"
)

func init() {
    if secret.Enabled() {
        log.Println("安全模式：敏感数据保护已启用")
    } else {
        log.Println("警告：敏感数据保护未启用")
    }
}

典型示例

示例 1：TLS 密钥处理

package main

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

func loadTLSKey(certFile, keyFile string) (*tls.Certificate, error) {
    var cert *tls.Certificate
    var err error

    secret.Do(func() {
        // 在敏感模式下加载密钥
        c, e := tls.LoadX509KeyPair(certFile, keyFile)
        if e != nil {
            err = e
            return
        }
        cert = &c
    })

    return cert, err
}

示例 2：密码验证

package main

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

func verifyPassword(input, stored []byte) bool {
    var result bool

    secret.Do(func() {
        // 在敏感模式下比较密码
        result = subtle.ConstantTimeCompare(input, stored) == 1
    })

    return result
}

示例 3：密钥派生

package main

import (
    "crypto/sha256"
    "golang.org/x/crypto/pbkdf2"
    "runtime/secret"
)

func deriveKey(password, salt []byte, iterations int) []byte {
    var key []byte

    secret.Do(func() {
        // 在敏感模式下派生密钥
        key = pbkdf2.Key(password, salt, iterations, 32, sha256.New)
    })

    return key
}

示例 4：临时令牌生成

package main

import (
    "crypto/rand"
    "encoding/hex"
    "runtime/secret"
)

func generateToken() string {
    var token string

    secret.Do(func() {
        // 在敏感模式下生成令牌
        bytes := make([]byte, 32)
        if _, err := rand.Read(bytes); err != nil {
            panic(err)
        }
        token = hex.EncodeToString(bytes)
    })

    return token
}

示例 5：加密存储

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "runtime/secret"
)

func encryptAndStore(data, key []byte) ([]byte, error) {
    var encrypted []byte
    var err error

    secret.Do(func() {
        block, err := aes.NewCipher(key)
        if err != nil {
            return
        }

        gcm, err := cipher.NewGCM(block)
        if err != nil {
            return
        }

        nonce := make([]byte, gcm.NonceSize())
        encrypted = gcm.Seal(nonce, nonce, data, nil)
    })

    return encrypted, err
}

示例 6：安全内存操作

package main

import (
    "runtime/secret"
)

func secureMemoryOperation() {
    secret.Do(func() {
        // 分配敏感数据
        sensitiveData := make([]byte, 1024)
        
        // 处理敏感数据
        fillSensitiveData(sensitiveData)
        processSensitiveData(sensitiveData)
        
        // 函数返回后自动清理
    })
}

func fillSensitiveData(data []byte) {
    // 填充敏感数据
    // ...
}

func processSensitiveData(data []byte) {
    // 处理敏感数据
    // ...
}

示例 7：密钥轮换

package main

import (
    "runtime/secret"
)

type KeyManager struct {
    currentKey []byte
}

func (km *KeyManager) RotateKey(newKey []byte) {
    secret.Do(func() {
        // 在敏感模式下执行密钥轮换
        oldKey := km.currentKey
        km.currentKey = make([]byte, len(newKey))
        copy(km.currentKey, newKey)
        
        // 旧密钥会在 GC 时被擦除
        _ = oldKey
    })
}

示例 8：多密钥操作

package main

import (
    "runtime/secret"
)

func multiKeyOperation(keys [][]byte) {
    secret.Do(func() {
        for _, key := range keys {
            // 每个密钥操作都在敏感模式下
            useKey(key)
        }
    })
}

func useKey(key []byte) {
    // 使用密钥
    // ...
}

最佳实践

1. 仅在必要时使用

// ✅ 推荐：仅在真正需要时使用
func encryptData(key, data []byte) {
    secret.Do(func() {
        // 加密逻辑
    })
}

// ❌ 不推荐：过度使用
func normalFunction() {
    secret.Do(func() {
        // 普通逻辑，不需要敏感保护
    })
}

2. 避免全局变量

// ❌ 错误：全局变量不受保护
var globalKey []byte

func init() {
    secret.Do(func() {
        globalKey = generateKey() // 全局变量不会被自动清理
    })
}

// ✅ 正确：使用局部变量
func process() {
    secret.Do(func() {
        key := generateKey() // 局部变量会被清理
        useKey(key)
    })
}

3. 避免在敏感函数中启动 goroutine

// ❌ 错误：禁止在敏感函数中启动 goroutine
secret.Do(func() {
    go func() {
        // 这会导致未定义行为
    }()
})

// ✅ 正确：在外部启动 goroutine
go func() {
    secret.Do(func() {
        // 敏感操作
    })
}()

4. 检查启用状态

// ✅ 推荐：检查启用状态
func secureOperation() {
    if !secret.Enabled() {
        log.Warn("敏感模式未启用")
        return
    }
    
    secret.Do(func() {
        // 敏感操作
    })
}

5. 处理 panic

// ✅ 推荐：妥善处理 panic
secret.Do(func() {
    defer func() {
        if r := recover(); r != nil {
            // 即使 panic，内存仍会被清理
            log.Printf("Recovered from panic: %v", r)
        }
    }()
    
    // 敏感操作
})

与其他包配合

与 crypto 包配合

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "runtime/secret"
)

func encryptWithAES(key, plaintext []byte) ([]byte, error) {
    var ciphertext []byte
    var err error

    secret.Do(func() {
        block, err := aes.NewCipher(key)
        if err != nil {
            return
        }

        gcm, err := cipher.NewGCM(block)
        if err != nil {
            return
        }

        nonce := make([]byte, gcm.NonceSize())
        ciphertext = gcm.Seal(nonce, nonce, plaintext, nil)
    })

    return ciphertext, err
}

与 crypto/subtle 包配合

package main

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

func constantTimeCompare(a, b []byte) bool {
    var result bool

    secret.Do(func() {
        result = subtle.ConstantTimeCompare(a, b) == 1
    })

    return result
}

与 encoding/hex 包配合

package main

import (
    "crypto/rand"
    "encoding/hex"
    "runtime/secret"
)

func generateHexToken() string {
    var token string

    secret.Do(func() {
        bytes := make([]byte, 32)
        if _, err := rand.Read(bytes); err != nil {
            panic(err)
        }
        token = hex.EncodeToString(bytes)
    })

    return token
}

注意事项

限制

  1. 平台限制：

    • 仅支持 linux/amd64 和 linux/arm64
    • 其他平台无法使用此特性

  2. 实验性质：

    • 需要设置 GOEXPERIMENT=runtimesecret
    • API 可能在未来版本中变化

  3. 不保护全局变量：

    • 全局变量中的敏感数据不会被自动擦除
    • 需要手动清理全局变量

  4. 堆擦除依赖 GC：

    • 堆对象的擦除依赖 GC 触发
    • 可能需要手动调用 runtime.GC() 加速擦除

  5. 禁止启动 goroutine：

    • 在 secret.Do() 中启动 goroutine 会导致未定义行为

  6. panic 值可能泄露：

    • panic 的值可能包含敏感数据的引用
    • 需要妥善处理 panic

安全建议

  1. 最小化敏感数据范围：

    • 尽量缩小 secret.Do() 的范围
    • 避免在敏感函数中执行不必要的操作

  2. 避免日志泄露：

    • 不要在敏感函数中打印敏感数据
    • 避免将敏感数据传递给日志系统

  3. 测试启用状态：

    • 在生产环境中确保启用了敏感模式
    • 提供降级处理机制

  4. 文档说明：

    • 在代码中注明使用了敏感模式
    • 说明启用要求和平台限制

快速参考

函数速查

函数功能参数返回值
Do(f func())在敏感模式下执行函数f func() - 要执行的函数无
Enabled() bool检查敏感模式是否启用无bool - 启用状态

使用流程

1. 设置 GOEXPERIMENT=runtimesecret
   ↓
2. 确认平台支持 (linux/amd64, linux/arm64)
   ↓
3. 使用 secret.Enabled() 检查状态
   ↓
4. 使用 secret.Do() 执行敏感操作
   ↓
5. 函数返回后自动清理内存

常见场景

场景推荐做法
密钥生成使用 secret.Do() 包裹生成逻辑
加密/解密使用 secret.Do() 包裹加密操作
密码处理使用 secret.Do() 包裹密码验证
令牌生成使用 secret.Do() 包裹令牌生成
密钥轮换使用 secret.Do() 包裹轮换逻辑

启用命令

# 编译时启用
GOEXPERIMENT=runtimesecret go build

# 运行时启用
GOEXPERIMENT=runtimesecret ./program

# 测试时启用
GOEXPERIMENT=runtimesecret go test

总结

runtime/secret 是 Go 1.26 引入的实验性安全特性，为加密库开发者提供敏感数据保护机制。

核心优势：

  • ✅ 自动擦除寄存器中的敏感数据
  • ✅ 自动擦除栈空间中的敏感数据
  • ✅ 自动擦除堆对象中的敏感数据
  • ✅ 即使 panic 也会执行擦除

重要限制：

  • ⚠️ 仅支持 linux/amd64 和 linux/arm64
  • ⚠️ 需要 GOEXPERIMENT=runtimesecret
  • ⚠️ 不保护全局变量
  • ⚠️ 禁止在敏感函数中启动 goroutine

主要用途：

  • 加密库开发
  • 密钥管理
  • 密码处理
  • 临时敏感数据清理

使用建议：

  1. 仅在真正需要时使用
  2. 避免全局变量存储敏感数据
  3. 检查启用状态并提供降级处理
  4. 遵循最小化敏感数据范围原则