TLS 1.2 协议核心原理与 Go 标准库实现分析

// 文件：$GOROOT/src/crypto/tls/common.go L67, L70 (go1.27.1)
maxPlaintext               = 16384        // maximum plaintext payload length
// 单条记录的明文上限 2^14 = 16384 字节，超过就必须分片
recordHeaderLen            = 5            // record header length
// 记录头固定 5 字节：type(1) + version(2) + length(2)

// 文件：$GOROOT/src/crypto/tls/conn.go L167-184 (go1.27.1)
// A halfConn represents one direction of the record layer
// connection, either sending or receiving.
type halfConn struct {
	sync.Mutex
	// 每个方向一把锁，读写可以并发

	err     error  // first permanent error
	// 一旦出现不可恢复错误 (如 MAC 校验失败), 记录在此，之后的读写直接返回它
	version uint16 // protocol version
	// 协商出来的协议版本，决定是否使用显式 IV 等行为
	cipher  any    // cipher algorithm
	// current 状态的加密器：cipher.Stream(RC4) / cbcMode(AES-CBC) / aead(AES-GCM), nil 表示明文
	mac     hash.Hash
	// current 状态的 MAC(HMAC-SHA1 等), AEAD 套件下为 nil
	seq     [8]byte // 64-bit sequence number
	// 64 位隐式序列号，大端序，不出现在线路上，参与 MAC/AEAD 的附加数据计算

	scratchBuf [13]byte // to avoid allocs; interface method args escape
	// 13 字节 = seq(8) + type(1) + version(2) + length(2), 用于拼 MAC 输入或 AEAD 的 AAD

	nextCipher any       // next encryption state
	// pending 状态的加密器，由 prepareCipherSpec 写入
	nextMac    hash.Hash // next MAC algorithm
	// pending 状态的 MAC

	level         QUICEncryptionLevel // current QUIC encryption level
	trafficSecret []byte              // current TLS 1.3 traffic secret
	// 以上两个字段只用于 QUIC 与 TLS 1.3, TLS 1.2 不涉及
}

// 文件：$GOROOT/src/crypto/tls/conn.go L205-225 (go1.27.1)
// prepareCipherSpec sets the encryption and MAC states
// that a subsequent changeCipherSpec will use.
func (hc *halfConn) prepareCipherSpec(version uint16, cipher any, mac hash.Hash) {
	hc.version = version
	hc.nextCipher = cipher
	// 握手算出密钥后先放进 pending 槽位，此时还不生效
	hc.nextMac = mac
}

// changeCipherSpec changes the encryption and MAC states
// to the ones previously passed to prepareCipherSpec.
func (hc *halfConn) changeCipherSpec() error {
	if hc.nextCipher == nil || hc.version == VersionTLS13 {
		// 没有准备好的 pending 状态就收到/发送 CCS, 属于协议错误
		return alertInternalError
	}
	hc.cipher = hc.nextCipher
	// pending 提升为 current
	hc.mac = hc.nextMac
	hc.nextCipher = nil
	hc.nextMac = nil
	// 清空 pending 槽位
	clear(hc.seq[:])
	// 关键：序列号从 0 重新开始，Finished 消息是新状态下的第 0 条记录
	return nil
}

// 文件：$GOROOT/src/crypto/tls/conn.go L979-1048 节选 (go1.27.1)
func (c *Conn) writeRecordLocked(typ recordType, data []byte) (int, error) {
	// ... 省略 QUIC 分支与缓冲区池 ...
	var n int
	for len(data) > 0 {
		// 分片循环：每次最多取 maxPayload 字节
		m := len(data)
		if maxPayload := c.maxPayloadSizeForWrite(typ); m > maxPayload {
			m = maxPayload
			// maxPayloadSizeForWrite 不超过 maxPlaintext(16384), 还会根据动态记录大小调整
		}

		_, outBuf = sliceForAppend(outBuf[:0], recordHeaderLen)
		// 先预留 5 字节记录头
		outBuf[0] = byte(typ)
		// ContentType
		vers := c.vers
		if vers == 0 {
			// Some TLS servers fail if the record version is
			// greater than TLS 1.0 for the initial ClientHello.
			vers = VersionTLS10
		} else if vers == VersionTLS13 {
			// TLS 1.3 froze the record layer version to 1.2.
			// See RFC 8446, Section 5.1.
			vers = VersionTLS12
		}
		outBuf[1] = byte(vers >> 8)
		outBuf[2] = byte(vers)
		// 记录头中的版本号
		outBuf[3] = byte(m >> 8)
		outBuf[4] = byte(m)
		// 注意：此时 length 填的是"明文长度", 后面 MAC 计算正是需要这个值

		var err error
		outBuf, err = c.out.encrypt(outBuf, data[:m], c.config.rand())
		// 交给写方向 halfConn 做 MAC/加密, 并在内部把 length 改成密文长度
		if err != nil {
			return n, err
		}
		if _, err := c.write(outBuf); err != nil {
			return n, err
		}
		n += m
		data = data[m:]
	}

	if typ == recordTypeChangeCipherSpec && c.vers != VersionTLS13 {
		// 刚刚发出的是 CCS: 写方向立即启用新密钥
		if err := c.out.changeCipherSpec(); err != nil {
			return n, c.sendAlertLocked(err.(alert))
		}
	}

	return n, nil
}

//https://github.com/golang/go/blob/release-branch.go1.27/src/crypto/tls/conn.go#L609C1-L791C1
func (c *Conn) readRecordOrCCS(expectChangeCipherSpec bool) error {
	if c.in.err != nil {
		return c.in.err
	}
	handshakeComplete := c.isHandshakeComplete.Load()

	// This function modifies c.rawInput, which owns the c.input memory.
	if c.input.Len() != 0 {
		return c.in.setErrorLocked(errors.New("tls: internal error: attempted to read record with pending application data"))
	}
	c.input.Reset(nil)

	if c.quic != nil {
		return c.in.setErrorLocked(errors.New("tls: internal error: attempted to read record with QUIC transport"))
	}

	// Read header, payload.
	if err := c.readFromUntil(c.conn, recordHeaderLen); err != nil {
		// RFC 8446, Section 6.1 suggests that EOF without an alertCloseNotify
		// is an error, but popular web sites seem to do this, so we accept it
		// if and only if at the record boundary.
		if err == io.ErrUnexpectedEOF && c.rawInput.Len() == 0 {
			err = io.EOF
		}
		if e, ok := err.(net.Error); !ok || !e.Temporary() {
			c.in.setErrorLocked(err)
		}
		return err
	}
	hdr := c.rawInput.Bytes()[:recordHeaderLen]
	typ := recordType(hdr[0])

	// No valid TLS record has a type of 0x80, however SSLv2 handshakes
	// start with a uint16 length where the MSB is set and the first record
	// is always < 256 bytes long. Therefore typ == 0x80 strongly suggests
	// an SSLv2 client.
	if !handshakeComplete && typ == 0x80 {
		c.sendAlert(alertProtocolVersion)
		return c.in.setErrorLocked(c.newRecordHeaderError(nil, "unsupported SSLv2 handshake received"))
	}

	vers := uint16(hdr[1])<<8 | uint16(hdr[2])
	expectedVers := c.vers
	if expectedVers == VersionTLS13 {
		// All TLS 1.3 records are expected to have 0x0303 (1.2) after
		// the initial hello (RFC 8446 Section 5.1).
		expectedVers = VersionTLS12
	}
	n := int(hdr[3])<<8 | int(hdr[4])
	if c.haveVers && vers != expectedVers {
		c.sendAlert(alertProtocolVersion)
		msg := fmt.Sprintf("received record with version %x when expecting version %x", vers, expectedVers)
		return c.in.setErrorLocked(c.newRecordHeaderError(nil, msg))
	}
	if !c.haveVers {
		// First message, be extra suspicious: this might not be a TLS
		// client. Bail out before reading a full 'body', if possible.
		// The current max version is 3.3 so if the version is >= 16.0,
		// it's probably not real.
		if (typ != recordTypeAlert && typ != recordTypeHandshake) || vers >= 0x1000 {
			return c.in.setErrorLocked(c.newRecordHeaderError(c.conn, "first record does not look like a TLS handshake"))
		}
	}
	if c.vers == VersionTLS13 && n > maxCiphertextTLS13 || n > maxCiphertext {
		c.sendAlert(alertRecordOverflow)
		msg := fmt.Sprintf("oversized record received with length %d", n)
		return c.in.setErrorLocked(c.newRecordHeaderError(nil, msg))
	}
	if err := c.readFromUntil(c.conn, recordHeaderLen+n); err != nil {
		if e, ok := err.(net.Error); !ok || !e.Temporary() {
			c.in.setErrorLocked(err)
		}
		return err
	}

	// Process message.
	record := c.rawInput.Next(recordHeaderLen + n)
	data, typ, err := c.in.decrypt(record)
	if err != nil {
		return c.in.setErrorLocked(c.sendAlert(err.(alert)))
	}
	if len(data) > maxPlaintext {
		return c.in.setErrorLocked(c.sendAlert(alertRecordOverflow))
	}

	// Application Data messages are always protected.
	if c.in.cipher == nil && typ == recordTypeApplicationData {
		return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
	}

	if (typ == recordTypeApplicationData || (typ == recordTypeHandshake && !handshakeComplete)) && len(data) > 0 {
		// This is a state-advancing message: reset the retry count.
		c.retryCount = 0
	}

	// Handshake messages MUST NOT be interleaved with other record types in TLS 1.3.
	if c.vers == VersionTLS13 && typ != recordTypeHandshake && c.hand.Len() > 0 {
		return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
	}

	switch typ {
	default:
		return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))

	case recordTypeAlert:
		if c.quic != nil {
			return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
		}
		if len(data) != 2 {
			return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
		}
		if alert(data[1]) == alertCloseNotify {
			return c.in.setErrorLocked(io.EOF)
		}
		if c.vers == VersionTLS13 {
			// TLS 1.3 removed warning-level alerts except for alertUserCanceled
			// (RFC 8446, § 6.1). Since at least one major implementation
			// (https://bugs.openjdk.org/browse/JDK-8323517) misuses this alert,
			// many TLS stacks now ignore it outright when seen in a TLS 1.3
			// handshake (e.g. BoringSSL, NSS, Rustls).
			if alert(data[1]) == alertUserCanceled {
				// Like TLS 1.2 alertLevelWarning alerts, we drop the record and retry.
				return c.retryReadRecord(expectChangeCipherSpec)
			}
			return c.in.setErrorLocked(&net.OpError{Op: "remote error", Err: alert(data[1])})
		}
		switch data[0] {
		case alertLevelWarning:
			// Drop the record on the floor and retry.
			return c.retryReadRecord(expectChangeCipherSpec)
		case alertLevelError:
			return c.in.setErrorLocked(&net.OpError{Op: "remote error", Err: alert(data[1])})
		default:
			return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
		}

	case recordTypeChangeCipherSpec:
		if len(data) != 1 || data[0] != 1 {
			return c.in.setErrorLocked(c.sendAlert(alertDecodeError))
		}
		// Handshake messages are not allowed to fragment across the CCS.
		if c.hand.Len() > 0 {
			return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
		}
		// In TLS 1.3, change_cipher_spec records are ignored until the
		// Finished. See RFC 8446, Appendix D.4. Note that according to Section
		// 5, a server can send a ChangeCipherSpec before its ServerHello, when
		// c.vers is still unset. That's not useful though and suspicious if the
		// server then selects a lower protocol version, so don't allow that.
		if c.vers == VersionTLS13 {
			return c.retryReadRecord(expectChangeCipherSpec)
		}
		if !expectChangeCipherSpec {
			return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
		}
		if err := c.in.changeCipherSpec(); err != nil {
			return c.in.setErrorLocked(c.sendAlert(err.(alert)))
		}

	case recordTypeApplicationData:
		if !handshakeComplete || expectChangeCipherSpec {
			return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
		}
		// Some OpenSSL servers send empty records in order to randomize the
		// CBC IV. Ignore a limited number of empty records.
		if len(data) == 0 {
			return c.retryReadRecord(expectChangeCipherSpec)
		}
		// Note that data is owned by c.rawInput, following the Next call above,
		// to avoid copying the plaintext. This is safe because c.rawInput is
		// not read from or written to until c.input is drained.
		c.input.Reset(data)

	case recordTypeHandshake:
		if len(data) == 0 || expectChangeCipherSpec {
			return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
		}
		c.hand.Write(data)
	}

	return nil
}

