Go x509.Certificate.VerifyHostname 为什么不检查旧版 Common Name

我第一次遇到这个报错时，证书的 Subject.CommonName 明明写着服务域名，VerifyHostname 却仍然返回 x509: certificate relies on legacy Common Name field, use SANs instead。这不是 Go 把证书读错了，而是主机名校验的入口已经换成了 Subject Alternative Name（SAN）。域名看 DNSNames，IP 地址看 IPAddresses，旧版 Common Name 不能再当作主机名授权依据。

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

先把 VerifyHostname 的匹配边界看清

VerifyHostname 只负责“这张证书是否覆盖这个主机名”。传入域名时，Go 会在证书的 DNSNames 中做不区分大小写的匹配；传入 IP 时，则只检查 IPAddresses。合法 DNS 名称可以使用完整的左侧通配符，例如 *.example.com，但通配符不能替代任意层级。

Subject.CommonName 仍然是证书对象里的字段，也可能在旧证书里保存着域名，但它不再是这个 API 的主机名授权来源。把 CN 填得再准确，也不能替代 SAN。

从错误信息判断证书是不是只有 Common Name

排查时先把证书字段打印成摘要，别只盯着浏览器或服务端显示的 CN。下面的代码只展示字段读取和错误分类，真正的证书仍应来自经过信任链校验的连接流程。

func checkHost(cert *x509.Certificate, host string) error {
	// 先查看 SAN，避免把旧版 Common Name 当成可用名称。
	fmt.Printf("dns_sans=%v ip_sans=%v common_name=%q\n",
		cert.DNSNames, cert.IPAddresses, cert.Subject.CommonName)

	// VerifyHostname 只判断主机名与 SAN 的匹配关系。
	if err := cert.VerifyHostname(host); err != nil {
		var hostnameErr x509.HostnameError
		if errors.As(err, &hostnameErr) {
			return fmt.Errorf("hostname mismatch for %q: %w", host, err)
		}
		return err
	}
	return nil
}

如果证书没有 SAN，但 CN 恰好与传入域名相同，错误信息会提示它依赖 legacy Common Name。这个提示的重点不是“CN 拼错”，而是证书的名称表达方式过时。若传入的是 IP，错误通常会指出证书没有对应的 IP SAN。

把证书签发配置迁移到 SAN

迁移时要改的是证书模板或签发工具的 SAN 输入。服务域名放进 DNSNames，固定地址放进 IPAddresses；内部别名、负载均衡地址和实际客户端传入的名称都要按使用场景列出。不要只改 CSR 的 Common Name 后重新签发，因为最终证书仍可能没有 SAN。

Go 代码生成证书时，字段关系大致如下：

template := &x509.Certificate{
	// DNSNames 承载客户端传入的域名匹配项。
	DNSNames: []string{"api.example.com", "api.internal.example.com"},
	// IPAddresses 只承载 IP 形式的访问地址。
	IPAddresses: []net.IP{net.ParseIP("10.0.0.8")},
	// Subject.CommonName 不是 VerifyHostname 的替代字段。
	Subject: pkix.Name{CommonName: "legacy-label"},
}

生产发布前检查解析后的证书字段，而不是只检查配置文件。对每个实际访问名建立一行清单：访问值、类型（域名或 IP）、预期 SAN、证书轮换时间。这样能在切换前发现“服务名改了、证书却只覆盖旧别名”的问题。

在 Go 客户端保留正确的复查动作

主机名匹配和证书链校验是两个相邻但不同的判断。调用 cert.VerifyHostname 只说明名称是否覆盖；完整 TLS 客户端还需要让标准验证流程检查根证书、中间证书、有效期和用途。使用 x509.VerifyOptions 时，DNSName 会参与叶子证书的名称校验。

Go 1.15 曾允许通过 GODEBUG=x509ignoreCN=0 临时恢复旧行为，Go 1.16 发布说明又明确该开关将在 Go 1.17 移除。它最多只能作为短期升级缓冲，不能成为新证书的配置方案。更不要用 InsecureSkipVerify 掩盖名称错误：那会把本应暴露的身份校验缺口变成客户端默认行为。

复查清单可以保持很短：确认客户端实际传入的 host；确认域名在 DNSNames、IP 在 IPAddresses；确认证书链由目标根集合信任；最后再按错误类型决定是换证书、补中间证书还是修正调用地址。

相关问题

Common Name 和 DNS SAN 都写了域名，Go 会优先看谁？

主机名校验看 SAN。只要 SAN 存在，CN 不会成为额外的匹配来源；应把需要支持的域名完整列到 DNS SAN。

能不能把 IP 地址写进 DNSNames？

不要这样设计。IP 形式的目标应写进 IPAddresses，域名才写进 DNSNames。客户端传入类型不同，匹配字段也不同。

VerifyHostname 成功就代表 TLS 完全安全吗？

不是。它只完成名称匹配；根证书信任、有效期、用途和撤销策略仍由完整证书验证与部署策略负责。

所以，这个问题的修复方向很明确：把旧证书里的 Common Name 迁移为正确的 SAN，按域名和 IP 分别填写，再让 Go 的名称校验与证书链校验各自完成本职工作。只要不把 CN、SAN 和信任链混成一个概念，排查结果通常很快就能落到具体的证书字段。