Go crypto/x509单独判断主机名匹配的验证步骤

如果手里已经有一个 *x509.Certificate，只是想判断它是否适用于某个 DNS 名称或 IP 地址，最小做法是调用 cert.VerifyHostname(host)：返回 nil 表示名称匹配，返回错误表示不匹配。这个方法只处理“证书上的授权名称”和“目标主机名”的关系，不会替代根证书、有效期或扩展用途检查。

官方地址：https://pkg.go.dev/crypto/x509

Go crypto/x509 单独判断主机名时应先分清验证范围

VerifyHostname 的输入是已经解析好的证书和一个主机名字符串。它返回 nil 时，只能得出“名称匹配”这个结论；证书是否由受信任的根签发、是否过期、是否允许服务器认证，仍然属于另一层验证。

名称类型也不能混用：像 api.example.com 这样的输入会按 DNS 名称比较；IPv4、IPv6 以及可选方括号形式会按 IPAddresses 检查。证书中的通配符必须是完整的最左侧标签，例如 *.example.com，不能把它当成任意字符串匹配。当前文档还明确说明，遗留 Common Name 字段会被忽略。

用 VerifyHostname 建立最小判断函数

实际项目通常先从 PEM 中取出叶子证书，再把连接目标传入同一个判断函数。下面的代码把解析错误和名称不匹配分开返回，便于上层决定是丢弃证书、记录诊断信息，还是进入完整链验证。

package certcheck

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

func matchHost(certPEM []byte, host string) (bool, error) {
    // 先取出证书块，避免把私钥或其他 PEM 数据送入解析器。
    block, _ := pem.Decode(certPEM)
    if block == nil || block.Type != "CERTIFICATE" {
        return false, fmt.Errorf("无有效的 CERTIFICATE PEM 块")
    }

    // ParseCertificate 只负责把 DER 内容变成可查询的证书对象。
    cert, err := x509.ParseCertificate(block.Bytes)
    if err != nil {
        return false, fmt.Errorf("解析证书失败: %w", err)
    }

    // VerifyHostname 返回 nil 才表示目标名称命中了证书授权名称。
    if err := cert.VerifyHostname(host); err != nil {
        var nameErr x509.HostnameError
        // 名称不匹配属于可识别的业务结果，保留原错误供上层记录。
        if errors.As(err, &nameErr) {
            return false, fmt.Errorf("主机名 %q 不匹配: %w", host, err)
        }
        return false, err
    }
    return true, nil
}

这个函数没有创建 CertPool，也没有检查证书链，因为它的职责就是回答“这张已解析证书是否声明了这个主机名”。如果调用方拿到的是 URL 主机部分，建议先去掉端口，再把规范化后的主机名传入；不要把 host:port 整体当作证书名称。

从 HostnameError 找到不匹配原因

匹配失败时，优先把错误识别为 x509.HostnameError，再对照证书里的名称列表。它至少能告诉你请求的 Host 和证书对象，适合把“客户端传错目标”和“证书漏配名称”分开记录。不要看到错误就直接改成跳过校验；先确认目标究竟是 DNS 名称还是 IP 地址。

因此，日志中最好同时保留目标主机、错误类型和证书的 SAN 摘要，而不是只保存一条“证书错误”。这样能看出是服务发现传入了错误别名，还是签发时没有把新域名放入 SAN。

需要信任链时改用 Certificate.Verify

如果需求是“这张证书能否作为 TLS 服务端证书被接受”，单独调用 VerifyHostname 就不够。此时准备根证书池和中间证书，并把目标主机名放入 VerifyOptions.DNSName：

opts := x509.VerifyOptions{
    Roots:         roots,
    Intermediates: intermediates,
    DNSName:       host, // 让完整验证同时检查目标主机名
}

chains, err := cert.Verify(opts)
if err != nil {
    // 这里的错误可能来自信任链、有效期、用途或名称检查。
    return fmt.Errorf("证书完整验证失败: %w", err)
}
fmt.Printf("验证链数量: %d\n", len(chains))

两种调用的边界可以这样记：调试证书 SAN 或复用已经完成链验证的证书时，选 VerifyHostname；建立 TLS 信任结论时，选 Verify 并提供合适的 VerifyOptions。不要为了让测试通过而把主机名检查删除。

常见问题

VerifyHostname 会检查证书是否过期吗？

不会。它回答的是名称匹配问题；有效期、签发者和用途等条件要放到完整证书验证中。

证书只有 Common Name 为什么仍然匹配失败？

因为当前 crypto/x509 文档明确说明遗留 Common Name 会被忽略，应让签发端把名称放到 Subject Alternative Name。

域名证书能直接拿来匹配 IP 吗？

不能按 DNS 名称的思路处理。IP 目标应出现在证书的 IPAddresses 字段，匹配时也传入 IP 地址。

最后可以按“类型—字段—范围”复查：DNS 看 DNSNames，IP 看 IPAddresses，只做名称判断用 VerifyHostname，需要信任链则用 Verify。这四项分清后，大多数主机名匹配问题都能在错误类型和证书 SAN 之间快速定位。