Go crypto/x509 怎样区分证书过期和主机名错误

在 Go 的 crypto/x509 中，证书过期和主机名错误都可能表现为“证书校验失败”，但它们对应的修复动作完全不同：前者要检查证书链上的有效期，后者要检查请求主机名是否出现在证书的 SAN 中。不要只比较错误字符串，应该用 errors.As 识别结构化错误。

如果要做完整的信任链校验，优先调用 Certificate.Verify，在 VerifyOptions 中设置 DNSName，再把错误分成 x509.CertificateInvalidError 和 x509.HostnameError。其中 CertificateInvalidError.Reason == x509.Expired 表示证书尚未生效或已经过期。

本文只讨论标准库 crypto/x509 的 API 边界。示例中的证书对象来自已经解析好的 DER/PEM 数据，代码重点放在校验选型和错误分流，不把示例输出冒充成某个真实站点的运行结果。

三种检查方式怎么选

先把三个经常混在一起的入口分开。Certificate.Verify 会尝试从叶子证书构建到根证书的链，并可结合 VerifyOptions.DNSName 检查名称；VerifyHostname 只回答“这个证书是否适用于这个主机名”；直接读取 NotBefore 和 NotAfter 只是在查看时间字段，不能替代信任链验证。

这里还有一个容易忽略的边界：如果 VerifyOptions.Roots 留空，某些平台可能使用系统验证器，错误细节可能与纯 Go 验证路径不同。需要稳定、可控的错误分类时，应明确传入根证书池，并把平台差异作为调用方的兼容策略。

用 VerifyOptions 触发完整校验

完整校验至少要明确两件事：信任根从哪里来，以及本次连接要访问哪个主机名。下面的函数接收一个已经解析好的叶子证书、根池和中间证书池，返回可供上层处理的错误。KeyUsages 也显式设置为服务端认证，避免把默认用途误读成业务规则。

package certcheck

import (
    "crypto/x509"
)

// verifyServerCertificate 同时检查证书链、有效期和服务端主机名。
func verifyServerCertificate(leaf *x509.Certificate, roots, intermediates *x509.CertPool, host string) error {
    opts := x509.VerifyOptions{
        Roots:         roots,                         // 明确指定信任根，便于稳定分类错误
        Intermediates: intermediates,                 // 提供不在系统根池中的中间证书
        DNSName:       host,                          // 把连接目标交给 x509 做 SAN 匹配
        KeyUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}, // 约束服务端用途
    }

    _, err := leaf.Verify(opts)
    return err
}

当返回 nil 时，表示当前选项下至少找到一条可用证书链。返回非空错误时，先按具体类型识别，再决定是让证书团队续期、修复服务端证书，还是修正连接使用的主机名。

用 errors.As 区分过期和主机名错误

CertificateInvalidError 携带 Reason，其中 Expired 覆盖“当前时间早于 NotBefore”和“当前时间晚于 NotAfter”两种情况；HostnameError 携带证书和请求主机名。它们都是结构化信息，适合使用 errors.As，而不是依赖会变化的错误字符串。

package certcheck

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

// classifyVerifyError 把 x509 错误转换为稳定的业务分类。
func classifyVerifyError(err error) string {
    if err == nil {
        return "ok"
    }

    var invalid x509.CertificateInvalidError
    if errors.As(err, &invalid) {
        // Expired 同时覆盖尚未生效和已经过期，不能只检查 NotAfter。
        if invalid.Reason == x509.Expired {
            return fmt.Sprintf("certificate-time-invalid: %s", invalid.Detail)
        }
        // 其他链路原因仍保留 Reason，方便记录和后续处理。
        return fmt.Sprintf("certificate-invalid: reason=%v detail=%s", invalid.Reason, invalid.Detail)
    }

    var hostname x509.HostnameError
    if errors.As(err, &hostname) {
        // HostnameError.Host 是本次被校验的主机名，而不是证书的 Common Name。
        return fmt.Sprintf("hostname-mismatch: host=%s", hostname.Host)
    }

    // 系统根不可用、解析错误等不属于这两类，保留原始错误给上层。
    return fmt.Sprintf("other-x509-error: %v", err)
}

