Go 自定义证书链验证不通过怎么办

我在把内部 CA 接入 Go 服务时，最容易误判的一类错误就是“证书明明都在，为什么还是验证不通过”。后来把 VerifyOptions 拆成三个问题，排查会清楚很多：Roots 解决“信任谁”，Intermediates 解决“链怎么补齐”，KeyUsages 解决“这条链允许拿来做什么”。

这三个字段混在一起配置时，常见结果是把根证书放进中间池、漏传中间证书，或者因为 KeyUsages 的默认值误把客户端证书当成服务端证书。下面只围绕这三个边界说明。

先把三种证书角色分开

验证入口通常是叶子证书。Go 会尝试从它向上构建证书链，最后落到 Roots 中的信任锚；如果链中缺少中间证书，就从 Intermediates 里寻找。也就是说，两个池的职责不是“都放 CA 证书”这么简单。

旧写法为什么经常卡在 UnknownAuthorityError

最典型的旧写法是只创建一个池，然后把根证书和中间证书都塞进去。这样看起来“材料齐全”，但验证器仍需要知道哪张证书是信任锚。自定义 CA 场景最好明确建立两个池：

package main

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

// parseCertificate 只负责把一张 PEM 证书解析成 x509.Certificate。
func parseCertificate(data []byte) (*x509.Certificate, error) {
    block, _ := pem.Decode(data)
    if block == nil || block.Type != "CERTIFICATE" {
        return nil, errors.New("PEM 中没有 CERTIFICATE 块")
    }
    return x509.ParseCertificate(block.Bytes)
}

// buildPools 把根证书与中间证书放入各自的职责边界。
func buildPools(rootPEM, intermediatePEM []byte) (*x509.CertPool, *x509.CertPool, error) {
    roots := x509.NewCertPool()
    if !roots.AppendCertsFromPEM(rootPEM) {
        return nil, nil, errors.New("根证书加入 Roots 失败")
    }

    intermediates := x509.NewCertPool()
    if !intermediates.AppendCertsFromPEM(intermediatePEM) {
        return nil, nil, errors.New("中间证书加入 Intermediates 失败")
    }
    return roots, intermediates, nil
}

func verifyLeaf(leaf *x509.Certificate, roots, intermediates *x509.CertPool) error {
    // ServerAuth 只允许面向服务端身份的用途约束。
    opts := x509.VerifyOptions{
        Roots:         roots,
        Intermediates: intermediates,
        KeyUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
    }
    _, err := leaf.Verify(opts)
    return err
}

func main() { fmt.Println("示例函数需要由调用方提供 PEM 和叶子证书") }

这里的关键不是函数名，而是池的语义：自签名根或企业信任根进入 Roots；签发叶子证书的中间 CA 进入 Intermediates。如果错误是 UnknownAuthorityError，先检查根是否真的追加成功，再检查中间证书是否缺失或不属于这条链。

新规则：Roots 决定信任锚，不是“所有 CA 的集合”

Roots 为 nil 时，Go 可能使用系统根证书或平台验证器。这个默认行为适合验证公共 CA，但在内部 CA、测试 CA 或租户隔离场景里容易产生错觉：机器上能验证，不代表容器或另一台机器也能验证。

自定义信任边界应该显式传入 Roots。反过来，不要把“为了让它通过”理解成把整个系统根池复制进自定义池。自定义池越明确，部署差异越容易解释，也更容易避免意外信任不该信任的 CA。

另一个容易忽略的点是：根证书不是“链路中任意一张 CA 证书”。只有作为信任锚参与验证时，它才属于 Roots；中间 CA 即使也带有 CA 能力，只要它不是最终信任锚，就应放进 Intermediates。

Intermediates 只补链，不提升信任级别

中间证书池的作用是帮助验证器找到从叶子到根的路径。把中间证书放进去，并不会让它自动变成可信根；真正的信任终点仍由 Roots 决定。

因此，看到“服务端发来了证书，但客户端仍然报未知颁发者”时，可以按下面顺序看：

1. 客户端的 Roots 是否包含签发链最终依赖的根证书。
2. 叶子证书的签发者对应的中间 CA 是否进入 Intermediates。
3. 中间 CA 是否能继续连接到 Roots 中的根，而不是只存在一张孤立证书。

