sign-kms · API 参考

gRPC KmsService

来源：api/v1/kms.proto:7-13、internal/service/kms_service.go:20-80。

方法	行号 (proto)	行号 (service)	请求	响应
GenerateKeypair	8	20-29	GenerateKeypairRequest	PublicKeyResponse
GetPublicKey	9	31-40	GetPublicKeyRequest	PublicKeyResponse
Sign	10	42-60	SignRequest（id、digest）	SignResponse（signature）
Verify	11	62-78	VerifyRequest（id、digest、signature）	VerifyResponse（bool valid）
HealthCheck	12	80	HealthCheckRequest	HealthCheckResponse（healthy、partitions map）

鉴权

internal/server/grpc.go:26-28 中间件链：recovery → signet → GrpcAuthMiddleware → audit。

GrpcAuthMiddleware（pkg/auth/grpc_auth.go:48-80）：

• 解析 Authorization: Bearer <jwt>。
• 校验 JWT 签名（用 KMS_AUTH_SECRET）与过期。
• 调用 TokenStore.GetByJTI：若 Disabled 返回 Forbidden（:62-74）；若有 view，用 DB 中的 keys 覆盖 JWT claims.Keys。
• 注入 claims 到 context。

权限矩阵（pkg/auth/claims.go:42-46）：

Role	允许的 operation
readonly	get_public_key、verify
readwrite	sign、verify、get_public_key
admin	sign、verify、get_public_key、gen_keypair、sign_cert、sign_crl

JWT claims（pkg/auth/claims.go:11-22）：

type KMSClaims struct {
    jwt.RegisteredClaims
    PartitionID string
    Role        string
    Keys        []string
}

HTTP 端点

来源：api/v1/manage.proto:11-81、internal/server/http.go:70、internal/service/kms_manage_service.go。

方法	路径	请求类型	proto 行号
POST	/api/v1/signin	SigninRequest（username、password）	12-16
POST	/api/v1/signout	Empty	18-22
GET	/api/v1/current	Empty	24-26
POST	/api/v1/create-ns	CreateNsRequest（name、description、provider_id、token_label、user_pin）	27-31
POST	/api/v1/access-token	GetAccessTokenRequest（ns_id、subject、role、keys[]、expires_in）	33-37
GET	/api/v1/list-ns	Empty	39-41
GET	/api/v1/list-providers	Empty	42-44
GET	/api/v1/list-keys	ListKeysRequest	45-47
POST	/api/v1/create-key	CreateKeyRequest	48-52
GET	/api/v1/list-access-tokens	ListAccessTokensRequest	54-56
POST	/api/v1/sync-keys	SyncKeysRequest	57-61
POST	/api/v1/disable-access-token	DisableAccessTokenRequest	63-67
POST	/api/v1/enable-access-token	EnableAccessTokenRequest	69-73
POST	/api/v1/update-access-token-keys	UpdateAccessTokenKeysRequest	75-79

中间件（internal/server/http.go:49-56）：recovery → signet → logging，FilterFunc = HttpAuthMiddleware()。

HttpAuthMiddleware（pkg/auth/http_auth.go:27-56）：仅检查 /api/* 路径；白名单为 /api/v1/signin（pkg/auth/config.go:11 的 NoAuthPaths）；从 cookie 读 token → ParseToken → jwt.NewContext。

libkms_pkcs11.so

来源：p11client/kms_so.c。

kms_so.c 的 CK_FUNCTION_LIST 暴露 68 个标准 PKCS#11 C_* 函数。与 KMS 操作相关者为实质实现（按源码顺序）：

C_Initialize / C_Finalize / C_GetInfo / C_GetFunctionList / C_GetSlotList / C_GetSlotInfo / C_GetTokenInfo / C_GetMechanismList / C_GetMechanismInfo / C_InitToken / C_InitPIN / C_SetPIN / C_OpenSession / C_CloseSession / C_CloseAllSessions / C_GetSessionInfo / C_Login / C_Logout / C_GenerateKeyPair / C_SignInit / C_Sign / C_GetAttributeValue / C_SetAttributeValue / C_FindObjectsInit / C_FindObjects / C_FindObjectsFinal / C_VerifyInit / C_Verify

其余（加解密、摘要、Wrap/Unwrap、随机数等）为桩实现，返回 CKR_FUNCTION_NOT_SUPPORTED。源码还定义了一个不在标准函数表中的自定义辅助函数 C_GetPublicKey。

环境变量（kms_so.c）：

变量	行号	用途
KMS_SO_DEBUG	39	调试日志
SIGN_KMS_ENDPOINT	202	KMS gRPC 端点

Operations / 健康检查

来源：internal/server/http.go:73（obs.RegisterRoutes(srv)）。

注册路径：/healthz、/readyz。具体响应字段 [未核]，需读 obs 包源码。

CLI

仓库不含独立 CLI 工具；所有操作走 gRPC / HTTP API。