x509 证书池怎样按租户隔离信任根

按租户隔离 x509 信任根，核心不是在验证时再判断“这是哪个租户”，而是让每个租户从一开始就拿到独立的 *x509.CertPool、*tls.Config 和可复用的 *http.Transport。严格私有信任应从 x509.NewCertPool() 开始，只加入该租户允许的根证书；如果业务明确允许公共 CA，再为这个租户单独取得或克隆系统根池后追加私有根。池构建完成后应视为不可变对象，轮换时整体替换快照，不能在共享池上继续追加。

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

租户隔离的验收标准不是“每个租户配置了不同 PEM 文件”，而是 Tenant A 的任何验证路径都不可能看到 Tenant B 的信任锚。

一次跨租户误信任的影响面

下面用一个复合排障场景说明问题。某网关需要访问多个租户自建的 HTTPS 服务。每个租户上传一份私有根 CA，网关为减少对象数量，在启动时创建一个全局 CertPool，再把所有租户 PEM 依次追加进去。所有出站请求共用一个带该根池的 http.Transport。

系统平时没有明显报错，因为每条合法证书链都能成功建立。真正的问题出现在负向测试：使用 Tenant B 私有 CA 签发、但部署在 Tenant A 目标地址上的服务证书，只要主机名也匹配，就可能被公共根池接受。也就是说，TLS 仍完成了密码学验证，却验证了错误的业务信任边界。

这类故障不会表现为“证书无效”，反而会表现为连接正常，因此监控只看握手失败率很难发现。必须把跨租户失败用例作为安全不变量。

触发条件藏在共享对象里

问题通常由三个条件共同触发：

• 多个租户的根证书被追加到同一个可变 CertPool；
• 多个租户的 tls.Config.RootCAs 指向这个池；
• HTTP 客户端或 Transport 又被跨租户复用。

// 错误示例：所有租户根被合并到同一个信任域。
sharedRoots := x509.NewCertPool()

for _, tenant := range tenants {
	// AppendCertsFromPEM 只说明是否追加到至少一张证书，
	// 它不会替业务判断这张根属于哪个租户。
	if ok := sharedRoots.AppendCertsFromPEM(tenant.RootPEM); !ok {
		return fmt.Errorf("tenant %s: invalid root PEM", tenant.ID)
	}
}

sharedTransport := http.DefaultTransport.(*http.Transport).Clone()
sharedTransport.TLSClientConfig = &tls.Config{
	MinVersion: tls.VersionTLS12,
	RootCAs:    sharedRoots, // 错误：租户边界在这里消失
}

x509.VerifyOptions.Roots 决定叶子证书最终允许链接到哪些信任锚；如果为 nil，验证可能使用系统根或平台验证器。多租户私有 PKI 若需要严格隔离，就不应依赖 nil 的默认行为，也不应把所有私有根合并到一个池中。

根因不是证书链，而是信任对象共享

排障初期很容易把注意力放在证书 Subject、Issuer 或 SAN 上，但这些字段都可能完全正确。根因是授权模型被错误编码成了一个进程级集合：只要任意租户允许某个根，所有共用该集合的请求都能看到它。

Go 的 CertPool.Clone() 会返回池的副本，SystemCertPool() 也返回系统池的副本；对返回池的修改不会写回磁盘，也不会影响其他 SystemCertPool() 返回的池。这些 API 很适合“先取得基线，再为某个租户单独扩展”的策略。但如果把副本重新存成全局变量，然后继续为所有租户追加，隔离仍然会失效。

另一个常见误区是用 CertPool.Subjects() 做审计。官方文档已经将其标记为弃用，而且由 SystemCertPool() 返回的池可能不会在 Subjects 中包含系统根。更可靠的办法是：配置加载时自行解析允许的根证书，记录 DER 指纹、序列号和配置版本；运行时日志记录租户 ID 与快照版本，而不是反向枚举池来猜测来源。

修复为每租户一份不可变快照

