主题
CA 与证书签发
本章描述 sign-pki/、fabric-ca/ 与 sign-kms/ 当前代码形成的签发体系。规范性信任模型以 sign-pki/docs/pki-architecture-standard.md 为准；实现入口见 sign-pki · 概述。
1. 三个组件的职责
| 组件 | 代码位置 | 职责 | 不负责 |
|---|---|---|---|
sign-pki pki-cli | sign-pki/pki-cli/ | 离线 Root 自签、Intermediate CSR/签发、CA Bundle、公开材料检查 | 叶子证书、在线 RA、HSM Key 生命周期 |
sign-pki ca-server | sign-pki/ca-server/ | 提供标准 Fabric CA v1.5.22 在线 API，通过 PKCS#11 使用 CA Key | Root 仪式、网络准入审批 |
| sign-kms | sign-kms/ | 将 PKCS#11 操作路由到 HSM，执行认证、隔离、签名 | 决定证书 Subject、用途和联盟权限 |
ca-server 与 pki-cli 是独立发布物。离线 Root 工具不进入在线 CA 镜像，在线 CA 也不替代离线审批与仪式。
2. CA 层级
text
Identity Root CA（央行离线 HSM）
├── Central Bank Identity Intermediate CA（央行在线 HSM）
├── Bank01…BankNN Identity Intermediate CA（各银行在线 HSM）
└── Wallet Operational X.509 Intermediate CA（央行在线 HSM）
TLS Root CA（央行离线 HSM）
├── Central Bank TLS Intermediate CA（央行在线 HSM）
└── Bank01…BankNN TLS Intermediate CA（各银行在线 HSM）
Wallet Idemix CA（央行在线）
└── Idemix Issuer / Revocation 参数（受控密钥文件）Identity Root 与 TLS Root 使用不同的 Key/Certificate。Wallet Operational Intermediate 虽由 Identity Root 签发，但只用作 Wallet Fabric CA 的 X.509 运行 signer，不进入联盟 MSP，也不签普通网络身份。
标准 Fabric CA v1.5.22 的 Idemix Issuer Secret Key 与 Issuer Revocation Private Key 不经过 BCCSP/PKCS#11。当前实现不能宣称这两类 Key 已由 HSM 托管；若要改变，需单独适配并完成兼容性验证。
3. 离线 Root 与 Intermediate 仪式
3.1 固定策略
pki-cli/pki/ 将策略固定在代码中：
| 材料 | 算法 | Basic Constraints | Key Usage | 其他约束 |
|---|---|---|---|---|
| Root CA | ECDSA P-256/P-384 | CA=true, pathLen=1 | CertSign、CRLSign、DigitalSignature | 自签；AKI=SKI；无 SAN/EKU |
| Intermediate CA | ECDSA P-256/P-384 | CA=true, pathLen=0 | CertSign、CRLSign、DigitalSignature | AKI=Root SKI；无 SAN/EKU；NotAfter 不超过 Root |
| Intermediate CSR | ECDSA P-256/P-384 | 不在 CSR 请求 | 不在 CSR 请求 | 只含 Subject/Public Key；禁止 SAN、属性和扩展 |
3.2 单条命令流程
ca sign 先校验 Root DER SHA-256、Root 固定策略、CSR 自签名与 Subject，再从 Root Certificate 公钥推导 SKI，确认 HSM Key 公钥匹配后签发。输出不混入 Root Certificate。
3.3 Catalog / Bundle 流程
实际初始部署优先使用：
bash
pki-cli bundle generate --config bundle-catalog.yaml
pki-cli bundle verify --config bundle-catalog.yamlCatalog 声明 KMS Profile、组织、Identity/TLS Root、各组织 Intermediate、Wallet CA 与 issuerRef。代码按依赖拓扑执行，全量成功后才原子发布；输出含证书/链、manifest.json 与 checksums.sha256。
一次全量执行要求所有 selected target 使用同一 KMS Endpoint，因为当前 PKCS#11 Client 每个进程读取一个 Endpoint。央行与银行使用不同 Endpoint 时，应按 --name 分进程执行并沿用同一审批 Catalog。
4. CA Bundle 到在线 CA
Intermediate / Wallet Bundle 的目标目录可作为标准 Fabric CA HOME 的只读证书层：
text
ca-cert.pem # 本 CA Certificate
ca-chain.pem # 上级 Root Chain
manifest.json # 组织、信任域、用途、指纹等
checksums.sha256 # 完整性校验Fabric CA 配置中 ca.keyfile 为空，bccsp.default=PKCS11，PKCS#11 Client 路径为 /usr/local/lib/libkms_pkcs11.so。运行时通过环境变量注入 FABRIC_CA_SERVER_BCCSP_PKCS11_PIN；该值实际承载 sign-kms Access Token，不得写入配置或日志。
5. 三类在线 CA
sign-pki/ca-server/templates/production/ 提供三份生产骨架：
| 模板 | 签发范围 | 关键限制 |
|---|---|---|
| Identity CA | 本组织 Fabric/Fabric-X MSP、节点和最小权限管理身份 | 不签 TLS，不签业务密码 Key |
| TLS CA | TLS Server、TLS Client、mTLS 身份 | Server Certificate 必须含实际 DNS/IP SAN |
| Wallet Idemix CA | 用户注册、Idemix Credential、CRI；X.509 signer 仅维持服务运行 | Wallet Operational Certificate 不进入 MSP；用户 Idemix Key 留在外部钱包 |
每个组织和信任域使用独立数据库、HSM partition、Registrar 与网络边界。同一 CA 多副本共享自己的数据库、CA Certificate/Chain 与同一逻辑 HSM Key。
6. HTTPS/mTLS 上线顺序
生产模板要求 REST API 与 Operations API 均开启 TLS/mTLS，数据库连接启用 TLS。CA 进程自身的 HTTPS Key 使用 SW PEM；CA signer Key 仍留在 HSM，两者不得混用。
TLS Intermediate CA 需要为自己签发首批服务证书时，只允许：
- 单副本、仅回环地址、无 Service/Ingress 的临时 HTTP 进程。
- 使用标准 Fabric CA Client 与 SW BCCSP 生成 REST/Operations Server 和管理 Client 的 Key/CSR。
- 版本化发布
bootstrap-tls/Secret，停止临时实例。 - 用正式模板以 HTTPS/mTLS 重启并验证，之后才开放网络入口。
Identity CA、Wallet CA 等其他在线 CA 的服务证书必须由已上线的所属组织 TLS Intermediate CA 预先签发，不得自动降级为 HTTP。完整检查清单见 sign-pki/docs/fabric-ca-production-rollout.md。
7. 叶子证书与管理授权
pki-cli 不签叶子证书。日常生命周期使用标准 Fabric CA：
text
Register → Enroll → Reenroll → Revoke → CRL高权限操作需要两层控制：
- HTTPS/mTLS 或等价的传输层强身份。
- Fabric CA Enrollment Certificate、请求签名与
hf.*Registrar/Revoker 属性。
API Key 可用于网关识别或限流，但不能替代 Fabric CA Registrar 授权。Bootstrap Admin 只用于初始化，创建受限身份后必须封存。
8. PKI 信任与 Fabric-X 准入
Root 对银行 Intermediate 的签名只建立 PKI 信任，不授予 Fabric-X 网络权限。银行加入还需要：
- 提交公开组织 MSP 与 TLS CA Chain。
- 联盟审批组织、节点角色和策略。
- 生成并提交 ConfigUpdate。
- 验证配置传播后再启用节点。
央行默认不接收银行 Intermediate CA Key、Registrar 私钥、节点私钥或 Enrollment Secret。跨组织交付只包含 CSR、证书、链、manifest、checksum 和审批记录。
9. 轮换与撤销
- 叶子证书优先通过 Reenroll 续期，版本化发布并滚动节点；Root/Intermediate 未变时通常不改 MSP 信任锚。
- Root/Intermediate 换代采用新旧信任锚并存：先传播信任，再滚动叶子证书，宽限期后移除旧 CA。
- Orderer TLS 续期优先复用原私钥；若换 Key，需先处理网络配置绑定。
- Idemix Issuer/Revocation Key 换代是新参数版本迁移，历史验证参数必须按治理周期保留。
10. 验证入口
| 层级 | 验证方式 |
|---|---|
| pki-cli 单元/架构测试 | cd sign-pki/pki-cli && go vet ./... && go test ./... |
| 真实 PKCS#11 CLI 流程 | cd sign-pki/pki-cli && make test-integration，只消费已准备的 Key/SKI/PIN |
| 在线 CA wire 协议 | cd sign-pki && make test-e2e，目标 CA 必须单独部署 |
| 生产上线 | 按 fabric-ca-production-rollout.md 验证 TLS、mTLS、DB、HSM、备份、审计与故障恢复 |
CA e2e 覆盖 CAInfo、Enroll、Register、Reenroll、身份查询、Revoke 和 CRL，能验证 fabric-ca-server → libkms_pkcs11.so → sign-kms → HSM 的真实签名路径；当前本地 e2e 的 HTTP、SW 客户端 Key 和 SQLite 结论不得外推到生产。
11. 当前代码速查
| 项 | 当前值 |
|---|---|
| Fabric CA 版本 | v1.5.22 |
| Fabric CA build tag | pkcs11 |
| 默认 Idemix 曲线 | gurvy.Bn254 |
| PKCS#11 Client | /usr/local/lib/libkms_pkcs11.so |
| Token label | KMS_TK |
| CA REST / Operations 端口 | 7054 / 9443 |
| Root / Intermediate path length | 1 / 0 |
| pki-cli module | github.com/built-by-sign/sign-pki/pki-cli |
运行配置中仍可能出现 sign-ca 镜像、容器或 CA 名称；这些是现存兼容标识，不再表示源码仓库。仓库路径、文档入口与 Go module 均使用 sign-pki。