在服务端把完整链发给客户端是一种常见部署方式，但客户端自己的自定义验证代码仍然要把收到的中间证书按职责放入 Intermediates。不要因为证书文件名叫 ca.pem 就直接判断它应该进哪个池。

KeyUsages 的默认值会改变你的预期

KeyUsages 为空时，并不是“不限制用途”，而是按 ExtKeyUsageServerAuth 处理。这个默认值对 HTTPS 客户端很合理，但如果你验证的是客户端证书、代码签名或其他用途，空切片可能直接造成用途不匹配。

// 根据验证对象选择用途，不用空切片表达“任意用途”。
func verifyForPurpose(leaf *x509.Certificate, roots, intermediates *x509.CertPool, purpose x509.ExtKeyUsage) error {
    opts := x509.VerifyOptions{
        Roots:         roots,
        Intermediates: intermediates,
        KeyUsages:     []x509.ExtKeyUsage{purpose},
    }
    _, err := leaf.Verify(opts)
    return err
}

// 服务端证书使用 ServerAuth；双向 TLS 的客户端证书使用 ClientAuth。
// 只有确实不关心用途时才使用 ExtKeyUsageAny，并保留更细的业务授权判断。
func purposeForTLS(isClientCertificate bool) x509.ExtKeyUsage {
    if isClientCertificate {
        return x509.ExtKeyUsageClientAuth
    }
    return x509.ExtKeyUsageServerAuth
}

如果日志落到 x509.IncompatibleUsage，就不要继续替换根证书。先对照叶子、间接签发者和 KeyUsages 的用途约束，确认它们是否允许当前目的。扩展密钥用途是沿证书链一起约束的，中间证书或根证书列出的限制也可能影响叶子证书。

一份更容易复用的 VerifyOptions 配置

我现在会把验证配置集中在一个构造函数里，让调用方必须明确传入信任根、补链材料和用途：

// makeVerifyOptions 集中保存三类配置，便于日志和代码评审逐项对照。
func makeVerifyOptions(roots, intermediates *x509.CertPool, usage x509.ExtKeyUsage) x509.VerifyOptions {
    return x509.VerifyOptions{
        Roots:         roots,         // 明确信任锚，避免依赖机器环境。
        Intermediates: intermediates, // 只放补链证书，不把它当根。
        KeyUsages:     []x509.ExtKeyUsage{usage}, // 明确验证目的。
    }
}

// verifyWithOptions 只负责执行验证，把错误交给上层按类型处理。
func verifyWithOptions(leaf *x509.Certificate, opts x509.VerifyOptions) ([][]*x509.Certificate, error) {
    chains, err := leaf.Verify(opts)
    if err != nil {
        // 不在这里吞掉错误，调用方才能区分信任链和用途问题。
        return nil, err
    }
    return chains, nil
}

兼容边界：别用 ExtKeyUsageAny 掩盖链路问题

ExtKeyUsageAny 可以表达“用途不作为这次验证的限制”，但它不能修复缺失根证书、断开的中间链，也不能替代业务层的授权判断。把它作为排障临时开关后，应该恢复到实际用途，否则“验证通过”只代表链能连上，不代表证书适合当前身份。

同样，Roots 为空和 Intermediates 为空表达的是两种不同语义：前者可能退回系统根，后者表示没有额外补链材料。不要用把所有证书都塞进一个池的方式消除这种差异。

最后按这个清单收口

• 自定义 CA 是否明确进入 Roots，而不是只放在中间池。
• 叶子到根之间的每张中间证书是否加入 Intermediates。
• KeyUsages 是否显式表达服务端、客户端或其他用途。
• UnknownAuthorityError 优先查信任锚和补链，IncompatibleUsage 优先查用途约束。
• 只有确实不关心用途时才使用 ExtKeyUsageAny，并在业务层继续做身份授权。

相关问题：为什么自签名根证书放进 Intermediates 仍然失败？为什么同一套证书在本机通过、容器里失败？KeyUsages 为空是不是代表不限制？mTLS 中服务端和客户端证书应该分别使用什么用途？