修复代码先从一个纯构建函数开始。它只接收某个租户的配置，只返回该租户的根池和 HTTP 客户端，不访问全局可变池。

package tenanttls

import (
	"crypto/sha256"
	"crypto/tls"
	"crypto/x509"
	"encoding/hex"
	"encoding/pem"
	"fmt"
	"net/http"
	"time"
)

type Snapshot struct {
	Version      string
	Roots        *x509.CertPool
	Fingerprints []string
	Transport    *http.Transport
	Client       *http.Client
}

// BuildStrictSnapshot 只信任传入租户的私有根，不自动叠加系统根。
func BuildStrictSnapshot(version string, rootPEM []byte) (*Snapshot, error) {
	pool := x509.NewCertPool()
	fingerprints, err := appendRoots(pool, rootPEM)
	if err != nil {
		return nil, err
	}

	tlsConfig := &tls.Config{
		MinVersion: tls.VersionTLS12,
		RootCAs:    pool,
	}

	// 克隆默认 Transport，保留合理的代理、超时和连接池默认值。
	transport := http.DefaultTransport.(*http.Transport).Clone()
	transport.TLSClientConfig = tlsConfig
	transport.ForceAttemptHTTP2 = true

	return &Snapshot{
		Version:      version,
		Roots:        pool,
		Fingerprints: fingerprints,
		Transport:    transport,
		Client: &http.Client{
			Transport: transport,
			Timeout:   30 * time.Second,
		},
	}, nil
}

// appendRoots 同时追加证书并记录稳定指纹，避免依赖 Subjects 反查。
func appendRoots(pool *x509.CertPool, data []byte) ([]string, error) {
	var fingerprints []string
	for len(data) > 0 {
		block, rest := pem.Decode(data)
		data = rest
		if block == nil {
			break
		}
		if block.Type != "CERTIFICATE" {
			continue
		}

		cert, err := x509.ParseCertificate(block.Bytes)
		if err != nil {
			return nil, fmt.Errorf("parse root: %w", err)
		}
		if !cert.IsCA {
			return nil, fmt.Errorf("certificate %s is not a CA", cert.Subject)
		}

		pool.AddCert(cert)
		sum := sha256.Sum256(cert.Raw)
		fingerprints = append(fingerprints, hex.EncodeToString(sum[:]))
	}
	if len(fingerprints) == 0 {
		return nil, fmt.Errorf("no CA certificate found")
	}
	return fingerprints, nil
}

如果某个租户明确要求同时信任公共 CA 和私有 CA，可以提供另一个策略函数：先调用 x509.SystemCertPool()，检查错误，再只向这个租户的副本追加私有根。不要把“严格私有根”和“系统根加私有根”藏在同一个布尔默认值里，建议使用清晰的策略枚举并写进租户配置。

不要只隔离 CertPool，还要隔离 TLS 客户端

仅创建两个根池还不够。如果所有请求仍复用一个 http.Transport，就只能绑定一个 TLSClientConfig。正确做法是以租户或“租户 + 出站策略”作为客户端缓存键，每个条目长期复用自己的 Transport。Go 官方文档建议复用 Client 和 Transport，它们可被多个 goroutine 并发使用；这里的复用范围应限制在同一信任策略内。

type Registry struct {
	mu    sync.RWMutex
	items map[string]*Snapshot
}

// Get 返回只读快照；调用方不得修改其中的 CertPool 或 tls.Config。
func (r *Registry) Get(tenantID string) (*Snapshot, bool) {
	r.mu.RLock()
	defer r.mu.RUnlock()
	snapshot, ok := r.items[tenantID]
	return snapshot, ok
}

// Replace 原子替换单个租户快照，不影响其他租户的信任边界。
func (r *Registry) Replace(tenantID string, next *Snapshot) {
	r.mu.Lock()
	previous := r.items[tenantID]
	r.items[tenantID] = next
	r.mu.Unlock()

	if previous != nil {
		// 只关闭旧 Transport 的空闲连接，不中断正在使用的连接。
		previous.Transport.CloseIdleConnections()
	}
}

