Go x509.VerifyOptions 只验证服务器证书时怎么设置 KeyUsages

在仅验证服务器证书的单向TLS场景下，你设置`x509.VerifyOptions`的KeyUsages字段时，直接传入仅包含服务端认证扩展密钥用途的列表就能实现限定校验逻辑。

只验证服务器证书时，KeyUsages字段赋值为`[]x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}`，即可过滤掉不满足服务端认证要求的非法证书，不需要额外加入其他用途项。

在 Go 中只接受“服务器用途”的证书链，最小配置可以直接写成 KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}。VerifyOptions.KeyUsages 为空时，官方语义本身也按 ExtKeyUsageServerAuth 处理；但在生产代码里显式写出用途，能让审查者一眼看出这不是“接受任意用途”。

官方文档地址：https://pkg.go.dev/crypto/x509#VerifyOptions

只验证服务器证书时，把 ExtKeyUsageServerAuth 放进 KeyUsages；不要使用 ExtKeyUsageAny 来掩盖用途不匹配。Roots、Intermediates、DNSName 解决的是不同问题，排障时要分开判断。

出现什么信号时先看 KeyUsages

如果 Certificate.Verify 返回 x509: certificate specifies an incompatible key usage，优先检查叶子证书和中间证书的扩展用途，而不是先换根证书。Go 的验证器会把 Extended Key Usage 沿证书链约束下来：中间证书或根证书如果列出了用途，叶子证书不能突破这层限制。

相反，certificate signed by unknown authority 更像是 Roots 或中间证书集合问题；主机名不匹配则应看 DNSName 和证书的 SAN。三类错误都可能发生在一次 Verify 调用里，但修复方向不同。

服务器用途应该怎样写进 VerifyOptions

推荐显式设置服务器用途，保留其他校验条件的职责边界：

package main

import "crypto/x509"

func serverVerifyOptions(roots, intermediates *x509.CertPool, host string) x509.VerifyOptions {
	return x509.VerifyOptions{
		// 显式限定为 TLS 服务端用途，避免把客户端或代码签名证书当成服务端证书。
		KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
		// Roots 决定信任锚；Intermediates 只补充链路中的非信任锚证书。
		Roots:         roots,
		Intermediates: intermediates,
		// DNSName 负责名称匹配，不要用 KeyUsages 代替主机名校验。
		DNSName: host,
	}
}

这里的关键是切片中放入 ExtKeyUsageServerAuth。KeyUsages 不是证书要被写入的用途，而是本次验证允许的用途集合；链路只有在允许集合与证书链声明能够匹配时才会通过。

空切片、ServerAuth 和 Any 有什么区别

对普通 HTTPS 服务端证书校验，优先选择显式的 ServerAuth。不要为了让失败消失就改成 ExtKeyUsageAny；那会扩大接受范围，可能把用途不适合服务端的证书放进验证结果。

把证书校验失败拆成三类信号

值班排查时，可以把配置和错误按下面的边界分层：

func classifyVerifyError(err error) string {
	if err == nil {
		// nil 表示证书链、用途和名称条件都没有返回错误。
		return "verified"
	}

	var invalid x509.CertificateInvalidError
	if errors.As(err, &invalid) {
		// IncompatibleUsage 代表用途不匹配，其他 Reason 需要继续看具体语义。
		if invalid.Reason == x509.IncompatibleUsage {
			return "key-usage-mismatch"
		}
		return "certificate-invalid"
	}

	var hostname x509.HostnameError
	if errors.As(err, &hostname) {
		// HostnameError 属于 DNSName/SAN 层，不要通过放宽 KeyUsages 修复。
		return "hostname-mismatch"
	}

	var authority x509.UnknownAuthorityError
	if errors.As(err, &authority) {
		// UnknownAuthorityError 优先检查 Roots 和 Intermediates 的来源。
		return "trust-chain-mismatch"
	}
	return "other-verify-error"
}

示例依赖 errors 包，实际文件中需要同时导入 crypto/x509 和 errors。分类函数只负责让告警路由更清晰，不会替代证书链验证，也不会执行吊销检查。官方文档明确说明 Certificate.Verify 本身不做吊销检查。

线上处理和回滚怎么安排

当升级后出现用途不匹配告警，先记录失败证书的 Subject、Issuer、SAN 和 EKU，再确认调用方是否把客户端证书或中间证书误当成叶子证书。若确认是配置误收紧，回滚到上一版显式的 ServerAuth 配置；不要直接回滚到 ExtKeyUsageAny。

若证书供应方刚切换链路，优先补齐正确的中间证书池，保持 KeyUsages 不变。若只是域名变化，更新 DNSName 或证书 SAN。每次只改一层，便于从告警中判断真正的修复项。

告警确认与复盘清单

• 告警中区分 IncompatibleUsage、UnknownAuthorityError 和 HostnameError。
• 记录本次验证使用的 Roots、Intermediates 来源，以及 DNSName 和 KeyUsages 配置。
• 确认服务端证书的 EKU 与中间证书约束一致，未用 ExtKeyUsageAny 绕过问题。
• 将证书更换、信任链调整和用途配置调整拆成独立变更，保留回滚点。

相关问题

KeyUsages 为空是不是不校验用途？不是。Go 官方文档规定空列表按 ExtKeyUsageServerAuth 处理。

ExtKeyUsageAny 能不能修复服务端证书验证失败？它可能放宽用途匹配，但会扩大接受范围，不应作为常规修复。

Verify 会自动检查证书是否被吊销吗？不会。吊销检查需要由应用按自己的证书与基础设施策略另行处理。