Go TLS 最低版本与密码套件迁移清单

Go 服务迁移 TLS 策略时，最稳妥的起点是：最低版本先以 TLS 1.2 为基线，密码套件优先使用 crypto/tls 的安全默认值，只有合规或明确互操作要求才显式配置 CipherSuites。还要特别注意，CipherSuites 只控制 TLS 1.0–1.2，TLS 1.3 的密码套件不能通过这个字段配置。

我见过最容易出问题的迁移，并不是代码写错，而是把一次安全调整当成单机配置修改：开发环境里的浏览器都能连，于是直接把生产服务改成 TLS 1.3 only；上线后，旧代理、设备 SDK 或合作方任务才开始握手失败。真正需要设计的是“服务端安全策略与调用方兼容性之间的契约”。

官方文档：https://pkg.go.dev/crypto/tls

先把三个配置决策拆开

tls.Config 中与这次迁移最相关的配置看似集中，实际控制的是不同边界：

• MinVersion：允许协商的最低 TLS 版本。当前官方文档说明默认最低版本为 TLS 1.2。
• MaxVersion：允许协商的最高版本。通常保持零值，让 Go 使用当前支持的最高版本。
• CipherSuites：只控制 TLS 1.0–1.2 的可用套件，列表顺序会被忽略。
• TLS 1.3 密码套件：由 crypto/tls 管理，应用不能通过 CipherSuites 改写。
• PreferServerCipherSuites：已经是无效果的遗留字段，不应继续作为迁移开关。

这几个字段的职责分开后，迁移方案也会清楚很多：先决定“最低允许哪个协议版本”，再决定“是否真的需要覆盖 TLS 1.2 默认套件”，而不是复制一份网上的长列表后一起上线。

接口目标：把安全基线写成可解释的契约

我更愿意把 TLS 配置看成服务接口的一部分。调用方需要知道的不是内部有多少常量，而是三件事：

1. 服务至少要求 TLS 1.2 还是 TLS 1.3；
2. TLS 1.2 客户端是否还需要满足额外的密码套件政策；
3. 策略升级失败时，谁根据什么指标决定暂停或回退。

如果没有外部合规要求，我通常不会固定 CipherSuites。Go 的默认套件会随安全实践更新；手写固定列表意味着团队以后必须自行跟踪删除、弃用和兼容性变化。官方也明确提醒：默认套件可能随时间变化。

迁移前先盘点真实客户端

不能只按浏览器版本或操作系统名称猜兼容性。真实链路中还可能存在负载均衡、反向代理、API 网关、硬件设备、Java 或 OpenSSL SDK，以及合作方托管任务。至少要在迁移前建立以下基线：

如果 TLS 在网关处终止，Go 应用看到的可能只是网关到后端的连接。此时还要从网关或负载均衡层获取外部握手数据，不能仅凭应用进程里的 ConnectionState 判断公网客户端兼容性。

最低版本怎么设置

对大多数公开服务，TLS 1.2 是兼顾现代安全基线与兼容性的常见选择。即使当前 Go 默认值已经是 TLS 1.2，在需要稳定配置契约、跨 Go 版本保持一致或通过配置审计时，也可以显式设置。

package transport

import "crypto/tls"

func ServerTLSConfig() *tls.Config {
    return &tls.Config{
        // 显式声明最低版本，便于审计并固定服务契约
        MinVersion: tls.VersionTLS12,

        // MaxVersion 保持零值，让 Go 使用当前实现支持的最高版本
        MaxVersion: 0,

        // nil 表示采用 crypto/tls 的安全默认套件
        CipherSuites: nil,
    }
}

如果所有调用方都已验证支持 TLS 1.3，可以把 MinVersion 提升为 tls.VersionTLS13。但这不是“数值越大越好”的简单升级：它会直接拒绝所有只支持 TLS 1.2 的客户端，而且无法通过给 CipherSuites 增加条目来补救。

什么时候才显式配置 CipherSuites

适合显式配置的场景通常只有两类：一是合规政策明确列出允许的 TLS 1.2 套件；二是与某个已验证的旧系统进行受控互操作。除此之外，保持 nil 往往更稳。

package transport

import "crypto/tls"

func PolicyTLSConfig() *tls.Config {
    return &tls.Config{
        MinVersion: tls.VersionTLS12,

        // 仅在政策明确要求时限制 TLS 1.2 套件；不会影响 TLS 1.3
        CipherSuites: []uint16{
            tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
            tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
            tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
            tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
            tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
            tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
        },
    }
}

上面的列表只是一个现代 TLS 1.2 示例，不是适用于所有组织的通用合规清单。RSA 与 ECDSA 套件能否实际协商，还与服务端证书、客户端能力和其他握手参数有关。迁移前应基于自己的证书类型和客户端盘点结果调整。

不要把 tls.CipherSuites() 的返回值整体复制到配置中。该函数返回当前实现的安全套件并按 ID 排序，但文档明确说明：它不代表默认启用列表，也无法表达 Go 的动态优先级逻辑。tls.InsecureCipherSuites() 返回的是有已知安全问题的套件，大多数应用不应启用。

TLS 1.3 为什么不接受自定义套件列表

TLS 1.3 的密码套件与 TLS 1.2 是分离的集合，职责也更简单。Go 官方选择不向应用暴露 TLS 1.3 套件配置，避免开发者用静态列表覆盖运行时基于安全性和硬件能力做出的选择。

