跳到主要内容

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 文件随镜像一起分发。