Go tls.Config VerifyConnection 的握手校验观测与返回策略

线上 TLS 问题常常只剩一句“握手失败”，但真正需要知道的是：服务名是什么、协商出了哪个版本和 ALPN、对端证书链是否存在、这次连接是不是会话恢复。tls.Config.VerifyConnection适合做这层统一观测：它在正常证书校验和 VerifyPeerCertificate 之后执行，返回非 nil 错误才会中止握手。默认校验没有失败时，回调可以只记录状态，不必为了拿诊断信息关闭安全校验。

官方地址：https://pkg.go.dev/crypto/tls#Config.VerifyConnection

实战中先把 VerifyConnection 当作“握手结果出口”，保留默认校验；只有确实要替代默认验证时，才配合 x509.Verify 和明确的 ClientAuth 策略。这样既能覆盖会话恢复，又不会把 InsecureSkipVerify 误当成排障开关。

先把回调顺序和安全边界分开

客户端默认会校验证书链和主机名，服务端则由 ClientAuth 决定客户端证书策略。VerifyConnection随后拿到完整的 tls.ConnectionState。如果回调返回错误，握手失败；如果只是打印信息，连接仍按原有校验结果继续。

用 ConnectionState 记录一次可定位的握手结果

下面的回调只做观测：把协商结果和证书摘要写入结构化日志，避免输出完整证书和敏感握手材料。DidResume可帮助解释“第一次失败、重连却成功”这类现象；恢复连接也会触发 VerifyConnection。

package main

import (
    "crypto/tls"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
)

func observeTLS(cs tls.ConnectionState) error {
    // 只记录证书指纹，避免把完整证书内容写进业务日志。
    leaf := ""
    if len(cs.PeerCertificates) > 0 {
        sum := sha256.Sum256(cs.PeerCertificates[0].Raw)
        leaf = hex.EncodeToString(sum[:8])
    }

    // VerifiedChains 反映默认校验是否建立了可用的验证链。
    fmt.Printf("tls server=%s version=%d alpn=%s resumed=%t leaf=%s chains=%d\n",
        cs.ServerName, cs.Version, cs.NegotiatedProtocol, cs.DidResume,
        leaf, len(cs.VerifiedChains))
    return nil // 观测成功不改变原有 TLS 校验结论。
}

需要替代默认校验时，必须把验证链补完整

例如测试环境使用私有 CA，不能只把 InsecureSkipVerify 设为 true 就结束。回调里至少要明确 DNSName、根证书池、中间证书和用途。客户端示例保留了关键错误处理；生产代码还应从受控配置加载根证书，不要把空池当作信任所有证书。

package main

import (
    "crypto/tls"
    "crypto/x509"
    "fmt"
)

func verifyPrivateCA(cs tls.ConnectionState, roots *x509.CertPool) error {
    // 没有对端证书时先返回可定位错误，避免访问下标 0 造成 panic。
    if len(cs.PeerCertificates) == 0 {
        return fmt.Errorf("tls peer certificate is missing")
    }

    intermediates := x509.NewCertPool()
    for _, cert := range cs.PeerCertificates[1:] {
        // 叶子证书单独交给 Verify，其余证书作为中间链。
        intermediates.AddCert(cert)
    }
    _, err := cs.PeerCertificates[0].Verify(x509.VerifyOptions{
        DNSName:       cs.ServerName, // 保留主机名校验。
        Roots:         roots,         // 只信任明确配置的私有根。
        Intermediates: intermediates,
    })
    if err != nil {
        return fmt.Errorf("verify tls peer %q: %w", cs.ServerName, err)
    }
    return nil // 自定义验证通过后才允许握手继续。
}

服务端同理：如果使用 RequireAnyClientCert 来接管客户端证书验证，就必须确认确实要求客户端证书，再访问 PeerCertificates[0]。证书没有由默认验证器处理时，VerifiedChains 可能为空，这是预期状态，不等于回调没有运行。

恢复连接、日志和错误返回的排查清单

1. 先记录 DidResume，确认问题是否只发生在新握手或只发生在会话恢复。
2. 再看 ServerName、NegotiatedProtocol 和证书指纹，避免把 ALPN 或 SNI 问题误判成证书过期。
3. 默认校验失败时不要期待回调“修复”它；需要替代校验就把根、用途、主机名和中间链都写入代码路径。
4. 日志只保留摘要和错误，不输出私钥、完整证书链或可用于解密流量的材料。

常见问题

VerifyPeerCertificate 和 VerifyConnection 怎么选？前者更接近原始证书字节和默认验证链，且恢复连接时不会调用；需要覆盖所有连接、包括恢复连接的统一检查和观测时优先考虑 VerifyConnection。

VerifyConnection 返回 nil 就代表证书一定可信了吗？不一定。若关闭了默认验证，可信性完全取决于回调内是否正确执行了 x509.Verify 以及信任根、主机名和用途是否正确。