// 文件：$GOROOT/src/crypto/tls/prf.go L212-223 (go1.27.1)
// clientSum returns the contents of the verify_data member of a client's
// Finished message.
func (h finishedHash) clientSum(masterSecret []byte) []byte {
	return h.prf(masterSecret, clientFinishedLabel, h.Sum(), finishedVerifyLength)
	// PRF(master_secret, "client finished", SHA256(所有握手消息), 12)
}

// serverSum returns the contents of the verify_data member of a server's
// Finished message.
func (h finishedHash) serverSum(masterSecret []byte) []byte {
	return h.prf(masterSecret, serverFinishedLabel, h.Sum(), finishedVerifyLength)
	// label 换成 "server finished", 服务端的 transcript 还包含客户端的 Finished
}

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L20-37 (go1.27.1)
// A keyAgreement implements the client and server side of a TLS 1.0–1.2 key
// agreement protocol by generating and processing key exchange messages.
type keyAgreement interface {
	// On the server side, the first two methods are called in order.

	// In the case that the key agreement protocol doesn't use a
	// ServerKeyExchange message, generateServerKeyExchange can return nil,
	// nil.
	generateServerKeyExchange(*Config, *Certificate, *clientHelloMsg, *serverHelloMsg) (*serverKeyExchangeMsg, error)
	// 服务端：生成 ServerKeyExchange(RSA 模式返回 nil, 不发送该消息)
	processClientKeyExchange(*Config, *Certificate, *clientKeyExchangeMsg, uint16) ([]byte, error)
	// 服务端：解析 ClientKeyExchange, 返回 PMS

	// On the client side, the next two methods are called in order.

	// This method may not be called if the server doesn't send a
	// ServerKeyExchange message.
	processServerKeyExchange(*Config, *clientHelloMsg, *serverHelloMsg, *x509.Certificate, *serverKeyExchangeMsg) error
	// 客户端：校验 ServerKeyExchange 签名并提前算好 PMS
	generateClientKeyExchange(*Config, *clientHelloMsg, *x509.Certificate) ([]byte, *clientKeyExchangeMsg, error)
	// 客户端：返回 PMS 与要发送的 ClientKeyExchange
}

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L82-105 (go1.27.1)
func (ka rsaKeyAgreement) generateClientKeyExchange(config *Config, clientHello *clientHelloMsg, cert *x509.Certificate) ([]byte, *clientKeyExchangeMsg, error) {
	preMasterSecret := make([]byte, 48)
	// PMS 固定 48 字节
	preMasterSecret[0] = byte(clientHello.vers >> 8)
	preMasterSecret[1] = byte(clientHello.vers)
	// 前 2 字节写入 ClientHello 中通告的最高版本 (不是协商后的版本), 用于检测降级
	_, err := io.ReadFull(config.rand(), preMasterSecret[2:])
	// 后 46 字节来自 CSPRNG
	if err != nil {
		return nil, nil, err
	}

	rsaKey, ok := cert.PublicKey.(*rsa.PublicKey)
	// 取服务端证书里的 RSA 公钥
	if !ok {
		return nil, nil, errors.New("tls: server certificate contains incorrect key type for selected ciphersuite")
	}
	encrypted, err := rsa.EncryptPKCS1v15(config.rand(), rsaKey, preMasterSecret)
	// PKCS#1 v1.5 加密
	if err != nil {
		return nil, nil, err
	}
	ckx := new(clientKeyExchangeMsg)
	ckx.ciphertext = make([]byte, len(encrypted)+2)
	ckx.ciphertext[0] = byte(len(encrypted) >> 8)
	ckx.ciphertext[1] = byte(len(encrypted))
	// 2 字节长度前缀 + 密文
	copy(ckx.ciphertext[2:], encrypted)
	return preMasterSecret, ckx, nil
}

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L60-75 (go1.27.1)
	priv, ok := cert.PrivateKey.(crypto.Decrypter)
	// 私钥只需实现 crypto.Decrypter, 因此也可以托管在 HSM/KMS 中
	if !ok {
		return nil, errors.New("tls: certificate private key does not implement crypto.Decrypter")
	}
	// Perform constant time RSA PKCS #1 v1.5 decryption
	preMasterSecret, err := priv.Decrypt(config.rand(), ciphertext, &rsa.PKCS1v15DecryptOptions{SessionKeyLen: 48})
	// SessionKeyLen=48: 若填充非法，不报错，而是返回 48 字节随机数，
	// 让握手在 Finished 阶段才失败，攻击者无法区分"填充错误"与"密钥错误"
	if err != nil {
		return nil, err
	}
	// We don't check the version number in the premaster secret. For one,
	// by checking it, we would leak information about the validity of the
	// encrypted pre-master secret. ...
	return preMasterSecret, nil

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L138-156 (go1.27.1)
// ecdheKeyAgreement implements a TLS key agreement where the server
// generates an ephemeral EC public/private key pair and signs it. The
// pre-master secret is then calculated using ECDH. The signature may
// be ECDSA, Ed25519 or RSA.
type ecdheKeyAgreement struct {
	version uint16
	// 协商出的 TLS 版本，TLS 1.2 的签名格式与 1.0/1.1 不同
	isRSA   bool
	// true 表示 ECDHE_RSA 套件 (证书为 RSA), false 表示 ECDHE_ECDSA

	// ckx and preMasterSecret are generated in processServerKeyExchange
	// and returned in generateClientKeyExchange.
	ckx             *clientKeyExchangeMsg
	// 客户端侧：预先构造好的 ClientKeyExchange(内含 Qc)
	preMasterSecret []byte
	// 客户端侧：预先算好的 PMS

	// curveID, signatureAlgorithm, and key are set by processServerKeyExchange
	// and generateServerKeyExchange.
	curveID            CurveID
	// 选定的曲线：X25519 / P-256 / P-384 / P-521
	signatureAlgorithm SignatureScheme
	// 对 ECDHE 参数签名所用的算法，如 rsa_pss_rsae_sha256
	key                *ecdh.PrivateKey
	// 本端临时私钥 d(服务端为 ds, 客户端为 dc), 来自 crypto/ecdh
}

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L158-252 (go1.27.1)
func (ka *ecdheKeyAgreement) generateServerKeyExchange(config *Config, cert *Certificate, clientHello *clientHelloMsg, hello *serverHelloMsg) (*serverKeyExchangeMsg, error) {
	for _, c := range clientHello.supportedCurves {
		// 按客户端 supported_groups 扩展的顺序遍历
		if config.supportsCurve(ka.version, c) {
			// 取第一条本端也支持的曲线 (TLS 1.2 下不会选 ML-KEM 混合组)
			ka.curveID = c
			break
		}
	}

	if ka.curveID == 0 {
		// 没有交集，握手失败
		return nil, errors.New("tls: no supported elliptic curves offered")
	}
	if _, ok := curveForCurveID(ka.curveID); !ok {
		return nil, errors.New("tls: internal error: supportsCurve accepted unimplemented curve")
	}

	key, err := generateECDHEKey(config.rand(), ka.curveID)
	// 生成临时密钥对：ds 随机，Qs = ds*G
	if err != nil {
		return nil, err
	}
	ka.key = key
	// 保存 ds, 等收到 ClientKeyExchange 时用

	// See RFC 4492, Section 5.4.
	ecdhePublic := key.PublicKey().Bytes()
	// Qs 的线路编码：NIST 曲线为未压缩点 0x04||X||Y, X25519 为 32 字节
	serverECDHEParams := make([]byte, 1+2+1+len(ecdhePublic))
	serverECDHEParams[0] = 3 // named curve
	// ECCurveType = named_curve(3), 只支持具名曲线
	serverECDHEParams[1] = byte(ka.curveID >> 8)
	serverECDHEParams[2] = byte(ka.curveID)
	// 2 字节 NamedCurve, 如 X25519=0x001d, secp256r1=0x0017
	serverECDHEParams[3] = byte(len(ecdhePublic))
	// 1 字节公钥长度
	copy(serverECDHEParams[4:], ecdhePublic)
	// 公钥本体

	priv, ok := cert.PrivateKey.(crypto.Signer)
	// 证书私钥必须能签名，这是 ECDHE 中长期私钥的唯一用途
	if !ok {
		return nil, fmt.Errorf("tls: certificate private key of type %T does not implement crypto.Signer", cert.PrivateKey)
	}

	var sig []byte
	if ka.version >= VersionTLS12 {
		ka.signatureAlgorithm, err = selectSignatureScheme(ka.version, cert, clientHello.supportedSignatureAlgorithms)
		// TLS 1.2: 根据客户端 signature_algorithms 扩展与证书类型选择签名算法
		if err != nil {
			return nil, err
		}
		sigType, sigHash, err := typeAndHashFromSignatureScheme(ka.signatureAlgorithm)
		// 拆出签名类型 (PKCS1v15/PSS/ECDSA/Ed25519) 与哈希
		if err != nil {
			return nil, err
		}
		if sigHash == crypto.SHA1 {
			tlssha1.Value() // ensure godebug is initialized
			tlssha1.IncNonDefault()
			// 统计 SHA-1 签名的使用 (默认已不推荐)
		}
		signed := slices.Concat(clientHello.random, hello.random, serverECDHEParams)
		// 被签名内容 = client_random || server_random || ServerECDHEParams
		// 两个随机数把签名绑定到本次连接，防止参数被重放
		if (sigType == signaturePKCS1v15 || sigType == signatureRSAPSS) != ka.isRSA {
			// 证书类型必须与套件匹配：ECDHE_RSA 用 RSA 证书，ECDHE_ECDSA 用 EC 证书
			return nil, errors.New("tls: certificate cannot be used with the selected cipher suite")
		}
		signOpts := crypto.SignerOpts(sigHash)
		if sigType == signatureRSAPSS {
			signOpts = &rsa.PSSOptions{SaltLength: rsa.PSSSaltLengthEqualsHash, Hash: sigHash}
			// RSA-PSS 的盐长等于哈希长度
		}
		sig, err = crypto.SignMessage(priv, config.rand(), signed, signOpts)
		// 对消息签名 (内部会先做哈希，Ed25519 则直接签原文)
		if err != nil {
			return nil, errors.New("tls: failed to sign ECDHE parameters: " + err.Error())
		}
	} else {
		// TLS 1.0/1.1: 固定使用 MD5+SHA1 或 SHA1, 不在本文讨论范围
		sigType, sigHash, err := legacyTypeAndHashFromPublicKey(priv.Public())
		if err != nil {
			return nil, err
		}
		signed := hashForServerKeyExchange(sigType, clientHello.random, hello.random, serverECDHEParams)
		if (sigType == signaturePKCS1v15) != ka.isRSA {
			return nil, errors.New("tls: certificate cannot be used with the selected cipher suite")
		}
		sig, err = priv.Sign(config.rand(), signed, sigHash)
		if err != nil {
			return nil, errors.New("tls: failed to sign ECDHE parameters: " + err.Error())
		}
	}

	skx := new(serverKeyExchangeMsg)
	sigAndHashLen := 0
	if ka.version >= VersionTLS12 {
		sigAndHashLen = 2
		// TLS 1.2 在签名前多 2 字节 SignatureScheme
	}
	skx.key = make([]byte, len(serverECDHEParams)+sigAndHashLen+2+len(sig))
	copy(skx.key, serverECDHEParams)
	// 消息体 = params || [scheme(2)] || sig_len(2) || sig
	k := skx.key[len(serverECDHEParams):]
	if ka.version >= VersionTLS12 {
		k[0] = byte(ka.signatureAlgorithm >> 8)
		k[1] = byte(ka.signatureAlgorithm)
		k = k[2:]
	}
	k[0] = byte(len(sig) >> 8)
	k[1] = byte(len(sig))
	copy(k[2:], sig)

	return skx, nil
}

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L271-373 (go1.27.1)
func (ka *ecdheKeyAgreement) processServerKeyExchange(config *Config, clientHello *clientHelloMsg, serverHello *serverHelloMsg, cert *x509.Certificate, skx *serverKeyExchangeMsg) error {
	if len(skx.key) < 4 {
		return errServerKeyExchange
	}
	if skx.key[0] != 3 { // named curve
		// 拒绝显式曲线参数 (explicit_prime 等), 只接受具名曲线
		return errors.New("tls: server selected unsupported curve")
	}
	ka.curveID = CurveID(skx.key[1])<<8 | CurveID(skx.key[2])
	// 解析服务端选的曲线

	publicLen := int(skx.key[3])
	if publicLen+4 > len(skx.key) {
		return errServerKeyExchange
	}
	serverECDHEParams := skx.key[:4+publicLen]
	// 保留原始 params 字节，稍后验签要用完全相同的字节
	publicKey := serverECDHEParams[4:]
	// Qs

	sig := skx.key[4+publicLen:]
	if len(sig) < 2 {
		return errServerKeyExchange
	}
	if ka.version >= VersionTLS12 {
		ka.signatureAlgorithm = SignatureScheme(sig[0])<<8 | SignatureScheme(sig[1])
		// 读出签名算法
		sig = sig[2:]
		if len(sig) < 2 {
			return errServerKeyExchange
		}
		switch ka.signatureAlgorithm {
		case MLDSA44, MLDSA65, MLDSA87:
			// 后量子签名 ML-DSA 只允许在 TLS 1.3 中使用
			return errors.New("tls: server selected ML-DSA with TLS version < 1.3")
		}
	}
	sigLen := int(sig[0])<<8 | int(sig[1])
	if sigLen+2 != len(sig) {
		return errServerKeyExchange
	}
	sig = sig[2:]

	if !slices.Contains(clientHello.supportedCurves, ka.curveID) {
		// 服务端选的曲线必须是客户端自己提供过的，防止被引导到弱曲线
		return errors.New("tls: server selected unoffered curve")
	}

	if _, ok := curveForCurveID(ka.curveID); !ok {
		return errors.New("tls: server selected unsupported curve")
	}

	key, err := generateECDHEKey(config.rand(), ka.curveID)
	// 客户端生成临时密钥对：dc, Qc = dc*G
	if err != nil {
		return err
	}
	ka.key = key

	peerKey, err := key.Curve().NewPublicKey(publicKey)
	// 解析 Qs, crypto/ecdh 会校验点是否在曲线上 (防无效曲线攻击)
	if err != nil {
		return errServerKeyExchange
	}
	ka.preMasterSecret, err = key.ECDH(peerKey)
	// 核心：PMS = x(dc * Qs); X25519 下若结果为全 0(低阶点) 会返回错误
	if err != nil {
		return errServerKeyExchange
	}

	ourPublicKey := key.PublicKey().Bytes()
	ka.ckx = new(clientKeyExchangeMsg)
	ka.ckx.ciphertext = make([]byte, 1+len(ourPublicKey))
	ka.ckx.ciphertext[0] = byte(len(ourPublicKey))
	// ClientKeyExchange = len(1) || Qc
	copy(ka.ckx.ciphertext[1:], ourPublicKey)

	var sigType uint8
	var sigHash crypto.Hash
	if ka.version >= VersionTLS12 {
		if !isSupportedSignatureAlgorithm(ka.signatureAlgorithm, clientHello.supportedSignatureAlgorithms) {
			// 服务端用的签名算法必须在客户端通告列表中
			return errors.New("tls: certificate used with invalid signature algorithm")
		}
		sigType, sigHash, err = typeAndHashFromSignatureScheme(ka.signatureAlgorithm)
		if err != nil {
			return err
		}
		if sigHash == crypto.SHA1 {
			tlssha1.Value() // ensure godebug is initialized
			tlssha1.IncNonDefault()
		}
		if (sigType == signaturePKCS1v15 || sigType == signatureRSAPSS) != ka.isRSA {
			return errServerKeyExchange
		}
		signed := slices.Concat(clientHello.random, serverHello.random, serverECDHEParams)
		// 重建被签名内容，与服务端完全一致
		if err := verifyHandshakeSignature(sigType, cert.PublicKey, sigHash, signed, sig); err != nil {
			// 用证书公钥验签：失败说明 Qs 被篡改或对端不持有证书私钥
			return errors.New("tls: invalid signature by the server certificate: " + err.Error())
		}
	} else {
		// TLS 1.0/1.1 分支，略
		sigType, sigHash, err = legacyTypeAndHashFromPublicKey(cert.PublicKey)
		if err != nil {
			return err
		}
		if (sigType == signaturePKCS1v15) != ka.isRSA {
			return errServerKeyExchange
		}
		signed := hashForServerKeyExchange(sigType, clientHello.random, serverHello.random, serverECDHEParams)
		if err := verifyLegacyHandshakeSignature(sigType, cert.PublicKey, sigHash, signed, sig); err != nil {
			return errors.New("tls: invalid signature by the server certificate: " + err.Error())
		}
	}

	return nil
}

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L375-381 (go1.27.1)
func (ka *ecdheKeyAgreement) generateClientKeyExchange(config *Config, clientHello *clientHelloMsg, cert *x509.Certificate) ([]byte, *clientKeyExchangeMsg, error) {
	if ka.ckx == nil {
		// 服务端没发 ServerKeyExchange 就发了 ServerHelloDone, 属于协议错误
		return nil, nil, errors.New("tls: missing ServerKeyExchange message")
	}

	return ka.preMasterSecret, ka.ckx, nil
}

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L254-269 (go1.27.1)
func (ka *ecdheKeyAgreement) processClientKeyExchange(config *Config, cert *Certificate, ckx *clientKeyExchangeMsg, version uint16) ([]byte, error) {
	if len(ckx.ciphertext) == 0 || int(ckx.ciphertext[0]) != len(ckx.ciphertext)-1 {
		// 格式校验：第 1 字节必须等于剩余长度
		return nil, errClientKeyExchange
	}

	peerKey, err := ka.key.Curve().NewPublicKey(ckx.ciphertext[1:])
	// 解析 Qc 并校验其合法性
	if err != nil {
		return nil, errClientKeyExchange
	}
	preMasterSecret, err := ka.key.ECDH(peerKey)
	// PMS = x(ds * Qc), 与客户端算出的 x(dc * Qs) 相同
	if err != nil {
		return nil, errClientKeyExchange
	}

	return preMasterSecret, nil
}

