Go 1.27 的 TLS 连接证书怎么取：ConnectionState.LocalCertificate 不是对端证书

服务端排查 mTLS 失败时，常见的误判是把 tls.ConnectionState.PeerCertificates 当成本端证书链。Go 1.27 新增的 ConnectionState.LocalCertificate 正好补上了这个方向：它描述当前连接在握手中提供给对端的本地证书链，而 PeerCertificates 仍然描述对端发来的证书链。

Go 1.27 新字段解决的是哪一个方向的问题

tls.ConnectionState 是一次握手后的连接快照。以前，业务代码很容易拿到 PeerCertificates，却要通过配置对象或自建映射去猜“我到底向对端发了哪条证书链”。Go 1.27 增加 LocalCertificate 后，连接状态本身就能表达这个事实。

先记一个简单方向图：客户端或服务端各自都有本地证书；握手时，本地证书链发给对端，PeerCertificates 则是本端收到的对端证书链。字段名里的 Local 和 Peer 是相对当前连接对象而言，不是相对“服务端”或“客户端”的固定称呼。

LocalCertificate 和 PeerCertificates 怎么区分

可以把两个字段放到同一张审计表里理解。当前对象是客户端时，LocalCertificate 是客户端向服务端提供的证书链；当前对象是服务端时，它就是服务端提供给客户端的证书链。PeerCertificates 始终反过来。

因此，日志字段最好带上角色，例如 tls_local_leaf 和 tls_peer_leaf，不要只写一个含义模糊的 certificate。证书链为空也不能直接等同于握手失败：是否要求对端证书，取决于认证模式和当前连接角色。

握手完成后怎样读取本端证书

读取点应放在握手完成之后。客户端显式调用 HandshakeContext，服务端可以在握手返回成功后再取连接状态；不要在连接刚创建、尚未完成协商时把空状态当成最终结论。

func logTLSState(conn *tls.Conn) error {
    if err := conn.Handshake(); err != nil {
        return err
    }

    state := conn.ConnectionState()
    fmt.Printf("version=%s local=%d peer=%d\n",
        tls.VersionName(state.Version),
        len(state.LocalCertificate),
        len(state.PeerCertificates),
    )
    return nil
}

这里的 len 只用于观察链条是否存在，不能替代证书校验。若要记录主体名称，应继续读取链中的证书对象并按业务要求脱敏；不要把完整证书、私钥材料或连接凭据直接写入普通日志。

升级到 Go 1.27 前先查这三类代码

先查把 PeerCertificates 当本端证书的日志

搜索 PeerCertificates 的使用位置，看它是否被写入“本地证书”“服务端证书”之类的字段。如果代码要审计本端实际选中的证书，应改为读取 LocalCertificate；如果要审计对端身份，原字段才是正确方向。

再查证书链的读取时机

连接状态是握手结果的一部分。把读取动作放在握手失败分支前面，得到的只能是未完成状态。网络错误、证书验证错误和没有请求客户端证书，也应该在日志里区分开。

最后查单向 TLS 与 mTLS 的判断

单向 TLS 通常只验证服务端，客户端不一定提供证书；mTLS 才要求双方完成证书认证。迁移检查应同时看 ClientAuth、握手错误和证书链内容，不能用“两个切片都非空”作为所有场景的通用成功条件。

常见问题

LocalCertificate 是不是服务端证书？

不固定。它是当前 tls.Conn 这一端提供的证书链，客户端对象和服务端对象的含义不同。

PeerCertificates 为空就说明 TLS 不安全吗？

不能这样判断。单向 TLS、未要求客户端证书或握手尚未完成，都可能导致它为空；要结合认证模式和握手结果分析。

Go 1.26 能不能直接编译访问 LocalCertificate？

不能把 Go 1.27 新字段当成旧工具链 API 使用。需要兼容旧版本时，应通过版本分支、构建约束或保留旧的证书来源实现迁移，并在目标工具链上回归编译。

这次升级的关键不是多记一个字段，而是把“本端提供什么”和“对端提供什么”从日志语义上分开。先确认连接角色，再确认握手完成，最后按单向 TLS 或 mTLS 的认证模式解释证书链，排查结果才不会被方向性错误带偏。