Go TLS 证书 IP 地址校验失败时如何读 SAN

我排查 Go TLS 连接时最容易先看错的地方，就是把“证书里写了这个 IP”理解成 CommonName 写过它。对 Go 的 crypto/x509 来说，输入被解析成 IP 后，只会拿它和证书的 IPAddresses SAN 比较；DNS 名称则看 DNSNames，传统 CommonName 不再承担主机名匹配。因此，先把 SAN 读出来，通常比反复改客户端参数更快。

先确认校验输入确实是 IP

VerifyHostname 会先判断传入值能否解析为 IP。IPv4、IPv6（也可写成方括号形式）走 IPAddresses；普通域名走 DNSNames。所以报错里出现“doesn't contain any IP SANs”，说明程序正在按 IP 查，而证书没有可用的 IP SAN，并不是 Go 没有读到 CommonName。

如果调用的是 Certificate.Verify，则检查 x509.VerifyOptions.DNSName。这个字段虽然名字叫 DNSName，但它也可以承载用于主机名校验的 IP 输入；最终仍遵守 IP 与 IP SAN 比较的规则。

读取证书里的 IP SAN，而不是猜 CommonName

下面的最小程序从 PEM 文件解析叶子证书，同时打印三组容易混淆的字段。它只做诊断，不关闭证书校验。

package main

import (
    "crypto/x509"
    "encoding/pem"
    "fmt"
    "os"
)

func main() {
    pemBytes, err := os.ReadFile("server.crt")
    if err != nil {
        panic(err) // 读取失败先修正文件来源，不要把空数据交给解析器
    }
    block, _ := pem.Decode(pemBytes)
    if block == nil {
        panic("没有找到 PEM 证书块") // PEM 格式错误时明确停止诊断
    }
    cert, err := x509.ParseCertificate(block.Bytes)
    if err != nil {
        panic(err) // DER 解析失败通常意味着拿到的不是证书主体
    }
    fmt.Println("IP SAN:", cert.IPAddresses)       // IP 校验只看这里
    fmt.Println("DNS SAN:", cert.DNSNames)          // 域名校验看这里
    fmt.Println("CommonName:", cert.Subject.CommonName) // 仅展示历史字段
}

输出时重点看两件事：IP SAN 是否为空，以及列表中是否存在与连接目标等价的 net.IP。即使 CommonName 看起来完全正确，只要 IP SAN 没有该地址，按 IP 校验仍会失败。

用 VerifyHostname 把失败原因分成两类

拿到证书后，可以用同一个校验入口复现问题。示例把错误类型打印出来，便于区分“缺少 IP SAN”和“有 IP SAN 但没有匹配项”。

package main

import (
    "crypto/x509"
    "errors"
    "fmt"
    "net"
)

func check(cert *x509.Certificate, host string) {
    err := cert.VerifyHostname(host)
    if err == nil {
        fmt.Println("匹配成功") // 只有成功才继续使用该主机名建立信任链
        return
    }
    var hostnameErr x509.HostnameError
    if errors.As(err, &hostnameErr) {
        if net.ParseIP(host) != nil && len(cert.IPAddresses) == 0 {
            fmt.Println("失败：证书没有 IP SAN") // 先补证书字段
            return
        }
        fmt.Println("失败：IP 或 DNS 名称与 SAN 不匹配") // 对照列表修正输入
        return
    }
    fmt.Println("其他证书错误：", err) // 不把链验证错误误判成 SAN 错误
}

这段判断的边界很重要：空的 IPAddresses 是“证书没有 IP SAN”，非空却失败则是值不相等、格式不一致或校验目标选错。IPv6 还要注意规范化表示，以及连接层是否带了方括号或区域信息。

修复证书或修正输入，再做一次复查

如果目标是固定 IP 访问，重新签发证书时把该地址放入 Subject Alternative Name 的 IP 项，而不是只填 Common Name。若证书只覆盖域名，就让客户端使用证书中的 DNS 名称，并把它作为 TLS 的服务名；不要为了绕过报错而把 InsecureSkipVerify 打开。

最后重新运行上面的读取程序：IP SAN 应包含目标地址；再调用 VerifyHostname，成功返回 nil 才说明名称匹配完成。名称匹配通过后，仍要让 Certificate.Verify 使用正确的根证书池和用途，SAN 正确不等于整条信任链一定正确。

常见疑问

为什么 CommonName 写了 IP 仍然失败？

因为 Go 的主机名校验把 legacy Common Name 视为旧字段，IP 只与 IPAddresses SAN 比较。

证书里有域名 SAN，能替代 IP SAN 吗？

不能。域名和 IP 属于两条匹配路径；除非连接与校验都改成证书覆盖的域名，否则仍需要对应的 IP SAN。

排查这类错误时，我的顺序是“看输入类型、读 SAN、复现 VerifyHostname、再决定签证书还是改目标名”。四步都围绕可见字段展开，通常能避免在客户端参数和证书文本之间来回猜测。