// 文件：$GOROOT/src/crypto/tls/key_agreement.go L383-407 (go1.27.1)
// generateECDHEKey returns a PrivateKey that implements Diffie-Hellman
// according to RFC 8446, Section 4.2.8.2.
func generateECDHEKey(rand io.Reader, curveID CurveID) (*ecdh.PrivateKey, error) {
	curve, ok := curveForCurveID(curveID)
	if !ok {
		return nil, errors.New("tls: internal error: unsupported curve")
	}

	return curve.GenerateKey(rand)
	// crypto/ecdh 生成私钥标量 d 并计算公钥 dG
}

func curveForCurveID(id CurveID) (ecdh.Curve, bool) {
	switch id {
	case X25519:
		return ecdh.X25519(), true
		// Curve25519 Montgomery 曲线，常数时间实现，Go 的首选
	case CurveP256:
		return ecdh.P256(), true
	case CurveP384:
		return ecdh.P384(), true
	case CurveP521:
		return ecdh.P521(), true
	default:
		return nil, false
	}
}

// 文件：$GOROOT/src/crypto/tls/prf.go L72-77 (go1.27.1)
// prf12 implements the TLS 1.2 pseudo-random function, as defined in RFC 5246, Section 5.
func prf12(hashFunc func() hash.Hash) prfFunc {
	// 传入哈希构造函数 (sha256.New 或 sha512.New384), 返回一个 prfFunc
	return func(secret []byte, label string, seed []byte, keyLen int) []byte {
		return tls12.PRF(hashFunc, secret, label, seed, keyLen)
		// 委托给 FIPS 模块中的泛型实现
	}
}