不要在请求到来时修改共享的 tls.Config 或 CertPool。把快照发布后视为不可变，既能避免数据竞争，也让日志中的版本号真正对应一组固定信任锚。

证书轮换要整体替换，不能原地追加

根证书轮换通常有重叠期，但重叠也必须发生在租户内部。推荐做法是离线构建 version=v2 的新快照，其中同时包含该租户的旧根和新根；完成解析、CA 属性、指纹和负向验证后，再一次性替换注册表条目。重叠期结束后，构建只含新根的 version=v3，再次整体替换。

不要在旧池上直接调用 AddCert 或 AppendCertsFromPEM。原地修改会让当前使用者看到一个随时间变化的信任集合，故障发生时也很难回答“某次握手究竟使用了哪一版根”。

系统根也有类似边界。官方文档提醒，系统根的新变化未必会反映在后续调用中，因此长期运行的服务不应把“再次调用 SystemCertPool()”当成可靠热更新机制。将操作系统 CA 更新转化为明确的配置重载或进程发布事件更容易审计。

如何验证隔离真的生效

回归测试应同时覆盖正向和负向矩阵。只测试“本租户能连接”无法发现信任扩散。

// verifyForTenant 在单元测试中直接验证叶子与中间证书集合。
func verifyForTenant(
	snapshot *Snapshot,
	leaf *x509.Certificate,
	intermediateCerts []*x509.Certificate,
	dnsName string,
) error {
	intermediates := x509.NewCertPool()
	for _, cert := range intermediateCerts {
		// 中间证书只参与构链，不能放进 Roots 充当信任锚。
		intermediates.AddCert(cert)
	}

	_, err := leaf.Verify(x509.VerifyOptions{
		Roots:         snapshot.Roots,
		Intermediates: intermediates,
		DNSName:       dnsName,
		KeyUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
	})
	return err
}

不要用 InsecureSkipVerify=true 绕过问题。它会跳过证书链和主机名的正常验证，等于直接移除本文试图建立的边界。若确实需要额外策略，应在正常验证成功后使用 VerifyConnection 追加约束，而不是替代标准校验。

防复发清单

• 每个租户根池只包含该租户策略允许的信任锚，默认不引入系统根。
• RootCAs、tls.Config、http.Transport 按同一租户策略绑定并复用。
• 配置加载时记录根证书 SHA-256 指纹与快照版本，不依赖 Subjects() 反查。
• 所有 PEM 解析失败、非 CA 证书和空根集合都在发布快照前拒绝。
• 根轮换通过构建新池和原子替换完成，不在服务中的池上原地追加。
• 测试矩阵必须包含 A 信任 B、B 信任 A 均失败的负向用例。
• 日志记录租户 ID、目标主机、快照版本和验证错误类型，但不记录私钥或完整证书机密。

这次复盘最重要的结论是：CertPool 不是一袋可以不断追加的“证书材料”，而是一份业务授权集合。多租户系统必须让授权集合与租户边界一一对应，再把它绑定到 TLS 和连接池对象。只要池、TLS 配置或 Transport 仍跨租户共享，PEM 文件分目录存放也不能形成真正的信任隔离。

相关问题

可以从 SystemCertPool 克隆后再隔离吗

可以，但前提是租户策略明确允许公共 CA。每个租户都应拿到自己的副本，再追加该租户私有根；严格私有 PKI 则直接使用 x509.NewCertPool()。

客户端 RootCAs 和服务端 ClientCAs 有什么区别

客户端的 RootCAs 用于验证服务端证书；启用 mTLS 时，服务端的 ClientCAs 用于验证客户端证书。两个方向都可能需要按租户隔离，但不能把一侧的池误用到另一侧。

中间证书能不能直接放到 Roots

不建议。Roots 表示信任锚，Intermediates 只帮助构建从叶子到根的链。把普通中间证书放进 Roots 会扩大信任边界，应在 VerifyOptions.Intermediates 中提供。