《游戏服务端编程实践》18.2 封包验证与篡改检测

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

// Package packet 演示带长度、消息类型、序号与校验和的封包编解码，
// 以及单连接速率与解析失败计数。
//
// 解码器对任何非法输入都返回错误，调用方应当直接断开连接，
// 而不是跳过若干字节后继续解析。继续解析会把协议边界交给攻击者。
package packet

import (
	"encoding/binary"
	"errors"
	"hash/crc32"
	"sync"
)

const (
	// Magic 是协议魔数，用于快速丢弃不属于本协议的字节流。
	Magic uint16 = 0x4753 // "GS"
	// HeaderSize 是固定包头长度：magic(2)+type(1)+flags(1)+seq(4)+length(2)+crc32(4)。
	HeaderSize = 14
	// MaxPayload 是单包负载上限，长度字段超过它直接拒绝。
	MaxPayload = 4096
	// maxWindow 是序号窗口上限，内部用 uint64 位图记录重复包。
	maxWindow = 64
)

var (
	// ErrShortFrame 表示字节数不足一个固定包头。
	ErrShortFrame = errors.New("packet: frame shorter than header")
	// ErrBadMagic 表示魔数不匹配。
	ErrBadMagic = errors.New("packet: bad magic")
	// ErrLength 表示长度字段与实际字节数不一致。
	ErrLength = errors.New("packet: length mismatch")
	// ErrTooLarge 表示负载超过 MaxPayload。
	ErrTooLarge = errors.New("packet: payload too large")
	// ErrChecksum 表示 CRC32 校验失败。
	ErrChecksum = errors.New("packet: checksum mismatch")
	// ErrUnknownType 表示消息类型不在白名单内。
	ErrUnknownType = errors.New("packet: unknown message type")
	// ErrDuplicate 表示序号已经在窗口内出现过。
	ErrDuplicate = errors.New("packet: duplicate sequence")
	// ErrTooOld 表示序号落后超过窗口，无法判断是否重复。
	ErrTooOld = errors.New("packet: sequence outside window")
	// ErrSeqJump 表示向前跳跃过大，可能被用于探测或注入。
	ErrSeqJump = errors.New("packet: forward sequence jump too large")
	// ErrRateLimited 表示单连接消息速率超过令牌桶容量。
	ErrRateLimited = errors.New("packet: rate limited")
	// ErrBanned 表示连接已因异常计数被封禁。
	ErrBanned = errors.New("packet: connection banned")
)

// Packet 是解码后的业务包。Payload 引用调用方传入的 frame，
// 调用方在下次读取前必须用完或自行复制，避免缓冲区被覆盖。
type Packet struct {
	Type    uint8
	Flags   uint8
	Seq     uint32
	Payload []byte
}

// Encode 按协议格式序列化一个包。
//
// 编码端不检查消息类型白名单，白名单属于接收端的策略；
// 但长度上限在这里就拒绝，避免生成无法被自己解码的包。
func Encode(msgType, flags uint8, seq uint32, payload []byte) ([]byte, error) {
	if len(payload) > MaxPayload {
		return nil, ErrTooLarge
	}
	frame := make([]byte, HeaderSize+len(payload))
	binary.BigEndian.PutUint16(frame[0:2], Magic)
	frame[2] = msgType
	frame[3] = flags
	binary.BigEndian.PutUint32(frame[4:8], seq)
	binary.BigEndian.PutUint16(frame[8:10], uint16(len(payload)))
	copy(frame[HeaderSize:], payload)
	binary.BigEndian.PutUint32(frame[10:14], checksum(frame[:10], payload))
	return frame, nil
}

func checksum(header, payload []byte) uint32 {
	h := crc32.NewIEEE()
	h.Write(header)
	h.Write(payload)
	return h.Sum32()
}

// Stats 记录单个解码器的累计计数，用于观测异常比例。
type Stats struct {
	Accepted       uint64
	Rejected       uint64
	ShortFrames    uint64
	MagicErrors    uint64
	LengthErrors   uint64
	ChecksumErrors uint64
	TypeErrors     uint64
	SequenceErrors uint64
}