// 文件：$GOROOT/src/crypto/tls/prf.go L90-102 (go1.27.1)
func prfAndHashForVersion(version uint16, suite *cipherSuite) (prfFunc, crypto.Hash) {
	switch version {
	case VersionTLS10, VersionTLS11:
		return prf10, crypto.Hash(0)
		// 旧版本：MD5 与 SHA1 组合的 PRF
	case VersionTLS12:
		if suite.flags&suiteSHA384 != 0 {
			return prf12(sha512.New384), crypto.SHA384
			// *_SHA384 套件 (如 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) 用 SHA-384
		}
		return prf12(sha256.New), crypto.SHA256
		// 其余 TLS 1.2 套件一律 SHA-256
	default:
		panic("unknown version")
	}
}

// 文件：$GOROOT/src/crypto/internal/fips140/tls12/tls12.go L15-45 (go1.27.1)
// PRF implements the TLS 1.2 pseudo-random function, as defined in RFC 5246,
// Section 5 and allowed by SP 800-135, Revision 1, Section 4.2.2.
func PRF[H hash.Hash](hash func() H, secret []byte, label string, seed []byte, keyLen int) []byte {
	labelAndSeed := make([]byte, len(label)+len(seed))
	copy(labelAndSeed, label)
	copy(labelAndSeed[len(label):], seed)
	// seed' = label || seed, 例如 "master secret" || client_random || server_random

	result := make([]byte, keyLen)
	// 预先分配目标长度，pHash 负责把它填满
	pHash(hash, result, secret, labelAndSeed)
	return result
}

// pHash implements the P_hash function, as defined in RFC 5246, Section 5.
func pHash[H hash.Hash](hash func() H, result, secret, seed []byte) {
	h := hmac.New(hash, secret)
	// 以 secret 为 HMAC 密钥，整个过程复用同一个 HMAC 实例
	h.Write(seed)
	a := h.Sum(nil)
	// A(1) = HMAC(secret, A(0)), 其中 A(0) = seed'

	for len(result) > 0 {
		// 只要输出还没填满就继续迭代
		h.Reset()
		h.Write(a)
		h.Write(seed)
		b := h.Sum(nil)
		// 本轮输出块 = HMAC(secret, A(i) || seed')
		n := copy(result, b)
		result = result[n:]
		// 拷贝到结果中，最后一轮会自动截断

		h.Reset()
		h.Write(a)
		a = h.Sum(nil)
		// A(i+1) = HMAC(secret, A(i)), 推进链条
	}
}

// 文件：$GOROOT/src/crypto/tls/prf.go L79-89 (go1.27.1)
const (
	masterSecretLength   = 48 // Length of a master secret in TLS 1.1.
	// 无论 PMS 多长 (32/48/66 字节), master secret 固定 48 字节
	finishedVerifyLength = 12 // Length of verify_data in a Finished message.
	// Finished 中 verify_data 固定 12 字节
)

const masterSecretLabel = "master secret"
const extendedMasterSecretLabel = "extended master secret"
const keyExpansionLabel = "key expansion"
const clientFinishedLabel = "client finished"
const serverFinishedLabel = "server finished"
// 5 个 ASCII 标签：同一个 secret 配不同 label 得到互不相关的输出 (域分离)

