Go TLS 握手失败怎样区分证书和协议版本

Go TLS 握手失败时，先看错误链里有没有证书校验线索，再看双方允许的协议版本范围。证书问题通常会出现主机名不匹配、未知签发者、过期或客户端证书不满足要求；协议版本问题则更常见于 protocol version not supported、tls: no supported versions satisfy MinVersion and MaxVersion 一类信息。不要先设置 InsecureSkipVerify 让错误消失，那会把身份校验问题隐藏起来。

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

最稳妥的顺序是：显式执行握手并设置超时，保存原始错误；先用 errors.As 判断证书验证类型，再核对 MinVersion、MaxVersion 和最终的 ConnectionState.Version。

先把 TLS 握手从业务读写中单独拿出来

tls.Dial 或第一次读写都可能隐式触发握手。排查时把它显式化，可以知道失败发生在建立安全连接这一步，而不是把 TLS 错误和 HTTP 请求解析、业务超时混在一起。HandshakeContext 还可以为握手单独设置取消和超时边界。

func dialTLS(ctx context.Context, network, address, serverName string) (*tls.Conn, error) {
    d := &net.Dialer{Timeout: 5 * time.Second}
    raw, err := d.DialContext(ctx, network, address)
    if err != nil {
        // TCP 都没有建立时，不要把问题误判成证书或 TLS 版本错误。
        return nil, fmt.Errorf("tcp dial: %w", err)
    }

    cfg := &tls.Config{
        ServerName: serverName,       // 用真实主机名参与证书名称校验。
        MinVersion: tls.VersionTLS12, // 保持明确的最低协议版本边界。
    }
    conn := tls.Client(raw, cfg)
    if err := conn.HandshakeContext(ctx); err != nil {
        // 握手失败时关闭底层连接，避免排查代码留下半开连接。
        _ = conn.Close()
        return nil, fmt.Errorf("tls handshake: %w", err)
    }
    return conn, nil
}

这里没有主动设置 MaxVersion，表示使用当前 Go 实现支持的最高版本；如果业务为了兼容旧设备而设置了上限，必须把该值和对端支持范围一起记录。握手成功后再进入 HTTP 或自定义协议层，日志也更容易按阶段聚合。

根据错误链判断证书校验失败

证书类失败的重点不是错误字符串中是否包含 certificate，而是沿错误链找到结构化类型。Go 的 tls.CertificateVerificationError 表示握手阶段的证书验证失败，可以继续查看它包装的 Err。如果底层是 x509.HostnameError，优先检查 ServerName 和证书 SAN；如果是 x509.UnknownAuthorityError，检查客户端信任根或服务端证书链。

func classifyCertificateError(err error) string {
    var verifyErr *tls.CertificateVerificationError
    if errors.As(err, &verifyErr) {
        // 先确认是证书验证阶段失败，再分析其底层 x509 错误。
        var hostErr x509.HostnameError
        if errors.As(verifyErr.Err, &hostErr) {
            return "certificate-hostname-mismatch"
        }
        var authorityErr x509.UnknownAuthorityError
        if errors.As(verifyErr.Err, &authorityErr) {
            return "certificate-unknown-authority"
        }
        return "certificate-verification"
    }
    return "not-certificate-verification"
}

双向 TLS 还要检查服务端是否要求客户端证书，以及客户端发送的证书是否由对端信任。证书过期、用途不符合、链不完整等问题也属于身份材料或验证策略问题，不应通过关闭校验解决。排查日志可记录证书主题、SAN、有效期和错误类别，但不要记录私钥或完整敏感凭据。

用版本范围和 ConnectionState 判断协议协商

协议版本问题的判断依据是双方允许范围没有交集。客户端的 MinVersion 太高而服务端只支持 TLS 1.0/1.1，或者客户端把 MaxVersion 限制在较低版本而服务端策略只接受更高版本，都可能在证书真正验证前失败。这类错误通常不会生成可用的 ConnectionState，所以不能只等连接成功后再看状态。

func reportTLSState(conn *tls.Conn) error {
    state := conn.ConnectionState()
    if !state.HandshakeComplete {
        // 未完成握手时，Version 等状态字段不能作为有效诊断证据。
        return errors.New("tls handshake is incomplete")
    }
    log.Printf("tls version=%s cipher=%s server_name=%s",
        tlsVersionName(state.Version),
        tls.CipherSuiteName(state.CipherSuite),
        state.ServerName) // 记录协商结果，不记录密钥材料。
    return nil
}

func tlsVersionName(v uint16) string {
    switch v {
    case tls.VersionTLS12:
        return "TLS1.2"
    case tls.VersionTLS13:
        return "TLS1.3"
    default:
        return fmt.Sprintf("0x%04x", v) // 未知值保留十六进制，避免误报。
    }
}

可以先用一个明确的安全基线测试，例如只设置 MinVersion: tls.VersionTLS12，不要同时改动证书根、密码套件、代理和重试策略。若降到 TLS 1.2 后成功，说明版本兼容性值得继续查；若仍然在证书验证阶段失败，方向就不应停留在协议版本。

用最小化配置矩阵完成生产排查

生产环境可以保留同一个目标地址，做两组可审计的对照：第一组使用正式信任根和目标主机名，只改变 MinVersion；第二组固定版本范围，只替换经过批准的信任根。每次只改一个变量，并把 Go 版本、目标地址、ServerName、版本范围、证书错误类型和握手耗时放入诊断记录。

若测试必须临时使用 InsecureSkipVerify 来确认“网络和版本能否协商”，应把它限定在隔离诊断代码中，并明确标记为不安全实验；它只能说明证书验证被绕过后是否继续，不代表生产配置可用。修复完成后，要恢复证书校验，再用真实 CA 和主机名重做握手。

1. 先确认 TCP 可达，再用 HandshakeContext 单独执行 TLS 握手。
2. 用 errors.As 沿错误链判断证书验证类型和底层 x509 原因。
3. 没有证书结构化错误时，核对 MinVersion、MaxVersion 与对端支持范围。
4. 只有握手成功后，才使用 ConnectionState.Version 记录最终协商结果。
5. 每次只改变一个配置变量，修复后恢复完整证书校验并复测。

常见问题

把 MinVersion 调低后握手成功，是否说明证书没问题？

只能说明版本范围可能是阻塞点。仍应在安全版本基线下重新握手，确认主机名、信任链和有效期都通过。

为什么失败时拿不到 ConnectionState.Version？

该状态只在握手完成后才有意义。协议版本或证书校验在握手中途失败时，应以错误链和配置记录为证据。

服务端证书正常，为什么 Go 仍然报证书错误？

常见原因是连接使用的 ServerName 与证书 SAN 不匹配，或客户端运行环境缺少签发该证书的信任根。