主题
sign-pki · API 参考
在线接口
sign-pki 不修改 Fabric CA 协议。ca-server 对外提供 Fabric CA v1.5.22 的标准 API；详细请求语义见 fabric-ca · API 参考。
| 默认端口 | 协议 | 用途 |
|---|---|---|
7054 | HTTP/HTTPS | Fabric CA REST API |
9443 | HTTP/HTTPS | Operations API（健康检查、metrics 等） |
8125/udp | StatsD | 可选指标上报；生产模板默认使用 Prometheus |
生产模板要求 CA API 与 Operations API 都启用 TLS/mTLS；Dockerfile 的 HTTP healthcheck 和本地 Compose 只代表开发配置。
常见 REST 路径：
| 路径 | 用途 |
|---|---|
POST /api/v1/cainfo | 查询 CA 名称与证书链 |
POST /api/v1/enroll | 首次签发 X.509 / Idemix 凭证 |
POST /api/v1/register | Registrar 创建身份 |
POST /api/v1/reenroll | 续签 |
POST /api/v1/revoke | 吊销身份或证书 |
POST /api/v1/gencrl | 生成 CRL |
GET /api/v1/identities | 查询身份 |
pki-cli 命令
Bundle
text
pki-cli bundle generate --config <catalog> [--name <target>]
pki-cli bundle verify --config <catalog> [--name <target>]Bundle 命令只接受 --config 和可选 --name，输出为 text。
离线 CA 仪式
text
pki-cli ca self-sign [flags]
pki-cli ca csr [flags]
pki-cli ca sign [flags]三个命令共享：
| flag | 默认值 | 说明 |
|---|---|---|
--kms-endpoint | SIGN_KMS_ENDPOINT | sign-kms gRPC Endpoint；显式 flag 优先 |
--pkcs11-lib | /usr/local/lib/libkms_pkcs11.so | PKCS#11 Client 路径 |
--pkcs11-pin-env | KMS_PIN | 保存 Access Token 的环境变量名 |
--format | text | text 或 json |
--force | false | 原子替换已有普通文件 |
ca self-sign 必填 --ski、--subject、--not-after、--out。
ca csr 必填 --ski、--subject、--out。
ca sign 必填 --issuer-cert、--issuer-sha256、--csr、--expected-subject、--not-after、--out。Root SKI 从已审批 Root Certificate 的公钥推导。
公开材料检查
text
pki-cli inspect --in <pem> [--kind auto|csr|cert|chain] [--format text|json]
pki-cli verify \
--profile csr|root-ca|intermediate-ca|chain \
--in <pem> \
[--issuer-cert <root.pem>] \
[--expected-subject <dn>] \
[--at <rfc3339>] \
[--warn-before <duration>] \
[--format text|json]inspect 只报告事实；签名无效或过期不会自动变成策略失败。需要安全判断时使用明确的 verify profile。
输出协议
- 成功结果写 stdout，错误写 stderr。
- JSON 使用
schemaVersion=v1Envelope 与稳定错误码。 - 指纹为证书/CSR DER 的 SHA-256，小写十六进制、无
0x。 - JSON warning 进入 Envelope；text 模式 warning 写 stderr，不改变成功退出码。
- Access Token、PIN 与私钥内容不得进入输出。
Makefile 目标
| 目录 | 目标 | 用途 |
|---|---|---|
sign-pki/ | build / build-multi | 构建/推送 CA Server |
sign-pki/ | build-pki-cli / build-pki-cli-multi | 构建/推送 pki-cli |
sign-pki/ | kms-up / kms-down | 本地 KMS |
sign-pki/ | ca-up / ca-down | 本地三 CA 编排 |
sign-pki/ | test-e2e | 对外部目标 CA 运行 e2e |
sign-pki/pki-cli/ | build | 构建 CLI 二进制 |
sign-pki/pki-cli/ | gen | 按 Catalog 生成 Bundle |
sign-pki/pki-cli/ | test-integration | 真实 PKCS#11 集成测试 |