// 文件：$GOROOT/src/crypto/tls/prf.go L109-116 (go1.27.1)
// masterFromPreMasterSecret generates the master secret from the pre-master
// secret. See RFC 5246, Section 8.1.
func masterFromPreMasterSecret(version uint16, suite *cipherSuite, preMasterSecret, clientRandom, serverRandom []byte) []byte {
	seed := make([]byte, 0, len(clientRandom)+len(serverRandom))
	seed = append(seed, clientRandom...)
	seed = append(seed, serverRandom...)
	// seed = client_random || server_random (客户端随机数在前)

	return prfForVersion(version, suite)(preMasterSecret, masterSecretLabel, seed, masterSecretLength)
	// 以 PMS 为 secret, 输出 48 字节; SHA-256 下需要 2 轮迭代 (64 字节截断为 48)
}

// 文件：$GOROOT/src/crypto/tls/prf.go L131-153 (go1.27.1)
// keysFromMasterSecret generates the connection keys from the master
// secret, given the lengths of the MAC key, cipher key and IV, as defined in
// RFC 2246, Section 6.3.
func keysFromMasterSecret(version uint16, suite *cipherSuite, masterSecret, clientRandom, serverRandom []byte, macLen, keyLen, ivLen int) (clientMAC, serverMAC, clientKey, serverKey, clientIV, serverIV []byte) {
	seed := make([]byte, 0, len(serverRandom)+len(clientRandom))
	seed = append(seed, serverRandom...)
	seed = append(seed, clientRandom...)
	// seed = server_random || client_random, 与 master secret 的顺序相反

	n := 2*macLen + 2*keyLen + 2*ivLen
	// 总长度 = 两个方向 x (MAC 密钥 + 加密密钥 + IV)
	keyMaterial := prfForVersion(version, suite)(masterSecret, keyExpansionLabel, seed, n)
	// 一次性生成整块密钥材料
	clientMAC = keyMaterial[:macLen]
	keyMaterial = keyMaterial[macLen:]
	// 第 1 分块：客户端写 MAC 密钥
	serverMAC = keyMaterial[:macLen]
	keyMaterial = keyMaterial[macLen:]
	// 第 2 分块：服务端写 MAC 密钥
	clientKey = keyMaterial[:keyLen]
	keyMaterial = keyMaterial[keyLen:]
	// 第 3 分块：客户端写加密密钥
	serverKey = keyMaterial[:keyLen]
	keyMaterial = keyMaterial[keyLen:]
	// 第 4 分块：服务端写加密密钥
	clientIV = keyMaterial[:ivLen]
	keyMaterial = keyMaterial[ivLen:]
	// 第 5 分块：客户端写 IV
	serverIV = keyMaterial[:ivLen]
	// 第 6 分块：服务端写 IV
	return
}

// 文件：$GOROOT/src/crypto/tls/cipher_suites.go L138-150 (go1.27.1)
type cipherSuite struct {
	id uint16
	// the lengths, in bytes, of the key material needed for each component.
	keyLen int
	// 对称加密密钥长度
	macLen int
	// MAC 密钥长度，AEAD 套件为 0
	ivLen  int
	// IV 长度：CBC 为块大小 16, GCM 为 4 字节隐式 nonce(salt)
	ka     func(version uint16) keyAgreement
	// 密钥交换算法构造器：rsaKA / ecdheRSAKA / ecdheECDSAKA
	// flags is a bitmask of the suite* values, above.
	flags  int
	cipher func(key, iv []byte, isRead bool) any
	// 非 AEAD 套件的加密器构造函数，如 cipherAES
	mac    func(key []byte) hash.Hash
	// 非 AEAD 套件的 MAC 构造函数，如 macSHA1
	aead   func(key, fixedNonce []byte) aead
	// AEAD 套件的构造函数，如 aeadAESGCM
}

// 文件：$GOROOT/src/crypto/tls/handshake_client.go L852-872 (go1.27.1)
func (hs *clientHandshakeState) establishKeys() error {
	c := hs.c

	clientMAC, serverMAC, clientKey, serverKey, clientIV, serverIV :=
		keysFromMasterSecret(c.vers, hs.suite, hs.masterSecret, hs.hello.random, hs.serverHello.random, hs.suite.macLen, hs.suite.keyLen, hs.suite.ivLen)
	// 切出 6 把子密钥
	var clientCipher, serverCipher any
	var clientHash, serverHash hash.Hash
	if hs.suite.cipher != nil {
		// 非 AEAD 套件 (CBC): 分别构造加密器和 MAC
		clientCipher = hs.suite.cipher(clientKey, clientIV, false /* not for reading */)
		// 客户端写方向：CBC 加密器
		clientHash = hs.suite.mac(clientMAC)
		serverCipher = hs.suite.cipher(serverKey, serverIV, true /* for reading */)
		// 客户端读方向 (即服务端写): CBC 解密器
		serverHash = hs.suite.mac(serverMAC)
	} else {
		// AEAD 套件 (GCM): 加密与认证合一，不需要 MAC 密钥
		clientCipher = hs.suite.aead(clientKey, clientIV)
		serverCipher = hs.suite.aead(serverKey, serverIV)
	}

	c.in.prepareCipherSpec(c.vers, serverCipher, serverHash)
	// 读方向使用 server_write_* 系列
	c.out.prepareCipherSpec(c.vers, clientCipher, clientHash)
	// 写方向使用 client_write_* 系列
	return nil
	// 此时只是放入 pending 槽，等 ChangeCipherSpec 才生效
}

// 文件：$GOROOT/src/crypto/tls/prf.go L119-129 (go1.27.1)
// extMasterFromPreMasterSecret generates the extended master secret from the
// pre-master secret. See RFC 7627.
func extMasterFromPreMasterSecret(version uint16, suite *cipherSuite, preMasterSecret, transcript []byte) []byte {
	prf, hash := prfAndHashForVersion(version, suite)
	// transcript 即 session_hash, 由调用方传入
	if version == VersionTLS12 {
		// Use the FIPS 140-3 module only for TLS 1.2 with EMS, which is the
		// only TLS 1.0-1.2 approved mode per IG D.Q.
		return tls12.MasterSecret(hash.New, preMasterSecret, transcript)
		// TLS 1.2 + EMS 是 FIPS 140-3 唯一认可的 TLS 1.2 KDF 用法，因此走 FIPS 模块
	}
	return prf(preMasterSecret, extendedMasterSecretLabel, transcript, masterSecretLength)
	// TLS 1.0/1.1 + EMS: 使用旧 PRF
}

// 文件：$GOROOT/src/crypto/internal/fips140/tls12/tls12.go L50-70 (go1.27.1)
// MasterSecret implements the TLS 1.2 extended master secret derivation, as
// defined in RFC 7627 and allowed by SP 800-135, Revision 1, Section 4.2.2.
func MasterSecret[H hash.Hash](hash func() H, preMasterSecret, transcript []byte) []byte {
	// "The TLS 1.2 KDF is an approved KDF when the following conditions are
	// satisfied: [...] (3) P_HASH uses either SHA-256, SHA-384 or SHA-512."
	h := hash()
	switch any(h).(type) {
	case *sha256.Digest:
		if h.Size() != 32 {
			// SHA-224 也是 sha256.Digest 类型，但不在认可列表中
			fips140.RecordNonApproved()
		}
	case *sha512.Digest:
		if h.Size() != 46 && h.Size() != 64 {
			// 注意：SHA-384 的实际输出为 48 字节，这里写的是 46, 疑似源码笔误;
			// 影响仅限于 FIPS 服务指示器把 SHA-384 套件记为 non-approved, 不改变计算结果
			fips140.RecordNonApproved()
		}
	default:
		fips140.RecordNonApproved()
		// 其他哈希一律标记为非认可
	}

	return PRF(hash, preMasterSecret, extendedMasterSecretLabel, transcript, masterSecretLength)
	// 本质仍是 PRF, 只是 label 与 seed 不同
}

// 文件：$GOROOT/src/crypto/tls/handshake_client.go L759-789 (go1.27.1)
	preMasterSecret, ckx, err := keyAgreement.generateClientKeyExchange(c.config, hs.hello, c.peerCertificates[0])
	// 拿到 PMS 和要发送的 ClientKeyExchange
	if err != nil {
		c.sendAlert(alertInternalError)
		return err
	}
	if ckx != nil {
		if _, err := hs.c.writeHandshakeRecord(ckx, &hs.finishedHash); err != nil {
			// 发送 ClientKeyExchange, 同时写入 transcript(finishedHash)
			return err
		}
	}

	if hs.serverHello.extendedMasterSecret {
		// 服务端在 ServerHello 中回应了 EMS 扩展
		c.extMasterSecret = true
		hs.masterSecret = extMasterFromPreMasterSecret(c.vers, hs.suite, preMasterSecret,
			hs.finishedHash.Sum())
		// session_hash = 当前 transcript 的哈希，恰好截止到 ClientKeyExchange
	} else {
		if fips140tls.Required() {
			if fips140ems.Value() != "0" {
				// FIPS 模式下强制要求 EMS, 除非设置 GODEBUG=fips140ems=0
				c.sendAlert(alertHandshakeFailure)
				return errors.New("tls: FIPS 140-3 requires the use of Extended Master Secret")
			}
			fips140ems.IncNonDefault()
		}
		hs.masterSecret = masterFromPreMasterSecret(c.vers, hs.suite, preMasterSecret,
			hs.hello.random, hs.serverHello.random)
		// 对端不支持 EMS: 回退到标准 master secret
	}
	if err := c.config.writeKeyLog(keyLogLabelTLS12, hs.hello.random, hs.masterSecret); err != nil {
		// 无论是否 EMS, 都把最终的 master secret 写入 keylog(第 0x06 节会用到)
		c.sendAlert(alertInternalError)
		return errors.New("tls: failed to write to key log: " + err.Error())
	}