这个分支顺序的意义是先处理完整链路里的证书有效性错误，再处理名称错误。对于名称不匹配，标准库当前按证书的 SAN 进行匹配；旧式 Common Name 不应被当作通用的主机名授权来源。日志中可以同时记录 hostname.Host、证书序列号或摘要等非敏感标识，但不要把私钥、完整令牌或不必要的证书内容写入日志。

只做局部检查时要接受它的边界

如果调用方已经完成证书链校验，只想检查一个备用域名，可以调用 VerifyHostname。这会返回 HostnameError，但它不会告诉你根证书是否受信，也不会替你判断证书是否已经过期。

package certcheck

import (
    "crypto/x509"
    "errors"
)

// checkOnlyHostname 只检查 SAN/主机名关系，不把结果当作完整 TLS 信任结论。
func checkOnlyHostname(cert *x509.Certificate, host string) (bool, error) {
    err := cert.VerifyHostname(host)
    if err == nil {
        return true, nil
    }

    var mismatch x509.HostnameError
    if errors.As(err, &mismatch) {
        // 保留结构化错误，调用方可以展示 host 或执行备用域名策略。
        return false, mismatch
    }
    return false, err
}

相反，如果只是做证书到期提醒，可以比较时间字段，但应明确它是信息展示而不是信任判断：

package certcheck

import (
    "crypto/x509"
    "time"
)

// certificateTimeState 只读取证书声明的有效期，不能代替 Verify。
func certificateTimeState(cert *x509.Certificate, now time.Time) string {
    if now.Before(cert.NotBefore) {
        return "not-yet-valid"
    }
    if now.After(cert.NotAfter) {
        return "expired"
    }
    return "currently-within-validity"
}

常见误区和决策表

• 不要用 strings.Contains(err.Error(), "expired") 作为长期接口；错误文案是给人看的，结构体字段才适合分类。
• 不要把 HostnameError 当成“证书不可信”；它说明授权名称与请求名称不匹配，根信任问题要看其他错误类型。
• 不要只检查叶子证书的 NotAfter；中间证书或根证书也可能在验证链时触发 Expired。
• Verify 不做吊销检查。需要吊销状态时，仍要按系统的 OCSP/CRL 策略单独设计。
• 证书解析失败、系统根不可用和算法不支持等错误，应保留原始错误，不要强行归为过期或主机名错误。

相关问题

Verify 设置 DNSName 后还需要再调用 VerifyHostname 吗？

通常不需要。Verify 在 VerifyOptions.DNSName 非空时会执行主机名检查；再次调用只会重复同一类局部检查。只有在已经完成链路验证后，确实要对另一个候选名称做单独判断时，才适合调用 VerifyHostname。

为什么错误信息里有 expired，但我判断的是主机名？

一次完整校验可能同时存在多个问题，标准库会按当前验证路径先返回其中一个错误。应先处理返回的结构化类型；如果证书时间有效，再继续修正主机名或重新校验，而不是把一条错误字符串拆成多个结论。

HostnameError 能说明证书来自不可信 CA 吗？

不能。它只描述授权名称与请求名称不匹配。CA 信任、链路构建和名称匹配是不同维度，应该根据具体错误类型分别记录。

应该把完整证书内容写入日志方便排查吗？

不建议。记录错误类型、主机名、证书序列号或指纹等必要标识即可；私钥、敏感扩展和不必要的完整证书内容不应进入普通业务日志。

把“完整信任校验”和“局部信息检查”分开，再用 errors.As 识别 Expired 与 HostnameError，就能让证书续期、主机名修正和其他链路故障进入不同处理路径。