Go 报错 x509: certificate relies on legacy Common Name field:原因、修复命令与排查清单
错误长什么样,为什么会出现
在 Go 1.15 及之后的所有版本里,只要服务端证书没有 SAN(subjectAltName)扩展、只把域名写在 CN(Common Name)字段里,客户端握手就会直接失败,典型输出:
Get "https://a.internal/health": x509: certificate relies on legacy Common Name field, use SANs instead
调用栈通常停在 crypto/tls 的 handshake,再往上是 crypto/x509 的 VerifyHostname。这句话的含义非常明确:证书里一个可用的 SAN 都没有,Go 拒绝回退到 CN 做主机名校验。
时间线值得记住:
- Go 1.15:默认不再用 CN 兜底,但保留
GODEBUG=x509ignoreCN=0临时开关。 - Go 1.17:该开关被彻底移除,没有回退路径。
- 同期 Chrome、Firefox、curl(OpenSSL 1.1.1+)、Java 8u181+、Node.js 17+ 也都完成了同样的强制迁移。
这类证书几乎全部来自两个地方:内部工具/脚本批量生成的老自签证书,以及早年手工用 openssl req -x509 不带扩展参数签出来的服务证书。问题不在 Go,在证书本身。
三分钟定位:证书到底缺了什么
先确认现场,不要凭猜测重签。拿到证书文件后执行:
# OpenSSL 1.1.1+ 推荐写法
openssl x509 -in a.crt -noout -ext subjectAltName
# 兼容老版本
openssl x509 -in a.crt -noout -text | grep -A1 "Subject Alternative Name"
三种可能的结果:
- 报错
No extensions in certificate或干脆没有输出:证书完全没有 SAN,这就是本文要修的场景。 - 有 SAN,但不包含你访问用的名字:那是另一个错误(见下文
certificate is valid for ...)。 - 有 SAN 且包含目标域名:问题出在信任链或时间,不在 CN。
顺手看一眼 CN 和有效期,方便判断是不是同一批老证书:
openssl x509 -in a.crt -noout -subject -issuer -dates
如果是线上服务,直接对着端口抓真实证书,避免拿到的是旧文件:
openssl s_client -connect a.internal:443 -servername a.internal </dev/null 2>/dev/null
| openssl x509 -noout -subject -ext subjectAltName
内部工具与自签证书:用 OpenSSL 重签
原文给出的 openssl req -new ... -addext "subjectAltName=DNS:a.internal" 只生成了 CSR,本身并不会产生可用证书,必须再签一步。完整可复制的流程如下。
场景 A:直接生成自签服务证书
openssl req -x509 -newkey rsa:2048 -nodes -days 365
-keyout a.key -out a.crt
-subj "/CN=a.internal"
-addext "subjectAltName=DNS:a.internal,DNS:localhost,IP:127.0.0.1"
-addext "keyUsage=digitalSignature,keyEncipherment"
-addext "extendedKeyUsage=serverAuth"
要点:CN 保留域名只是为了可读性和兼容老旧工具,真正生效的是 SAN。所有会被访问到的名字都必须出现在 SAN 里——用 127.0.0.1 访问就要写 IP:127.0.0.1,用 localhost 访问就要写 DNS:localhost。
场景 B:CSR + 自有 CA 签发
# 1. 生成带 SAN 的 CSR
openssl req -new -newkey rsa:2048 -nodes
-keyout a.key -out a.csr
-subj "/CN=a.internal"
-addext "subjectAltName=DNS:a.internal,DNS:localhost,IP:127.0.0.1"
# 2. 签发前先确认 CSR 里真的带了 SAN
openssl req -in a.csr -noout -text | grep -A1 "Subject Alternative Name"
# 3. 用 CA 签发(OpenSSL 3.x,自动复制 CSR 扩展)
openssl x509 -req -in a.csr -CA ca.crt -CAkey ca.key -CAcreateserial
-out a.crt -days 365 -copy_extensions copy
# 4. OpenSSL 1.1.1 没有 -copy_extensions,改用 extfile
openssl x509 -req -in a.csr -CA ca.crt -CAkey ca.key -CAcreateserial
-out a.crt -days 365
-extfile <(printf "subjectAltName=DNS:a.internal,DNS:localhost,IP:127.0.0.1nkeyUsage=digitalSignature,keyEnciphermentnextendedKeyUsage=serverAuthn")
最常见的坑就在这里:CSR 里的 SAN 不会自动进入最终证书,签发时必须显式复制或重新指定,否则重签一圈回来依旧报同一个错。
场景 C:OpenSSL 低于 1.1.1(不支持 -addext)
cat > san.cnf <<'EOF'
[req]
distinguished_name = dn
req_extensions = v3_req
prompt = no
[dn]
CN = a.internal
[v3_req]
subjectAltName = @alt_names
[alt_names]
DNS.1 = a.internal
DNS.2 = localhost
IP.1 = 127.0.0.1
EOF
openssl req -new -newkey rsa:2048 -nodes -keyout a.key -out a.csr -config san.cnf
签完必须验证
openssl verify -CAfile ca.crt a.crt
openssl x509 -in a.crt -noout -checkhost a.internal
openssl x509 -in a.crt -noout -ext subjectAltName
-checkhost 返回 a.internal: OK 才算真正修好,别只看文件生成成功。
生产证书:向 CA 重签,而不是自己打补丁
公网或对外服务的证书不要手工改扩展,正确做法是重新走 CA 流程:
- 现代 CA(Let’s Encrypt、DigiCert、Sectigo 等)默认就会把申请域名写入 SAN,并在证书里保留 CN 作为展示字段。
- 重签时把所有会被访问的域名一次性写全:主域名、
www、内部别名、负载均衡域名。漏一个就会出现certificate is valid for ...。 - 用 IP 直连的入口,必须申请带 IP SAN 的证书,普通域名证书不覆盖 IP。
- ACME 签发(certbot / lego / acme.sh)默认已包含 SAN,无需额外参数;但
--expand之类选项要确认新证书真的包含了新增域名。
拿到新证书后,先在本地验证再上线:
openssl s_client -connect a.internal:443 -servername a.internal -CAfile ca.crt </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
各运行时对 CN 与 SAN 的处理对照表
| 运行时 / 版本 | 只有 CN,无 SAN | CN 与 SAN 都有 | 只有 SAN,无 CN |
|---|---|---|---|
| Go 1.14 及更早 | 通过 | 通过 | 通过 |
| Go 1.15 – 1.16 | 失败(可临时 GODEBUG=x509ignoreCN=0) |
通过 | 通过 |
| Go 1.17 及以上 | 失败,无开关 | 通过 | 通过 |
| Chrome / Edge / Safari | 失败(ERR_CERT_COMMON_NAME_INVALID) |
通过 | 通过 |
| Firefox | 失败(SSL_ERROR_BAD_CERT_DOMAIN) |
通过 | 通过 |
| curl + OpenSSL 1.1.1+ | 失败 | 通过 | 通过 |
| Java 8u181+ / 11+ | 失败 | 通过 | 通过 |
| Node.js 17+ | 失败 | 通过 | 通过 |
结论很直接:CN 已经退化为纯展示字段,SAN 是唯一具备校验语义的位置。为兼容旧工具,最佳实践是「CN 写主域名 + SAN 写全部域名」,两者保持一致。
常见报错与排查
1. x509: certificate relies on legacy Common Name field, use SANs instead
证书没有 SAN。按上文重签,或确认重签后的文件真的被服务进程加载(很多故障是换了证书没重启,或 tls.crt 指向旧路径)。
2. x509: certificate is valid for a.internal, not b.internal
SAN 存在但不含目标名。检查代码里的 ServerName、URL 主机名与证书 SAN 是否逐字一致;注意 *.internal 只匹配一级子域,a.b.internal 不匹配。
3. x509: cannot validate certificate for 10.0.0.5 because it doesn't contain any IP SANs
用 IP 访问但证书只有 DNS SAN。要么改用域名访问,要么重签时加 -addext "subjectAltName=IP:10.0.0.5"。
4. x509: certificate signed by unknown authority
私有 CA 未被信任。把 CA 加入 x509.NewCertPool() 并赋给 tls.Config.RootCAs,或设置环境变量 SSL_CERT_FILE=/etc/ssl/certs/internal-ca.crt,或把 CA 装进系统信任库后执行 update-ca-certificates。
5. tls: failed to verify certificate: x509: certificate has expired or is not yet valid
时间问题,不是 SAN 问题。核对 NotBefore/NotAfter 与容器、CI 机器的系统时钟(时钟漂移在容器里很常见)。
6. x509: certificate specifies an incompatible key usage
证书缺少 extendedKeyUsage=serverAuth,多见于内部 CA 只写了 clientAuth。重签时补上 -addext "extendedKeyUsage=serverAuth"。
7. remote error: tls: bad certificate
这是对端(通常是 mTLS 场景的客户端)拒绝了你的证书,排查方向同上,但要检查对端的信任库与客户端证书的 SAN/用途,而不是本机代码。
Go 代码侧验证与过渡手段
不要靠业务请求去试错,写一个十行的探针程序最快:
pool := x509.NewCertPool()
if ok := pool.AppendCertsFromPEM(caPEM); !ok {
log.Fatal("CA 证书解析失败")
}
conn, err := tls.Dial("tcp", "a.internal:443", &tls.Config{
RootCAs: pool,
ServerName: "a.internal",
MinVersion: tls.VersionTLS12,
})
if err != nil {
log.Fatalf("握手失败: %v", err)
}
defer conn.Close()
for _, c := range conn.ConnectionState().PeerCertificates {
log.Printf("Subject=%s DNSNames=%v IPAddresses=%v NotAfter=%s",
c.Subject, c.DNSNames, c.IPAddresses, c.NotAfter.Format(time.RFC3339))
}
如果 DNSNames 打印为空切片,就百分百确认是 CN-only 证书。
关于过渡方案:
GODEBUG=x509ignoreCN=0只在 Go 1.15 / 1.16 有效,1.17 起已移除,不要把它写进部署脚本。InsecureSkipVerify: true能消掉报错,但同时关闭主机名校验与链校验,等于放弃 TLS 的核心价值,只能用于一次性本地调试。- 如果确实需要自定义校验(例如固定公钥指纹),用
VerifyPeerCertificate显式实现,而不是关掉校验。
上线前检查清单
- ☐
openssl x509 -ext subjectAltName有输出,且包含全部访问用域名与 IP。 - ☐ CN 与主 SAN 一致(便于人工排查)。
- ☐
openssl verify -CAfile ca.crt a.crt返回 OK。 - ☐
openssl x509 -checkhost <host>全部返回 OK。 - ☐ 证书含
extendedKeyUsage=serverAuth。 - ☐ 服务进程已重启并加载新证书(
openssl s_client抓到的指纹与文件一致)。 - ☐ 客户端已配置
RootCAs或系统信任库。 - ☐ 证书有效期与自动续期已接入监控。
FAQ
Q1:我把 CN 改成域名了,为什么 Go 还是报同样的错?
因为 Go 1.15+ 根本不读取 CN 做主机名校验,只看 SAN。改 CN 无效,必须新增 SAN 扩展。
Q2:GODEBUG=x509ignoreCN=0 还能救急吗?
仅在 Go 1.15 和 1.16 存在,Go 1.17 起已删除。即使能用也只是把故障推迟,证书换新是唯一正解。
Q3:可以只写 SAN、完全不要 CN 吗?
技术上完全可以,现代 CA 签发的证书也常常 CN 为空。保留 CN 只是为了兼容某些老旧的展示型工具和便于人工阅读。
Q4:为什么我用 CSR 重新签了,还是没 SAN?
CSR 中的扩展默认不会进入最终证书。签发时需 -copy_extensions copy(OpenSSL 3.x)或 -extfile 显式指定。
Q5:用 IP 访问内网服务怎么办?
必须申请或签发带 IP:10.0.0.5 形式 IP SAN 的证书;域名证书不覆盖 IP,代码里改 ServerName 也没用。
Q6:通配符证书能覆盖多级子域吗?
不能。*.internal 只匹配 a.internal,不匹配 a.b.internal,也不匹配裸域 internal,后者需要单独加入 SAN。
Q7:换了证书 Go 服务还报旧错?
多半是进程未重启、连接池复用旧连接,或配置里证书路径指向旧文件。用 openssl s_client 抓线上实际证书指纹比对。
Q8:内网自建 CA 怎么让 Go 信任?
三种方式:代码里 RootCAs 加载 CA;环境变量 SSL_CERT_FILE 指向 CA 文件;把 CA 安装到系统信任库。容器镜像里要确保 CA 文件随镜像一起分发。