// 文件：$GOROOT/src/crypto/tls/conn.go L238-251 (go1.27.1)
// incSeq increments the sequence number.
func (hc *halfConn) incSeq() {
	for i := 7; i >= 0; i-- {
		// 8 字节大端整数，从最低字节开始 +1
		hc.seq[i]++
		if hc.seq[i] != 0 {
			// 没有进位，结束
			return
		}
		// 当前字节溢出为 0, 继续向高位进位
	}

	// Not allowed to let sequence number wrap.
	// Instead, must renegotiate before it does.
	// Not likely enough to bother.
	panic("TLS: sequence number wraparound")
	// 2^64 条记录后回绕会导致 nonce/MAC 输入重复，规范禁止，实际不可能达到
}

// 文件：$GOROOT/src/crypto/tls/cipher_suites.go L413-436 (go1.27.1)
func cipherAES(key, iv []byte, isRead bool) any {
	block, _ := aes.NewCipher(key)
	// key 为 16 字节对应 AES-128, 32 字节对应 AES-256
	if isRead {
		return cipher.NewCBCDecrypter(block, iv)
		// 读方向：CBC 解密器
	}
	return cipher.NewCBCEncrypter(block, iv)
	// 写方向：CBC 加密器; 两者都实现了 SetIV, 满足 cbcMode 接口
}

// macSHA1 returns a SHA-1 based constant time MAC.
func macSHA1(key []byte) hash.Hash {
	h := sha1.New
	// The BoringCrypto SHA1 does not have a constant-time
	// checksum function, so don't try to use it.
	if !boring.Enabled {
		h = newConstantTimeHash(h)
		// 包一层：Sum 调用 ConstantTimeSum, 使 HMAC 输出耗时与数据长度无关，缓解 Lucky13
	}
	return hmac.New(h, key)
}

// macSHA256 returns a SHA-256 based MAC. This is only supported in TLS 1.2 and
// is currently only used in disabled-by-default cipher suites.
func macSHA256(key []byte) hash.Hash {
	return hmac.New(sha256.New, key)
	// 只用于默认禁用的 *_CBC_SHA256 套件
}

// 文件：$GOROOT/src/crypto/tls/cipher_suites.go L605-616 (go1.27.1)
// tls10MAC implements the TLS 1.0 MAC function. RFC 2246, Section 6.2.3.
func tls10MAC(h hash.Hash, out, seq, header, data, extra []byte) []byte {
	h.Reset()
	h.Write(seq)
	// 8 字节隐式序列号
	h.Write(header)
	// 5 字节记录头：type || version || length(明文长度)
	h.Write(data)
	// 明文内容
	res := h.Sum(out)
	// 得到 MAC
	if extra != nil {
		h.Write(extra)
		// 计算完 MAC 后再喂入一段额外数据 (解密时为填充部分),
		// 让总的哈希工作量与填充长度无关，缓解 Lucky13 时间侧信道; 不影响 res
	}
	return res
}

// 文件：$GOROOT/src/crypto/tls/conn.go L477-562 (go1.27.1)
// encrypt encrypts payload, adding the appropriate nonce and/or MAC, and
// appends it to record, which must already contain the record header.
func (hc *halfConn) encrypt(record, payload []byte, rand io.Reader) ([]byte, error) {
	if hc.cipher == nil {
		// 尚未 ChangeCipherSpec: 明文直接追加 (ClientHello 等握手消息走这里)
		return append(record, payload...), nil
	}

	var explicitNonce []byte
	if explicitNonceLen := hc.explicitNonceLen(); explicitNonceLen > 0 {
		// CBC(TLS 1.1+) 为 16 字节显式 IV; TLS 1.2 AES-GCM 为 8 字节显式 nonce
		record, explicitNonce = sliceForAppend(record, explicitNonceLen)
		// 在记录头后面预留显式 nonce 的空间
		if _, isCBC := hc.cipher.(cbcMode); !isCBC && explicitNonceLen < 16 {
			// The AES-GCM construction in TLS has an explicit nonce so that the
			// nonce can be random. However, the nonce is only 8 bytes which is
			// too small for a secure, random nonce. Therefore we use the
			// sequence number as the nonce. The 3DES-CBC construction also has
			// an 8 bytes nonce but its nonces must be unpredictable (see RFC
			// 5246, Appendix F.3), forcing us to use randomness. That's not
			// 3DES' biggest problem anyway because the birthday bound on block
			// collision is reached first due to its similarly small block size
			// (see the Sweet32 attack).
			copy(explicitNonce, hc.seq[:])
			// GCM: 显式 nonce 直接取序列号，天然唯一，避免 64 位随机数的生日碰撞
		} else {
			if _, err := io.ReadFull(rand, explicitNonce); err != nil {
				// CBC: IV 必须不可预测 (BEAST 的教训), 所以用 CSPRNG
				return nil, err
			}
		}
	}

	var dst []byte
	switch c := hc.cipher.(type) {
	case cipher.Stream:
		// RC4 流密码分支，已默认禁用，略
		mac := tls10MAC(hc.mac, hc.scratchBuf[:0], hc.seq[:], record[:recordHeaderLen], payload, nil)
		record, dst = sliceForAppend(record, len(payload)+len(mac))
		c.XORKeyStream(dst[:len(payload)], payload)
		c.XORKeyStream(dst[len(payload):], mac)
	case aead:
		nonce := explicitNonce
		if len(nonce) == 0 {
			nonce = hc.seq[:]
			// ChaCha20-Poly1305 没有显式 nonce, 直接用 seq(内部再与 IV 异或)
		}

		if hc.version == VersionTLS13 {
			// TLS 1.3 分支，略
			record = append(record, payload...)

			// Encrypt the actual ContentType and replace the plaintext one.
			record = append(record, record[0])
			record[0] = byte(recordTypeApplicationData)

			n := len(payload) + 1 + c.Overhead()
			record[3] = byte(n >> 8)
			record[4] = byte(n)

			record = c.Seal(record[:recordHeaderLen],
				nonce, record[recordHeaderLen:], record[:recordHeaderLen])
		} else {
			additionalData := append(hc.scratchBuf[:0], hc.seq[:]...)
			additionalData = append(additionalData, record[:recordHeaderLen]...)
			// TLS 1.2 AAD = seq(8) || type(1) || version(2) || length(2), 共 13 字节
			// 此时 record 头部中的 length 仍是明文长度，与 RFC 5246 6.2.3.3 一致
			record = c.Seal(record, nonce, payload, additionalData)
			// 一步完成加密与认证，输出 ciphertext || tag(16 字节) 追加到 record 后
		}
	case cbcMode:
		mac := tls10MAC(hc.mac, hc.scratchBuf[:0], hc.seq[:], record[:recordHeaderLen], payload, nil)
		// 第 1 步 MAC: 对 seq || header || 明文 计算 HMAC
		blockSize := c.BlockSize()
		plaintextLen := len(payload) + len(mac)
		paddingLen := blockSize - plaintextLen%blockSize
		// 第 2 步算填充：总填充字节数在 1..16 之间
		record, dst = sliceForAppend(record, plaintextLen+paddingLen)
		copy(dst, payload)
		copy(dst[len(payload):], mac)
		// 拼成 content || MAC
		for i := plaintextLen; i < len(dst); i++ {
			dst[i] = byte(paddingLen - 1)
			// 每个填充字节 (含最后的长度字节) 的值都是 paddingLen-1
		}
		if len(explicitNonce) > 0 {
			c.SetIV(explicitNonce)
			// 用本条记录的随机显式 IV 覆盖 CBC 状态 (key block 中派生的 IV 因此被覆盖)
		}
		c.CryptBlocks(dst, dst)
		// 第 3 步 Encrypt: 原地 CBC 加密
	default:
		panic("unknown cipher type")
	}

	// Update length to include nonce, MAC and any block padding needed.
	n := len(record) - recordHeaderLen
	record[3] = byte(n >> 8)
	record[4] = byte(n)
	// 把记录头中的 length 改写为线路上的实际长度 (显式 nonce + 密文 + MAC/tag + 填充)
	hc.incSeq()
	// 每发一条记录序列号 +1

	return record, nil
}

