Go tls.ClientHelloInfo SupportedVersions 怎样判断客户端支持的 TLS 版本

如果你在 Go 服务端回调里看到了 ClientHelloInfo.SupportedVersions，它表示的是客户端在 ClientHello 中声明支持的 TLS 版本，不是这次连接最终协商出的版本。真正的结果要等握手完成后读取 tls.ConnectionState.Version。

官方文档入口：https://pkg.go.dev/crypto/tls#ClientHelloInfo

这一区别很重要：服务端的 MinVersion、MaxVersion 会继续限制可选范围，客户端声明的版本集合只是输入。下面用一个回调示例把这三个概念拆开。

理解 SupportedVersions 的位置和含义

ClientHelloInfo 用于给 GetCertificate、GetConfigForClient 等回调提供 ClientHello 信息。SupportedVersions 是其中的客户端版本字段，读取时不需要从底层连接自行解析握手报文。

需要注意两个边界。第一，它描述的是客户端声明支持的版本；第二，Go 文档说明，对于低于 TLS 1.3 的版本，这个列表是根据客户端广告的最高版本推导出来的，低版本条目不一定都能直接作为可用结论。因此它适合做策略分流或记录线索，不适合单独当成最终协商证据。

在回调中读取并格式化版本列表

下面的代码把版本号映射成可读文本，并在 GetConfigForClient 中读取。示例不修改客户端的能力列表，只把它作为选择配置的输入。

package main

import (
    "crypto/tls"
    "fmt"
)

func tlsVersionName(version uint16) string {
    // 使用标准库常量映射版本，未知值保留十六进制便于排障。
    switch version {
    case tls.VersionTLS10:
        return "TLS 1.0"
    case tls.VersionTLS11:
        return "TLS 1.1"
    case tls.VersionTLS12:
        return "TLS 1.2"
    case tls.VersionTLS13:
        return "TLS 1.3"
    default:
        return fmt.Sprintf("unknown(0x%04x)", version)
    }
}

func readClientVersions(hello *tls.ClientHelloInfo) []string {
    // 复制成新的字符串切片，避免把回调输入误当成可修改的配置状态。
    names := make([]string, 0, len(hello.SupportedVersions))
    for _, version := range hello.SupportedVersions {
        names = append(names, tlsVersionName(version))
    }
    return names
}

func chooseConfig(base *tls.Config) *tls.Config {
    // 回调只读取客户端能力；最终能否协商仍由 TLS 握手规则决定。
    config := base.Clone()
    config.GetConfigForClient = func(hello *tls.ClientHelloInfo) (*tls.Config, error) {
        fmt.Printf("client versions: %v\n", readClientVersions(hello))
        return nil, nil // 返回 nil 表示继续使用当前配置。
    }
    return config
}

如果只是记录日志，建议记录版本名称和连接上下文，不要把 hello.Conn 当作普通连接去读写。官方说明明确禁止在这个回调阶段直接读写底层连接，否则可能破坏 TLS 握手。

区分客户端能力与服务端允许范围

判断“能不能用 TLS 1.3”时，至少要看两边：客户端是否声明支持，以及服务端配置是否允许。可以把它理解成两个集合的交集，而不是把 SupportedVersions 中的最大值直接当结果。

func serverConfig() *tls.Config {
    // 服务端策略单独表达，不能用客户端列表替代 MinVersion 和 MaxVersion。
    return &tls.Config{
        MinVersion: tls.VersionTLS12,
        MaxVersion: tls.VersionTLS13,
    }
}

func clientAdvertises(hello *tls.ClientHelloInfo, wanted uint16) bool {
    // 这里只判断 ClientHello 中是否出现目标版本，不代表握手一定会选它。
    for _, version := range hello.SupportedVersions {
        if version == wanted {
            return true
        }
    }
    return false
}

例如，客户端声明支持 TLS 1.2 和 TLS 1.3，而服务端只允许 TLS 1.2，那么最终不会因为列表里出现 TLS 1.3 就使用 TLS 1.3。相反，如果客户端没有声明服务端要求的最低版本，握手会因没有可用交集而失败；这时应该修正兼容性策略，而不是无条件降低服务端最低版本。

用 ConnectionState 确认最终协商结果

如果你的目标是记录真实协商版本，应在握手成功后读取连接状态。这个值反映双方能力和配置共同作用后的结果。

func reportNegotiatedVersion(conn *tls.Conn) error {
    // 先完成握手，再读取 ConnectionState，避免把未完成连接当成成功结果。
    if err := conn.Handshake(); err != nil {
        return fmt.Errorf("TLS 握手失败: %w", err)
    }
    state := conn.ConnectionState()
    fmt.Printf("negotiated TLS version: %s\n", tlsVersionName(state.Version))
    return nil
}

排障时可以同时记录两类信息：回调阶段的 SupportedVersions，以及握手完成后的 ConnectionState.Version。前者帮助解释客户端带来了什么输入，后者才是这次连接的实际结果。两者不一致并不矛盾，通常正是服务端范围限制或协商规则生效的表现。

常见问题

SupportedVersions 为空是不是客户端不支持 TLS？不能直接这样判断。应先确认回调阶段、Go 版本和具体 ClientHello，再结合握手错误判断；不要把空切片当作降低安全策略的理由。

SupportedVersions 的最大值就是最终版本吗？不是。它只是客户端声明的输入，服务端配置和握手协商仍会决定最终版本，最终结果看 ConnectionState.Version。

能不能在 GetConfigForClient 里直接改原配置的 MinVersion？不建议把共享配置当作每个连接的临时状态。需要按客户端选择策略时，应基于配置副本做明确的范围决策，并注意并发访问边界。

小结

记住三个层次即可：ClientHelloInfo.SupportedVersions 是客户端声明的能力输入，Config.MinVersion/MaxVersion 是服务端允许范围，ConnectionState.Version 是握手完成后的真实协商结果。排查版本兼容问题时把它们分开记录，才能避免把“客户端支持”误判成“连接已经使用”。