因此迁移代码中出现下面的期待时，需要及时纠正：

• 把 TLS 1.3 套件常量放进 CipherSuites；
• 通过调整 CipherSuites 顺序控制服务端优先级；
• 继续设置 PreferServerCipherSuites 期望改变协商结果。

这些做法都不能建立可靠策略。真正应该控制的是最低协议版本、证书与密钥、客户端兼容性，以及必要时对 TLS 1.2 套件做最小范围限制。

用协商结果决定是否继续推进

服务端可以在连接进入活动状态后读取 tls.ConnectionState，记录协议版本和密码套件。下面示例只展示观测结构，生产环境应接入指标系统并控制日志基数。

package server

import (
    "crypto/tls"
    "log"
    "net"
    "net/http"
)

func NewServer(handler http.Handler, cfg *tls.Config) *http.Server {
    return &http.Server{
        Addr:      ":8443",
        Handler:   handler,
        TLSConfig: cfg,
        ConnState: func(conn net.Conn, state http.ConnState) {
            // 握手完成并进入可处理请求状态后再读取协商结果
            if state != http.StateActive {
                return
            }
            tlsConn, ok := conn.(*tls.Conn)
            if !ok {
                return
            }

            cs := tlsConn.ConnectionState()
            log.Printf("tls_version=%s cipher_suite=%s",
                tls.VersionName(cs.Version),
                tls.CipherSuiteName(cs.CipherSuite),
            )
        },
    }
}

仅记录成功连接还不够。协议版本不兼容通常发生在握手阶段，应用层可能拿不到 HTTP 请求。要同时采集服务入口或代理层的握手错误，并区分证书验证、协议版本、无共同套件、SNI 和网络超时等原因。

分阶段发布，而不是一次切断

我更习惯把迁移拆成四个发布动作，每个动作都有进入条件和退出条件：

1. 只观测：保持现状，记录至少一个完整业务周期的版本、套件和失败分布。
2. 先改调用方：升级仍使用旧协议或旧 TLS 栈的内部客户端，确认合作方升级计划。
3. 小流量收紧：在单个入口、单个地域或小比例实例上提升 MinVersion，保持证书与其他变量不变。
4. 逐步扩大：只有握手失败率、关键客户成功率和业务错误率都在阈值内，才扩大范围。

回退策略也要预先写清：回退的是 MinVersion，还是 TLS 1.2 的显式套件列表；由哪个指标触发；配置回退需要多长时间传播。不要同时更换证书、域名、代理链和 TLS 策略，否则失败时很难判断根因。

不要把 GODEBUG 当成长久兼容层

Go 曾为 TLS 默认值变化提供过 tls10server、tls3des、tlsrsakex 等兼容开关，但这类 GODEBUG 设置都有明确生命周期，可能在后续版本删除。它们适合短期诊断或争取迁移时间，不适合作为长期安全策略。

更稳的做法是：在 tls.Config 中表达长期契约，升级客户端，移除对旧协议或旧套件的依赖，并让 Go 版本升级成为常规安全维护的一部分。

迁移清单

• 确认 TLS 在 Go 服务、反向代理还是负载均衡处终止。
• 记录成功握手的 Version 与 CipherSuite，并单独统计握手失败。
• 列出关键内部客户端、合作方、设备和定时任务的 TLS 能力。
• 先以 TLS 1.2 为最低基线；提升到 TLS 1.3 前完成全量兼容确认。
• 默认保持 CipherSuites: nil；显式列表必须有合规或互操作理由。
• 不要尝试配置 TLS 1.3 密码套件，也不要依赖列表顺序。
• 灰度期间只改变一个变量，并预先定义失败率和关键客户回退阈值。
• 把临时 GODEBUG 开关登记移除日期，不让它成为无人维护的永久配置。
• 升级 Go 版本后重新核对官方 crypto/tls 文档和发布说明。

常见问题

MinVersion 留零值还是显式写 TLS 1.2？

希望跟随 Go 的安全默认值时可以留零值；需要稳定审计契约、跨版本保持一致或配置中心明确展示策略时，可以显式写 tls.VersionTLS12。两种选择都要记录理由。

把 CipherSuites 留空是否等于允许所有套件？

不是。nil 表示使用 crypto/tls 的安全默认列表，该列表可能随 Go 版本变化。它不等于启用 InsecureCipherSuites() 中的所有旧套件。

只允许 TLS 1.3 后，还需要配置 CipherSuites 吗？

不需要，也无法通过该字段配置 TLS 1.3 套件。此时更应关注客户端是否支持 TLS 1.3、证书验证、支持组和握手失败指标。

为什么本地测试正常，生产仍有握手失败？

本地通常只覆盖现代浏览器或开发机 TLS 栈，生产还存在旧 SDK、设备、代理和合作方任务。必须以真实入口的握手数据为准，并确认 TLS 实际终止在哪一层。

这次迁移真正要避免的，不是某一个常量选错，而是把安全配置当成孤立代码。版本基线、TLS 1.2 套件、TLS 1.3 内建策略、客户端兼容性和回退指标共同构成一个接口决策；拆开记录、逐步发布，才有机会同时获得更好的安全性与可控的兼容性。