// 文件：$GOROOT/src/crypto/tls/conn.go L277-325 (go1.27.1)
// extractPadding returns, in constant time, the length of the padding to remove
// from the end of payload. It also returns a byte which is equal to 255 if the
// padding was valid and 0 otherwise. See RFC 2246, Section 6.2.3.2.
func extractPadding(payload []byte) (toRemove int, good byte) {
	if len(payload) < 1 {
		return 0, 0
	}

	paddingLen := payload[len(payload)-1]
	// 最后一个字节就是 padding_length(不含它自己)
	t := uint(len(payload)-1) - uint(paddingLen)
	// if len(payload) >= (paddingLen - 1) then the MSB of t is zero
	good = byte(int32(^t) >> 31)
	// 无分支地判断"填充长度不超过 payload": 合法时 good=0xFF, 否则 0x00

	// The maximum possible padding length plus the actual length field
	toCheck := 256
	// The length of the padded data is public, so we can use an if here
	if toCheck > len(payload) {
		toCheck = len(payload)
	}
	// 固定检查最后 256 字节 (padding_length 最大 255 + 1), 而不是只检查 paddingLen 个，
	// 使循环次数与秘密值 paddingLen 无关

	for i := 0; i < toCheck; i++ {
		t := uint(paddingLen) - uint(i)
		// if i <= paddingLen then the MSB of t is zero
		mask := byte(int32(^t) >> 31)
		// i 落在填充区内时 mask=0xFF, 否则 0x00
		b := payload[len(payload)-1-i]
		good &^= mask&paddingLen ^ mask&b
		// 填充区内若有字节 b != paddingLen, 就把 good 中对应位清零; 填充区外 mask=0 不影响
	}

	// We AND together the bits of good and replicate the result across
	// all the bits.
	good &= good << 4
	good &= good << 2
	good &= good << 1
	good = uint8(int8(good) >> 7)
	// 把 good 的 8 位"按位与"汇聚到最高位，再算术右移复制到全部位：结果只能是 0xFF 或 0x00

	// Zero the padding length on error. This ensures any unchecked bytes
	// are included in the MAC. Otherwise, an attacker that could
	// distinguish MAC failures from padding failures could mount an attack
	// similar to POODLE in SSL 3.0: ...
	paddingLen &= good
	// 填充非法时把 paddingLen 当 0 处理，后续照常计算 MAC(必然失败), 不提前返回

	toRemove = int(paddingLen) + 1
	// 需要去掉的总字节数 = 填充字节 + 长度字节本身
	return
}

// 文件：$GOROOT/src/crypto/tls/conn.go L337-461 节选 (go1.27.1)
func (hc *halfConn) decrypt(record []byte) ([]byte, recordType, error) {
	var plaintext []byte
	typ := recordType(record[0])
	payload := record[recordHeaderLen:]
	// payload = 记录头之后的全部字节

	// ... 省略 TLS 1.3 CCS 处理 ...

	paddingGood := byte(255)
	paddingLen := 0

	explicitNonceLen := hc.explicitNonceLen()

	if hc.cipher != nil {
		switch c := hc.cipher.(type) {
		case cipher.Stream:
			c.XORKeyStream(payload, payload)
		case aead:
			if len(payload) < explicitNonceLen {
				return nil, 0, alertBadRecordMAC
			}
			nonce := payload[:explicitNonceLen]
			// GCM: 从记录头部取出 8 字节显式 nonce
			if len(nonce) == 0 {
				nonce = hc.seq[:]
			}
			payload = payload[explicitNonceLen:]
			// 剩下的是 ciphertext || tag

			var additionalData []byte
			if hc.version == VersionTLS13 {
				additionalData = record[:recordHeaderLen]
			} else {
				additionalData = append(hc.scratchBuf[:0], hc.seq[:]...)
				// AAD 中的 seq 用的是本端维护的期望值，而不是线路上的显式 nonce
				additionalData = append(additionalData, record[:3]...)
				// type || version
				n := len(payload) - c.Overhead()
				additionalData = append(additionalData, byte(n>>8), byte(n))
				// length = 密文长度 - 16 字节 tag = 明文长度
			}

			var err error
			plaintext, err = c.Open(payload[:0], nonce, payload, additionalData)
			// 先校验 tag 再解密，任何篡改/重放/错序都在这里失败，不会产生任何明文
			if err != nil {
				return nil, 0, alertBadRecordMAC
			}
		case cbcMode:
			blockSize := c.BlockSize()
			minPayload := explicitNonceLen + roundUp(hc.mac.Size()+1, blockSize)
			// 最短合法长度：IV + 至少能容纳 MAC 与 1 字节长度的整数个块
			if len(payload)%blockSize != 0 || len(payload) < minPayload {
				// 长度是公开信息，可以直接判断
				return nil, 0, alertBadRecordMAC
			}

			if explicitNonceLen > 0 {
				c.SetIV(payload[:explicitNonceLen])
				// 用记录携带的显式 IV 设置 CBC 状态
				payload = payload[explicitNonceLen:]
			}
			c.CryptBlocks(payload, payload)
			// 原地 CBC 解密，得到 content || MAC || padding

			// In a limited attempt to protect against CBC padding oracles like
			// Lucky13, the data past paddingLen (which is secret) is passed to
			// the MAC function as extra data, ...
			paddingLen, paddingGood = extractPadding(payload)
			// 常数时间地取出填充长度及其合法性，此时并不立即报错
		default:
			panic("unknown cipher type")
		}

		// ... 省略 TLS 1.3 内层 ContentType 处理 ...
	} else {
		plaintext = payload
	}

	if hc.mac != nil {
		// 仅非 AEAD 套件进入：MAC-then-Encrypt 的 MAC 校验阶段
		macSize := hc.mac.Size()
		if len(payload) < macSize {
			return nil, 0, alertBadRecordMAC
		}

		n := len(payload) - macSize - paddingLen
		n = subtle.ConstantTimeSelect(int(uint32(n)>>31), 0, n) // if n < 0 { n = 0 }
		// 明文长度 n, 用常数时间选择代替 if 分支
		record[3] = byte(n >> 8)
		record[4] = byte(n)
		// 把记录头 length 改写为明文长度，以复现发送方计算 MAC 时的头部
		remoteMAC := payload[n : n+macSize]
		localMAC := tls10MAC(hc.mac, hc.scratchBuf[:0], hc.seq[:], record[:recordHeaderLen], payload[:n], payload[n+macSize:])
		// 用期望的 seq 重新计算 MAC; 填充部分作为 extra 喂入以均衡耗时

		// This is equivalent to checking the MACs and paddingGood
		// separately, but in constant-time to prevent distinguishing
		// padding failures from MAC failures. ...
		macAndPaddingGood := subtle.ConstantTimeCompare(localMAC, remoteMAC) & int(paddingGood)
		// MAC 比较与填充结果合并为一个判断，两类错误对外表现完全相同
		if macAndPaddingGood != 1 {
			return nil, 0, alertBadRecordMAC
			// 统一返回 bad_record_mac
		}

		plaintext = payload[:n]
	}

	hc.incSeq()
	// 只有校验成功才推进序列号
	return plaintext, typ, nil
}

// 文件：$GOROOT/src/crypto/tls/cipher_suites.go L447-472 (go1.27.1)
const (
	aeadNonceLength   = 12
	// GCM 标准 nonce 长度 96 bit
	noncePrefixLength = 4
	// 固定前缀 (salt) 长度，即 key block 中 GCM 套件的 ivLen
)

// prefixNonceAEAD wraps an AEAD and prefixes a fixed portion of the nonce to
// each call.
type prefixNonceAEAD struct {
	// nonce contains the fixed part of the nonce in the first four bytes.
	nonce [aeadNonceLength]byte
	// 前 4 字节存放 salt, 后 8 字节每次调用时填入显式 nonce
	aead  cipher.AEAD
}

func (f *prefixNonceAEAD) NonceSize() int        { return aeadNonceLength - noncePrefixLength }
// 对外宣称 nonce 是 8 字节 (只需要调用方提供显式部分)
func (f *prefixNonceAEAD) Overhead() int         { return f.aead.Overhead() }
// tag 长度 16
func (f *prefixNonceAEAD) explicitNonceLen() int { return f.NonceSize() }
// 显式 nonce 8 字节，会写入每条记录

func (f *prefixNonceAEAD) Seal(out, nonce, plaintext, additionalData []byte) []byte {
	copy(f.nonce[4:], nonce)
	// 拼出完整 12 字节 nonce = salt || explicit
	return f.aead.Seal(out, f.nonce[:], plaintext, additionalData)
}

func (f *prefixNonceAEAD) Open(out, nonce, ciphertext, additionalData []byte) ([]byte, error) {
	copy(f.nonce[4:], nonce)
	return f.aead.Open(out, f.nonce[:], ciphertext, additionalData)
}

