《游戏服务端编程实践》18.1 网络加密与签名

// file: ch18/sign/sign.go
// tier: L1
// verify: go test ./ch18/sign/

// Package sign 演示游戏消息的 HMAC 签名、时间窗与 nonce 防重放。
//
// 这里的签名用于“消息完整性 + 新鲜性”，不替代 TLS。密钥只保存在
// 服务端；客户端持有的任何密钥都只能视为公开信息。
package sign

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/binary"
	"errors"
	"hash"
	"sync"
	"time"
)

var (
	// ErrMalformed 表示消息缺少必要字段，无法进入验签。
	ErrMalformed = errors.New("sign: malformed message")
	// ErrUnknownKey 表示 KeyID 不在服务端密钥表中，通常意味着轮换未同步。
	ErrUnknownKey = errors.New("sign: unknown key id")
	// ErrExpired 表示时间戳落在允许窗口之外，可能过期或来自未来。
	ErrExpired = errors.New("sign: timestamp outside window")
	// ErrReplay 表示同一个 nonce 在有效期内被重复使用。
	ErrReplay = errors.New("sign: nonce already used")
	// ErrBadMAC 表示签名不匹配，消息内容或密钥不一致。
	ErrBadMAC = errors.New("sign: mac mismatch")
	// ErrNonceFull 表示 nonce 缓存已达上限且没有可回收的过期项。
	ErrNonceFull = errors.New("sign: nonce cache full")
)

const (
	// macDomain 做域分离，避免同一密钥在别的协议里被复用。
	macDomain = "gsp-sign-v1"
	// defaultMaxNonces 是单个 Verifier 允许缓存的 nonce 上限。
	defaultMaxNonces = 1 << 16
)

// Message 是一条待签名或待验证的业务消息。
//
// Timestamp 使用 Unix 秒。Nonce 由发送方生成，必须在时间窗内唯一；
// 服务端只要求唯一性，不解释它的具体格式。
type Message struct {
	KeyID     string
	Nonce     string
	Timestamp int64
	Payload   []byte
}

// Mac 计算消息的 HMAC-SHA256。
//
// 编码是确定性的：域分隔串、带长度前缀的 KeyID 与 Nonce、
// 大端序时间戳、带长度前缀的负载。长度前缀保证字段边界清晰，
// 不会出现“把两个字段拼接后恰好相同”的歧义。
func Mac(secret []byte, m Message) []byte {
	h := hmac.New(sha256.New, secret)
	h.Write([]byte(macDomain))
	writeField(h, []byte(m.KeyID))
	writeField(h, []byte(m.Nonce))
	var ts [8]byte
	binary.BigEndian.PutUint64(ts[:], uint64(m.Timestamp))
	h.Write(ts[:])
	writeField(h, m.Payload)
	return h.Sum(nil)
}

func writeField(h hash.Hash, b []byte) {
	var size [4]byte
	binary.BigEndian.PutUint32(size[:], uint32(len(b)))
	h.Write(size[:])
	h.Write(b)
}

// Verifier 持有一组可轮换的密钥和时间窗配置。
//
// keys 的键是 KeyID，值是对应密钥。Verify 只读取密钥表，
// 不会修改调用方传入的 map。
type Verifier struct {
	mu         sync.Mutex
	keys       map[string][]byte
	window     time.Duration
	maxNonces  int
	seen       map[string]time.Time // nonce key -> 可回收时间
	now        func() time.Time
	lastPurge  time.Time
	purgeEvery time.Duration
}

// NewVerifier 创建验签器并复制密钥表。
//
// window 是时间戳允许偏离服务端时钟的最大绝对值，小于等于 0 时
// 使用 30 秒。生产环境应根据时钟同步精度和消息生命周期取值，
// 不要为了“减少误杀”把窗口设成几分钟。
func NewVerifier(keys map[string][]byte, window time.Duration) *Verifier {
	if window <= 0 {
		window = 30 * time.Second
	}
	copied := make(map[string][]byte, len(keys))
	for id, secret := range keys {
		copied[id] = append([]byte(nil), secret...)
	}
	return &Verifier{
		keys:       copied,
		window:     window,
		maxNonces:  defaultMaxNonces,
		seen:       make(map[string]time.Time),
		now:        time.Now,
		purgeEvery: time.Second,
	}
}

// Verify 校验消息的时间窗、MAC 与 nonce 唯一性。
//
// 检查顺序是刻意的：先做廉价的结构与时间检查，再验 MAC，
// 最后才写入 nonce 缓存。这样伪造消息无法耗尽 nonce 缓存，
// 因为 MAC 不通过的消息不会占用缓存条目。
func (v *Verifier) Verify(m Message, mac []byte) error {
	if m.KeyID == "" || m.Nonce == "" || m.Timestamp <= 0 || len(mac) == 0 {
		return ErrMalformed
	}
	secret, ok := v.keys[m.KeyID]
	if !ok {
		return ErrUnknownKey
	}
	now := v.clock()
	ts := time.Unix(m.Timestamp, 0)
	if now.Sub(ts) > v.window || ts.Sub(now) > v.window {
		return ErrExpired
	}
	want := Mac(secret, m)
	if !hmac.Equal(want, mac) {
		return ErrBadMAC
	}

	nonceKey := m.KeyID + "\x00" + m.Nonce
	v.mu.Lock()
	defer v.mu.Unlock()
	v.purgeLocked(now)
	if _, ok := v.seen[nonceKey]; ok {
		return ErrReplay
	}
	if len(v.seen) >= v.maxNonces {
		return ErrNonceFull
	}
	expires := ts.Add(v.window)
	if expires.Before(now) {
		expires = now.Add(v.window)
	}
	v.seen[nonceKey] = expires
	return nil
}

// purgeLocked 回收已经过期的 nonce，避免缓存无限增长。
//
// 每个窗口最多全量扫描一次；两次清理之间只做 O(1) 判断。
func (v *Verifier) purgeLocked(now time.Time) {
	if now.Sub(v.lastPurge) < v.purgeEvery && len(v.seen) < v.maxNonces {
		return
	}
	for key, expires := range v.seen {
		if now.After(expires) {
			delete(v.seen, key)
		}
	}
	v.lastPurge = now
}

// SetClock 替换时钟，仅用于测试或需要统一注入时钟的服务。
func (v *Verifier) SetClock(now func() time.Time) {
	v.mu.Lock()
	defer v.mu.Unlock()
	if now != nil {
		v.now = now
	}
}

func (v *Verifier) clock() time.Time {
	v.mu.Lock()
	defer v.mu.Unlock()
	return v.now()
}

// Window 返回当前允许的时间偏差。
func (v *Verifier) Window() time.Duration {
	return v.window
}

cd .local/checks/gs-practice-lab
gofmt -l ch18/sign
go vet ./ch18/sign/
go test ./ch18/sign/ -count=1