// Decoder 维护一条连接上的收包状态。
//
// Decoder 不是并发安全的“多连接共享对象”：每条连接应各自创建。
// 内部加锁只是为了防止统计读取与解码并发时出现竞态。
type Decoder struct {
	mu            sync.Mutex
	allowed       map[uint8]struct{}
	window        uint32
	maxForwardGap uint32
	started       bool
	highest       uint32
	seen          uint64
	stats         Stats
}

// NewDecoder 创建解码器。
//
// types 是允许的消息类型白名单；window 是重复包检测窗口，
// 会被限制在 1 到 64 之间。向前跳跃上限默认等于窗口，
// 丢包严重的传输层可以调用 SetMaxForwardGap 放宽。
func NewDecoder(types []uint8, window int) *Decoder {
	if window < 1 {
		window = 1
	}
	if window > maxWindow {
		window = maxWindow
	}
	allowed := make(map[uint8]struct{}, len(types))
	for _, t := range types {
		allowed[t] = struct{}{}
	}
	return &Decoder{
		allowed:       allowed,
		window:        uint32(window),
		maxForwardGap: uint32(window),
	}
}

// SetMaxForwardGap 调整允许的向前序号跳跃上限。
//
// 上限越大，越能容忍丢包后的序号跳跃，但也越难区分正常丢包
// 与伪造序号。不要把它设成“无限大”。
func (d *Decoder) SetMaxForwardGap(gap uint32) {
	d.mu.Lock()
	defer d.mu.Unlock()
	if gap == 0 {
		gap = d.window
	}
	d.maxForwardGap = gap
}

// Decode 校验并解析一个完整包。
//
// 检查顺序：固定头长度、魔数、长度字段、CRC32、类型白名单、
// 序号窗口。任何一步失败都返回错误并累加对应计数，调用方应
// 立即断开连接。
func (d *Decoder) Decode(frame []byte) (Packet, error) {
	d.mu.Lock()
	defer d.mu.Unlock()

	if len(frame) < HeaderSize {
		d.reject(&d.stats.ShortFrames)
		return Packet{}, ErrShortFrame
	}
	if binary.BigEndian.Uint16(frame[0:2]) != Magic {
		d.reject(&d.stats.MagicErrors)
		return Packet{}, ErrBadMagic
	}
	size := int(binary.BigEndian.Uint16(frame[8:10]))
	if size > MaxPayload {
		d.reject(&d.stats.LengthErrors)
		return Packet{}, ErrTooLarge
	}
	if len(frame) != HeaderSize+size {
		d.reject(&d.stats.LengthErrors)
		return Packet{}, ErrLength
	}
	payload := frame[HeaderSize:]
	want := binary.BigEndian.Uint32(frame[10:14])
	if checksum(frame[:10], payload) != want {
		d.reject(&d.stats.ChecksumErrors)
		return Packet{}, ErrChecksum
	}
	msgType := frame[2]
	if _, ok := d.allowed[msgType]; !ok {
		d.reject(&d.stats.TypeErrors)
		return Packet{}, ErrUnknownType
	}
	pkt := Packet{
		Type:    msgType,
		Flags:   frame[3],
		Seq:     binary.BigEndian.Uint32(frame[4:8]),
		Payload: payload,
	}
	if err := d.acceptSequence(pkt.Seq); err != nil {
		d.reject(&d.stats.SequenceErrors)
		return Packet{}, err
	}
	d.stats.Accepted++
	return pkt, nil
}

func (d *Decoder) reject(counter *uint64) {
	d.stats.Rejected++
	*counter++
}

// acceptSequence 在持有 d.mu 时调用，维护序号窗口位图。
func (d *Decoder) acceptSequence(seq uint32) error {
	if !d.started {
		d.started = true
		d.highest = seq
		d.seen = 1
		return nil
	}
	if seq > d.highest {
		gap := seq - d.highest
		if gap > d.maxForwardGap {
			return ErrSeqJump
		}
		if gap >= d.window {
			d.seen = 0
		} else {
			d.seen <<= gap
		}
		d.seen |= 1
		d.highest = seq
		return nil
	}
	delta := d.highest - seq
	if delta >= d.window {
		return ErrTooOld
	}
	mask := uint64(1) << delta
	if d.seen&mask != 0 {
		return ErrDuplicate
	}
	d.seen |= mask
	return nil
}

// Snapshot 返回当前统计快照。
func (d *Decoder) Snapshot() Stats {
	d.mu.Lock()
	defer d.mu.Unlock()
	return d.stats
}

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