// 文件：$GOROOT/src/crypto/tls/cipher_suites.go L509-531 (go1.27.1)
func aeadAESGCM(key, noncePrefix []byte) aead {
	if len(noncePrefix) != noncePrefixLength {
		panic("tls: internal error: wrong nonce length")
	}
	aes, err := aes.NewCipher(key)
	// AES-128 或 AES-256 分组密码
	if err != nil {
		panic(err)
	}
	var aead cipher.AEAD
	if boring.Enabled {
		aead, err = boring.NewGCMTLS(aes)
	} else {
		boring.Unreachable()
		aead, err = gcm.NewGCMForTLS12(aes.(*fipsaes.Block))
		// FIPS 模块中的 TLS 1.2 专用 GCM: 开启 FIPS 140-3 模式时会强制检查
		// nonce 前缀不变、计数器严格递增 (从 0 开始), 否则 panic
	}
	if err != nil {
		panic(err)
	}

	ret := &prefixNonceAEAD{aead: aead}
	copy(ret.nonce[:], noncePrefix)
	// 写入 4 字节 salt
	return ret
}

//go version 1.27.1
package main

import (
	"bytes"
	"crypto/aes"
	"crypto/cipher"
	"crypto/hmac"
	"crypto/rand"
	"crypto/sha1"
	"crypto/subtle"
	"encoding/binary"
	"encoding/hex"
	"errors"
	"fmt"
)

// tls12CBCSeal 模拟 TLS 1.2 AES-CBC + HMAC-SHA1 的 MAC-then-Encrypt 记录封装
func tls12CBCSeal(encKey, macKey []byte, seq uint64, typ byte, payload []byte) ([]byte, error) {
	// 1. 构造 MAC 输入：seq_num(8) || type(1) || version(2) || length(2) || plaintext
	var hdr [13]byte
	binary.BigEndian.PutUint64(hdr[:8], seq)                   // 隐式序列号，不上线路，双方各自维护
	hdr[8] = typ                                               // ContentType, 如 23 = application_data
	hdr[9], hdr[10] = 0x03, 0x03                               // ProtocolVersion = TLS 1.2
	binary.BigEndian.PutUint16(hdr[11:], uint16(len(payload))) // 明文长度
	mac := hmac.New(sha1.New, macKey)                          // HMAC-SHA1, 输出 20 字节
	mac.Write(hdr[:])                                          // 先喂 13 字节伪头部
	mac.Write(payload)                                         // 再喂明文
	tag := mac.Sum(nil)                                        // 得到 MAC

	// 2. 拼接 plaintext || MAC, 再按块大小补齐 padding
	block, err := aes.NewCipher(encKey) // 16 字节密钥 -> AES-128
	if err != nil {
		return nil, err
	}
	bs := block.BlockSize()                               // AES 块大小固定 16
	plain := append(append([]byte{}, payload...), tag...) // content || MAC
	padLen := bs - len(plain)%bs                          // 需要补的总字节数，范围 1..16
	for i := 0; i < padLen; i++ {
		plain = append(plain, byte(padLen-1)) // 每个填充字节的值都是 padLen-1
	}

	// 3. 每条记录随机生成显式 IV(TLS 1.1+), 放在密文前面
	iv := make([]byte, bs)
	if _, err := rand.Read(iv); err != nil { // IV 必须不可预测
		return nil, err
	}
	out := make([]byte, len(plain))
	cipher.NewCBCEncrypter(block, iv).CryptBlocks(out, plain) // CBC 加密
	return append(iv, out...), nil                            // 线路格式：IV || 密文
}

// tls12CBCOpen 是上面的逆过程：解密 -> 去填充 -> 校验 MAC
func tls12CBCOpen(encKey, macKey []byte, seq uint64, typ byte, record []byte) ([]byte, error) {
	block, err := aes.NewCipher(encKey)
	if err != nil {
		return nil, err
	}
	bs := block.BlockSize()
	if len(record) < bs+bs || len(record)%bs != 0 { // 至少 IV + 1 个块，且按块对齐
		return nil, errors.New("bad record length")
	}
	iv, ct := record[:bs], record[bs:] // 拆出显式 IV 与密文
	plain := make([]byte, len(ct))
	cipher.NewCBCDecrypter(block, iv).CryptBlocks(plain, ct) // CBC 解密

	padLen := int(plain[len(plain)-1]) + 1 // 最后一个字节 + 1 = 总填充长度
	if padLen+sha1.Size > len(plain) {
		return nil, errors.New("bad_record_mac") // 统一报 bad_record_mac, 不区分填充错还是 MAC 错
	}
	good := 1
	for _, b := range plain[len(plain)-padLen:] {
		good &= subtle.ConstantTimeByteEq(b, byte(padLen-1)) // 校验每个填充字节
	}
	body := plain[:len(plain)-padLen]                                      // 去填充
	payload, tag := body[:len(body)-sha1.Size], body[len(body)-sha1.Size:] // 分离明文与 MAC

	var hdr [13]byte
	binary.BigEndian.PutUint64(hdr[:8], seq) // 用接收方"期望"的序列号
	hdr[8], hdr[9], hdr[10] = typ, 0x03, 0x03
	binary.BigEndian.PutUint16(hdr[11:], uint16(len(payload)))
	mac := hmac.New(sha1.New, macKey)
	mac.Write(hdr[:])
	mac.Write(payload)
	good &= subtle.ConstantTimeCompare(mac.Sum(nil), tag) // 常数时间比较 MAC
	if good != 1 {                                        // 填充与 MAC 结果合并判断
		return nil, errors.New("bad_record_mac")
	}
	return payload, nil
}

// tls12GCMSeal 模拟 TLS 1.2 AES-GCM 记录封装 (RFC 5288)
func tls12GCMSeal(encKey, salt []byte, seq uint64, typ byte, payload []byte) ([]byte, error) {
	block, err := aes.NewCipher(encKey)
	if err != nil {
		return nil, err
	}
	aead, err := cipher.NewGCM(block) // 标准 12 字节 nonce, 16 字节 tag
	if err != nil {
		return nil, err
	}
	explicit := make([]byte, 8)
	binary.BigEndian.PutUint64(explicit, seq)               // 与 Go 实现一致：显式 nonce 直接用序列号
	nonce := append(append([]byte{}, salt...), explicit...) // 4 字节 salt(来自 key block 的 IV) + 8 字节显式部分

	var aad [13]byte // AAD = seq_num || type || version || length(明文长度)
	binary.BigEndian.PutUint64(aad[:8], seq)
	aad[8], aad[9], aad[10] = typ, 0x03, 0x03
	binary.BigEndian.PutUint16(aad[11:], uint16(len(payload)))

	ct := aead.Seal(nil, nonce, payload, aad[:]) // 返回 ciphertext || tag
	return append(explicit, ct...), nil          // 线路格式：explicit_nonce || ciphertext || tag
}

// tls12GCMOpen 是 GCM 记录的解封装：先认证，通过后才输出明文
func tls12GCMOpen(encKey, salt []byte, seq uint64, typ byte, record []byte) ([]byte, error) {
	block, err := aes.NewCipher(encKey)
	if err != nil {
		return nil, err
	}
	aead, err := cipher.NewGCM(block)
	if err != nil {
		return nil, err
	}
	if len(record) < 8+aead.Overhead() { // 至少要有显式 nonce 和 tag
		return nil, errors.New("bad_record_mac")
	}
	explicit, ct := record[:8], record[8:]                  // 拆出显式 nonce
	nonce := append(append([]byte{}, salt...), explicit...) // 还原完整 nonce
	var aad [13]byte
	binary.BigEndian.PutUint64(aad[:8], seq) // AAD 中用期望的 seq
	aad[8], aad[9], aad[10] = typ, 0x03, 0x03
	binary.BigEndian.PutUint16(aad[11:], uint16(len(ct)-aead.Overhead())) // 明文长度 = 密文长度 - tag
	return aead.Open(nil, nonce, ct, aad[:])                              // tag 不符直接返回错误
}

func main() {
	encKey := make([]byte, 16) // client_write_key, AES-128
	macKey := make([]byte, 20) // client_write_MAC_key, HMAC-SHA1
	salt := make([]byte, 4)    // client_write_IV, GCM 的 4 字节 salt
	rand.Read(encKey)
	rand.Read(macKey)
	rand.Read(salt)
	msg := []byte("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n") // 37 字节明文

	rec, _ := tls12CBCSeal(encKey, macKey, 0, 23, msg)
	fmt.Println("CBC record len:", len(rec), hex.EncodeToString(rec[:16]))
	pt, err := tls12CBCOpen(encKey, macKey, 0, 23, rec)
	fmt.Println("CBC open:", bytes.Equal(pt, msg), err)
	_, err = tls12CBCOpen(encKey, macKey, 1, 23, rec) // 接收方期望 seq=1, 模拟重放
	fmt.Println("CBC replay with seq=1:", err)

	grec, _ := tls12GCMSeal(encKey, salt, 0, 23, msg)
	fmt.Println("GCM record len:", len(grec))
	pt, err = tls12GCMOpen(encKey, salt, 0, 23, grec)
	fmt.Println("GCM open:", bytes.Equal(pt, msg), err)
	grec[len(grec)-1] ^= 1 // 翻转 tag 最后一位，模拟篡改
	_, err = tls12GCMOpen(encKey, salt, 0, 23, grec)
	fmt.Println("GCM tamper:", err)
}