用 VerifyOptions 区分服务器与客户端证书用途

在 Go 里手工调用 Certificate.Verify 时，服务器证书和客户端证书必须使用不同的扩展密钥用途。验证 HTTPS 服务端证书应传 x509.ExtKeyUsageServerAuth；验证 mTLS 客户端证书应传 x509.ExtKeyUsageClientAuth。不要让客户端证书验证继续依赖空的 KeyUsages，因为官方定义中空列表默认就是服务器认证用途。

Go crypto/x509 官方文档：https://pkg.go.dev/crypto/x509

最小区别只有一行：

// 验证服务器证书：空列表虽然也默认 ServerAuth，但显式写出更容易审查。
serverOpts := x509.VerifyOptions{
    KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
}

// 验证客户端证书：必须明确指定 ClientAuth，不能继续依赖默认值。
clientOpts := x509.VerifyOptions{
    KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageClientAuth},
}

哪些旧写法需要迁移

需要迁移的不是某个 Go 版本语法，而是证书验证策略。常见旧代码把所有证书都交给同一个空 VerifyOptions，或者为了“兼容”直接使用 ExtKeyUsageAny。这两种写法都会模糊证书角色。

Go 官方文档还明确说明：KeyUsages 中列出多个值时，只要证书链允许其中任意一个用途，链就可能被接受。因此把 ServerAuth 和 ClientAuth 同时放入列表，不等于要求证书同时具备两种用途，反而会放宽验证条件。

把两种证书用途写成两个入口

下面的写法把共享的证书池放入小型配置结构，再公开两个语义明确的验证函数。调用方不再传裸的用途常量，也就更难把客户端证书误当成服务端证书。

package certcheck

import "crypto/x509"

// Verifier 保存两类验证共用的信任根与中间证书。
type Verifier struct {
    Roots         *x509.CertPool
    Intermediates *x509.CertPool
}

// VerifyServerCertificate 验证服务端证书链和目标主机名。
func (v Verifier) VerifyServerCertificate(
    leaf *x509.Certificate,
    dnsName string,
) ([][]*x509.Certificate, error) {
    return leaf.Verify(x509.VerifyOptions{
        Roots:         v.Roots,
        Intermediates: v.Intermediates,
        DNSName:       dnsName,
        KeyUsages: []x509.ExtKeyUsage{
            x509.ExtKeyUsageServerAuth,
        },
    })
}

// VerifyClientCertificate 只验证客户端认证用途；业务身份授权另行处理。
func (v Verifier) VerifyClientCertificate(
    leaf *x509.Certificate,
) ([][]*x509.Certificate, error) {
    return leaf.Verify(x509.VerifyOptions{
        Roots:         v.Roots,
        Intermediates: v.Intermediates,
        KeyUsages: []x509.ExtKeyUsage{
            x509.ExtKeyUsageClientAuth,
        },
    })
}

服务端验证函数接收 dnsName，因为连接服务端时通常还要确认 SAN 是否覆盖目标主机。客户端证书用于 mTLS 身份声明时，通常没有“访问哪个主机”的问题，所以这里不设置 DNSName。但不设置主机名不等于完成授权：客户端证书中的 SAN、Subject、URI 或自定义扩展仍需由业务层映射为账户、设备或服务身份。

用途约束不只看叶子证书

Verify 会先构建候选证书链，再检查扩展密钥用途。Go 的官方实现会沿证书链应用用途约束；如果中间 CA 或根 CA 明确限制了可签发用途，叶子证书即使写着 ClientAuth，也可能无法作为客户端证书通过验证。

用途不兼容时，常见错误是 x509: certificate specifies an incompatible key usage。这和 unknown authority 不同：前者说明可能已经构建出候选链，但用途筛选没有留下可接受的链；后者更偏向于信任锚或中间证书链不完整。

不要用 ExtKeyUsageAny 代替角色判断

ExtKeyUsageAny 的含义不是“自动识别服务器或客户端”，而是接受任意扩展密钥用途。它适合证书清单工具、通用检查器等确实只关心链有效性的场景，不适合网络连接认证。

// inspectChain 只检查证书链能否建立，故意不限定业务用途。
// 生产认证流程不要复用这个函数，否则会失去服务器与客户端角色约束。
func (v Verifier) inspectChain(
    leaf *x509.Certificate,
) ([][]*x509.Certificate, error) {
    return leaf.Verify(x509.VerifyOptions{
        Roots:         v.Roots,
        Intermediates: v.Intermediates,
        KeyUsages: []x509.ExtKeyUsage{
            x509.ExtKeyUsageAny,
        },
    })
}

如果业务真的允许一张证书承担两种角色，也不要在验证侧简单传入两个用途就结束。先确认 PKI 签发策略允许双用途，再分别在服务端场景和客户端场景调用对应函数，才能保持调用语义清楚。

用表驱动测试锁住迁移结果

迁移后至少准备三种叶子证书夹具：仅 ServerAuth、仅 ClientAuth、同时包含两种用途。测试目标不是验证证书生成代码，而是确认调用入口不会接受错误角色。

