secure

package
v2.0.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package secure 提供与业务无关的短时凭据原语:一次性票据与解锁令牌。

设计要点:

  • 明文凭据只在签发时返回一次,服务端内存里只保存其 SHA-256 摘要,进程内存被读取也无法还原出可用凭据;
  • 票据单次有效(兑换即销毁)、带用途与绑定对象,防止被挪用到别的端点或别的会话;
  • 容量有上限,过期项在签发 / 兑换时惰性回收,不依赖后台协程,也不会被灌爆内存;
  • 时间源可注入,便于确定性测试。

Index

Constants

View Source
const (
	DefaultUnlockIdle     = 15 * time.Minute
	DefaultUnlockAbsolute = 8 * time.Hour
)

解锁令牌的默认有效期:空闲 15 分钟、绝对 8 小时(每次成功使用顺延空闲期,但不会超过绝对期限)。

Variables

View Source
var ErrSealKey = errors.New("secure: 缺少密封主密钥")

ErrSealKey 表示主密钥不可用(为空)。

View Source
var ErrSealOpen = errors.New("secure: 无法解开密文")

ErrSealOpen 表示密文无法解开:密钥不对、被篡改、上下文不一致或格式不合法。 故意不区分具体原因,避免给攻击者提供区分信息。

View Source
var ErrTooManyTickets = errors.New("too many outstanding tickets")

ErrTooManyTickets 表示未过期的票据数量已达上限,调用方应返回 429 并稍后重试。

View Source
var ErrTooManyUnlocks = errors.New("too many active unlock tokens")

ErrTooManyUnlocks 表示同时存在的解锁令牌数量已达上限。

Functions

func NewCredential

func NewCredential() (string, error)

NewCredential 生成一个 URL 安全的随机凭据明文(base64url,无填充)。

Types

type Sealer

type Sealer struct {
	// contains filtered or unexported fields
}

Sealer 用主密钥派生出的子密钥对敏感值做 AEAD 加解密,可并发使用。

func NewSealer

func NewSealer(masterKey, purpose string) (*Sealer, error)

NewSealer 用主密钥与用途派生子密钥。主密钥强度由调用方在配置层校验。

func (*Sealer) Open

func (s *Sealer) Open(sealed, aad string) ([]byte, error)

Open 解开 Seal 的输出。任何失败都返回 ErrSealOpen。

func (*Sealer) Seal

func (s *Sealer) Seal(plaintext []byte, aad string) (string, error)

Seal 加密 plaintext,aad 为绑定的上下文(解密时必须一致)。返回可直接存入文本列的字符串。

type TicketInfo

type TicketInfo struct {
	Purpose string    // 用途,兑换时必须一致,例如 "sse" / "term"
	Subject string    // 签发时的主体(登录账号)
	Bind    string    // 绑定对象,例如会话 ID;不需要时为空
	Expires time.Time // 过期时间
}

TicketInfo 是兑换成功后返回的票据元数据。

type TicketStore

type TicketStore struct {
	// contains filtered or unexported fields
}

TicketStore 是内存版一次性票据库。零值不可用,请使用 NewTicketStore。

func NewTicketStore

func NewTicketStore(max int) *TicketStore

NewTicketStore 创建票据库;max<=0 时取 1024。

func (*TicketStore) Issue

func (s *TicketStore) Issue(purpose, subject, bind string, ttl time.Duration) (string, error)

Issue 签发一张票据,返回明文(仅此一次可见)。

func (*TicketStore) Len

func (s *TicketStore) Len() int

Len 返回当前票据数(含尚未被回收的过期项),仅供测试与监控。

func (*TicketStore) Redeem

func (s *TicketStore) Redeem(ticket, purpose string) (TicketInfo, bool)

Redeem 兑换票据:存在、未过期且用途一致则销毁并返回元数据。 用途不一致时不销毁(持有者没有过错,且攻击者无法借此消耗他人的票据)。

func (*TicketStore) RevokeAll

func (s *TicketStore) RevokeAll()

RevokeAll 作废全部票据。

func (*TicketStore) RevokeSubject

func (s *TicketStore) RevokeSubject(subject string)

RevokeSubject 作废某个主体的全部票据(改密、登出等场景)。

func (*TicketStore) SetClock

func (s *TicketStore) SetClock(now func() time.Time)

SetClock 仅供测试注入时间源。

type UnlockStore

type UnlockStore struct {
	// contains filtered or unexported fields
}

UnlockStore 保存「二次解锁」令牌:管理员在已登录的基础上再次输入密码后获得, 用于启用 / 停用主机、开会话等高风险操作。只存摘要,空闲与绝对两道期限。

func NewUnlockStore

func NewUnlockStore(idle, absolute time.Duration, max int) *UnlockStore

NewUnlockStore 创建解锁令牌库;参数 <=0 时使用默认值(空闲 15 分钟 / 绝对 8 小时 / 最多 256 个)。

func (*UnlockStore) AbsoluteTTL

func (s *UnlockStore) AbsoluteTTL() time.Duration

AbsoluteTTL 返回绝对有效期。

func (*UnlockStore) IdleTTL

func (s *UnlockStore) IdleTTL() time.Duration

IdleTTL 返回空闲有效期,供接口告知前端。

func (*UnlockStore) Issue

func (s *UnlockStore) Issue(subject string) (string, time.Time, error)

Issue 为主体签发解锁令牌,返回明文与绝对过期时间。

func (*UnlockStore) Len

func (s *UnlockStore) Len() int

Len 返回当前令牌数(含尚未回收的过期项),仅供测试与监控。

func (*UnlockStore) Peek

func (s *UnlockStore) Peek(token, subject string) (remaining time.Duration, ok bool)

Peek 与 Validate 判定规则相同,但不顺延空闲期:用于状态轮询等「只读查看」场景, 避免界面每隔几秒刷新一次状态就让解锁令牌永远不过期。返回距离空闲失效 / 绝对失效中较早者的剩余时间。

func (*UnlockStore) Revoke

func (s *UnlockStore) Revoke(token string)

Revoke 作废单个令牌(主动「上锁」)。

func (*UnlockStore) RevokeAll

func (s *UnlockStore) RevokeAll()

RevokeAll 作废全部令牌:总闸关闭、账号或密码被修改时必须调用。

func (*UnlockStore) SetClock

func (s *UnlockStore) SetClock(now func() time.Time)

SetClock 仅供测试注入时间源。

func (*UnlockStore) Validate

func (s *UnlockStore) Validate(token, subject string) bool

Validate 校验令牌归属于 subject 且未过期;通过则顺延空闲期。

func (*UnlockStore) ValidateFresh

func (s *UnlockStore) ValidateFresh(token, subject string, maxAge time.Duration) bool

ValidateFresh 在 Validate 的基础上要求令牌是「刚刚」换取的(创建于 maxAge 之内),也就是管理员不久之前才输入过密码。 用于授予式的高风险操作(例如开启「允许整个文件系统」):已经解锁了几个小时的令牌不能替这类操作代为确认。 不满足时不顺延空闲期——被拒绝的请求不该让令牌更长寿。maxAge<=0 一律不通过。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL