Documentation
¶
Overview ¶
Package secure 提供与业务无关的短时凭据原语:一次性票据与解锁令牌。
设计要点:
- 明文凭据只在签发时返回一次,服务端内存里只保存其 SHA-256 摘要,进程内存被读取也无法还原出可用凭据;
- 票据单次有效(兑换即销毁)、带用途与绑定对象,防止被挪用到别的端点或别的会话;
- 容量有上限,过期项在签发 / 兑换时惰性回收,不依赖后台协程,也不会被灌爆内存;
- 时间源可注入,便于确定性测试。
Index ¶
- Constants
- Variables
- func NewCredential() (string, error)
- type Sealer
- type TicketInfo
- type TicketStore
- func (s *TicketStore) Issue(purpose, subject, bind string, ttl time.Duration) (string, error)
- func (s *TicketStore) Len() int
- func (s *TicketStore) Redeem(ticket, purpose string) (TicketInfo, bool)
- func (s *TicketStore) RevokeAll()
- func (s *TicketStore) RevokeSubject(subject string)
- func (s *TicketStore) SetClock(now func() time.Time)
- type UnlockStore
- func (s *UnlockStore) AbsoluteTTL() time.Duration
- func (s *UnlockStore) IdleTTL() time.Duration
- func (s *UnlockStore) Issue(subject string) (string, time.Time, error)
- func (s *UnlockStore) Len() int
- func (s *UnlockStore) Peek(token, subject string) (remaining time.Duration, ok bool)
- func (s *UnlockStore) Revoke(token string)
- func (s *UnlockStore) RevokeAll()
- func (s *UnlockStore) SetClock(now func() time.Time)
- func (s *UnlockStore) Validate(token, subject string) bool
- func (s *UnlockStore) ValidateFresh(token, subject string, maxAge time.Duration) bool
Constants ¶
const ( DefaultUnlockIdle = 15 * time.Minute DefaultUnlockAbsolute = 8 * time.Hour )
解锁令牌的默认有效期:空闲 15 分钟、绝对 8 小时(每次成功使用顺延空闲期,但不会超过绝对期限)。
Variables ¶
var ErrSealKey = errors.New("secure: 缺少密封主密钥")
ErrSealKey 表示主密钥不可用(为空)。
var ErrSealOpen = errors.New("secure: 无法解开密文")
ErrSealOpen 表示密文无法解开:密钥不对、被篡改、上下文不一致或格式不合法。 故意不区分具体原因,避免给攻击者提供区分信息。
var ErrTooManyTickets = errors.New("too many outstanding tickets")
ErrTooManyTickets 表示未过期的票据数量已达上限,调用方应返回 429 并稍后重试。
var ErrTooManyUnlocks = errors.New("too many active unlock tokens")
ErrTooManyUnlocks 表示同时存在的解锁令牌数量已达上限。
Functions ¶
func NewCredential ¶
NewCredential 生成一个 URL 安全的随机凭据明文(base64url,无填充)。
Types ¶
type Sealer ¶
type Sealer struct {
// contains filtered or unexported fields
}
Sealer 用主密钥派生出的子密钥对敏感值做 AEAD 加解密,可并发使用。
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) Redeem ¶
func (s *TicketStore) Redeem(ticket, purpose string) (TicketInfo, bool)
Redeem 兑换票据:存在、未过期且用途一致则销毁并返回元数据。 用途不一致时不销毁(持有者没有过错,且攻击者无法借此消耗他人的票据)。
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) Peek ¶
func (s *UnlockStore) Peek(token, subject string) (remaining time.Duration, ok bool)
Peek 与 Validate 判定规则相同,但不顺延空闲期:用于状态轮询等「只读查看」场景, 避免界面每隔几秒刷新一次状态就让解锁令牌永远不过期。返回距离空闲失效 / 绝对失效中较早者的剩余时间。
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 一律不通过。