package certcheck

import (
    "crypto/x509"
    "testing"
)

// TestVerifyCertificateRole 确认两种入口只接受匹配用途。
func TestVerifyCertificateRole(t *testing.T) {
    // 测试夹具应由同一测试 CA 签发，并分别限制为服务器或客户端用途。
    verifier, serverOnly, clientOnly := loadRoleFixtures(t)

    tests := []struct {
        name    string
        verify  func() error
        wantErr bool
    }{
        {
            name: "服务器入口接受 ServerAuth",
            verify: func() error {
                _, err := verifier.VerifyServerCertificate(serverOnly, "api.example.test")
                return err
            },
        },
        {
            name: "客户端入口拒绝 ServerAuth",
            verify: func() error {
                _, err := verifier.VerifyClientCertificate(serverOnly)
                return err
            },
            wantErr: true,
        },
        {
            name: "客户端入口接受 ClientAuth",
            verify: func() error {
                _, err := verifier.VerifyClientCertificate(clientOnly)
                return err
            },
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := tt.verify()
            if (err != nil) != tt.wantErr {
                t.Fatalf("用途验证结果不符合预期: err=%v wantErr=%v", err, tt.wantErr)
            }
        })
    }
}

// loadRoleFixtures 由测试项目提供，返回同一 CA 下的不同用途证书。
func loadRoleFixtures(t *testing.T) (Verifier, *x509.Certificate, *x509.Certificate) {
    t.Helper()
    // 这里应加载项目 testdata 中固定的 CA、ServerAuth 和 ClientAuth 证书。
    panic("由项目测试夹具实现")
}

这段示例故意把夹具加载留给项目自身，因为不同团队的证书模板、SAN 和中间链不同。真正需要锁住的是三条断言：服务端入口接受 ServerAuth，客户端入口拒绝 ServerAuth，客户端入口接受 ClientAuth。若使用双用途证书，再增加两边都通过的独立用例。

与 crypto/tls 配置怎样对应

手工调用 x509.Verify 时要自己选择用途；使用 crypto/tls 的常规握手时，库会根据连接角色执行相应验证。客户端验证服务端时使用 RootCAs 和 ServerName；服务端验证客户端时使用 ClientCAs，并通过 ClientAuth 决定是否要求、是否验证客户端证书。

// 客户端配置：验证服务端证书链，并校验目标主机名。
clientTLS := &tls.Config{
    RootCAs:    serverRoots,
    ServerName: "api.example.test",
    MinVersion: tls.VersionTLS12,
}

// 服务端 mTLS 配置：要求客户端提供可由 ClientCAs 验证的证书。
serverTLS := &tls.Config{
    Certificates: []tls.Certificate{serverCertificate},
    ClientCAs:    clientRoots,
    ClientAuth:   tls.RequireAndVerifyClientCert,
    MinVersion:   tls.VersionTLS12,
}

tls.RequireAnyClientCert 只要求对方发送证书，不要求证书有效；真正的 mTLS 验证通常使用 tls.RequireAndVerifyClientCert。如果使用 VerifyPeerCertificate 或 VerifyConnection 自定义逻辑，也要确认正常验证是否被保留，以及回调拿到的 VerifiedChains 是否为空。

迁移检查清单

• 搜索所有 Certificate.Verify 调用，标注它验证的是服务端还是客户端证书。
• 把空 KeyUsages 改为显式的 ServerAuth 或 ClientAuth。
• 删除网络认证路径中的 ExtKeyUsageAny，只在通用检查工具里保留。
• 服务端证书验证设置正确的 DNSName，并使用 SAN 匹配结果。
• 客户端证书验证通过后，再执行账户、设备或服务身份授权。
• 增加“错误用途必须失败”的测试，而不只测试正确用途能通过。
• 检查中间 CA 和根 CA 是否也包含限制用途的 EKU。

还要记住，Certificate.Verify 不执行证书吊销检查。用途正确、链可信和时间有效，并不自动等于证书没有被撤销；需要吊销策略时，应另外设计 OCSP、CRL 或短周期证书机制。

常见问题

KeyUsages 传两个值，是同时满足还是满足一个？

官方定义是链允许其中任意一个用途即可。因此需要严格区分角色时，每次验证只传当前场景对应的一个用途。

证书没有 EKU 扩展怎么办？

不要仅凭字段为空就自行判定它属于某个角色，应让 Verify 按链和请求用途处理，并结合组织的签发策略决定是否还要增加更严格的应用层限制。

验证客户端证书需要设置 DNSName 吗？

通常不需要。DNSName 主要用于把服务端证书绑定到访问主机；客户端身份应由 SAN、URI、Subject 或业务扩展映射，并在证书链验证后单独授权。

迁移的关键不是多写一个枚举值，而是让证书角色成为代码接口的一部分：服务端验证只接受 ServerAuth，客户端验证只接受 ClientAuth，测试再明确证明错误用途会失败。这样证书策略才不会随着调用方复制粘贴而悄悄变宽。