KernLab.Claim 引擎包使用指南
1. 定位
KernLab.Claim 是认证引擎包:JOSE/JWT 签发与验证(ES256 零第三方)、签名密钥环(双 key 宽限)、
PKCE、PBKDF2、TOTP、KEK、TokenService 授权流、IClaimStore 存储抽象——面向嵌入式/自建形态的
引擎级复用。部署统一认证中心请用宿主 kernlab-claim;消费方取 token/验签请用
KernLab.Claim.Client SDK。
2. 快速上手
using KernLab.Claim.Hosting;
using KernLab.Claim.Security;
using KernLab.Claim.Services;
using KernLab.Claim.Store.Tier;
var options = new ClaimOptions { DataDir = null }; // null = memory 介质(介质是配置)
var store = await TierClaimStore.CreateAsync(options.TierFsSpec);
var keys = SigningKeyRing.Load(options.DataDir, store.CreateKeyStore());
var tokens = new TokenService(store, keys, options);
var issued = await tokens.ClientCredentialsAsync(client, scope: "kernlab.cohort.config.read");
异步优先(禁
GetAwaiter().GetResult());示例与当前源码同构。
3. 概念与术语
| 术语 | 含义 |
|---|---|
| 签名密钥环 | ES256 密钥集(持久化于根域 keys/signing 目录域);kid 锚点 + 双 key 宽限(轮换期新旧并行验签) |
| LogicalAddress | KV 引擎全局单调地址——即身份/版本/游标/fencing(CAS 令牌) |
| 会话原子批 | 多 key 全或无提交(BeginAtomicBatch/CommitBatchAsync) |
| KEK | 私钥静态加密主钥(AES-GCM,env CLAIM_KEK 注入;v1kek: 前缀识别明文/密文共存) |
| 恢复码 | TOTP 不可用的一次性替代因子(SHA-256 Hex 库存、消费即删) |
4. 怎么选
| 需求 | 用什么 |
|---|---|
| 部署完整认证中心 | 宿主 kernlab-claim(见其使用指南) |
| 消费方取 token / 验签 | KernLab.Claim.Client SDK(分层纪律——不背引擎) |
| 自建存储适配 | IClaimStore 实现(多实现挂同一契约测试:memory/Tier 缺省在树,Synod 待 KernLab.Synod.Client alpha.3 回归) |
| 嵌入式引擎复用 | 本包 |
5. 怎么用
5.1 TokenService(五流)
var issued = await tokens.ClientCredentialsAsync(client, scope: "...");
var issued = await tokens.AuthorizationCodeAsync(client, code, redirectUri, codeVerifier); // 签发 id_token+refresh
var issued = await tokens.RefreshAsync(client, refreshToken); // 轮换(旧值即弃)
var issued = await tokens.TokenExchangeAsync(client, subjectToken, audience, scope); // 代唤(act 串联)
var issued = await tokens.DeviceAuthorizeAsync(client, scope); // 设备流发起(WP9)
var issued = await tokens.DeviceTokenAsync(client, deviceCode, now); // 设备轮询(pending/slow_down/deny/granted 单次取走)
轮换语义:旧 refresh 一经换新即标记,二次使用视为泄露——撤销该客户端该用户全部 refresh(RFC 6749 §10.5)。
5.2 JwtValidator(验证面)
alg 白名单(ES256;none 恒禁)→ 签名 → 时间窗(时钟偏移容忍)→ iss/aud——消费方线上验签请用
Client SDK(同语义独立实现 + JWKS 自动刷新);本包验证器用于签发侧自检与测试。
5.3 SigningKeyRing(密钥环)
keys.Rotate(graceCount); // 新 kid 接任,旧 kid 入宽限(宽限数 = options.KeyGraceCount)
集群形态下 kid 未命中自动 ReloadFromStore 重验一次(他副本轮换可见——与消费方 JWKS 刷新同构)。
5.4 安全原语
PasswordHasher.Hash/Verify(PBKDF2,随哈希存迭代参数)、PasswordPolicy.Validate(长度/复杂度)、
Totp.Compute/Verify(RFC 6238)、KekProtector(私钥加密;env CLAIM_KEK)、
DpopProofValidator.ValidateAsync(WP11——RFC 9449 proof 矩阵 + cnf.jkt 解析:宿主与资源方共用,
htu 规范化 / jwk 含私钥即拒 / jti NX 单次 / ath 绑定)。
5.5 存储抽象
IClaimStore 十域(clients/users/users-by-email/账户令牌/codes/refresh/login-fail/sessions/jti +
settings)+ ISigningKeyStore + IAuditLog(TierTimeSeries)+ IStoreMigration(export/import 快照)。
存储实现唯一性——上层零手搓 store(介质是配置:ClaimOptions.FsKind → TierFsSpec;新介质 =
新 TierKv 介质 spec,不是新适配器)。WP7 增量三件:邮箱唯一索引 TrySaveUserWithEmailIndexAsync
(值版 CAS NX 恰一注册,改绑即迁槽)与账户一次性令牌 Save/ConsumeAccountTokenAsync
(email-verify 24h / pw-reset 30min,授权码同款 CAS 单次消费)。
5.6 限流器(WP10)
RateLimiter.HitAsync(dim, identity, now) = 固定窗计数(TierKv 限流域 CAS 递增,
争用 3 次降级放行——限流器故障不得化为全拒);维度阈值住 RateLimitSettings(0 = 关闭)。
5.7 账户自助与标准 claims(WP7/WP8)
AccountService(注册/验证/找回域逻辑——令牌落库只存 SHA-256、防枚举形态在宿主层呈文)+
UsernamePolicy(3–64 字符,键段安全)+ IEmailSender 端口(宿主缺省 = 自研最小 SMTP 客户端,
测试 = 进程内接箱桩)。StandardClaims.Project(tokenClaims, user) = userinfo 单点投影
(token scp × 用户档:profile → name/preferred_username;email → email/email_verified;
只发有值字段,id_token 维持最小集)。
5.8 WebAuthn 验证器与联邦服务(WP12/WP13)
- passkey(WP12):
Security.WebAuthn命名空间——CborDecoder(RFC 8949 子集:定长形态, 不定长/浮点/非法 UTF-8 恒拒;游标式入口服务嵌入段)、CoseKey(EC2/P-256 ES256 + RSA RS256, kty/alg/crv 越白名单 fail-fast)、AuthenticatorData(rpIdHash/flags/signCount/凭证段解析)、WebAuthnVerifier(clientDataJSON 矩阵 + attestation none/packed 自证 + assertion 验签, challenge 恒时比对)、WebAuthnService(挑战编排 + signCount CAS 克隆检测)。 - 联邦(WP13):
UpstreamJwks(上游 JWKS 拉取缓存 + kid 未命中刷新重验一次——不动 Client 包 JwksFetcher 包边界)+UpstreamIdToken.ValidateAsync(alg 白名单按上游配置——独立于本域 ES256 红线;iss/aud/exp/nonce 回填矩阵)+FederationService(state+nonce+PKCE 三防、 code 换 ID token、ident 绑定解析、MFA 待定态、idp-link/unlink 编排)。
5.9 可观测原语(WP14)
Diagnostics.ClaimDiagnostics(ActivitySource KernLab.Claim + W3C traceparent 注入——无监听器
零开销直通)+ TracedClaimStore(IClaimStore 装饰器——claim.store.<op> span,零业务代码侵入)+
TracedEmailSender + OtlpTraceExporter(自研 OTLP/HTTP JSON 编码;有界队列 1024 满即丢、
批量 5s/256、FlushAsync 手工驱动——宿主按 options.Otel 装配,嵌入形态按需自接)。
6. 反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 手写 JWT/手拼签名 | alg 混淆攻击面(RFC 8725) | JwtCodec 签发 + JwtValidator/SDK 验签(none 恒禁) |
| 自解 CBOR / 手拼 COSE | WebAuthn 攻击面(恶意嵌套/不定长/编码混淆) | CborDecoder 子集(不定长与浮点恒拒)+ CoseKey 白名单 |
| 上游 ID token 只解不验签 | 联邦伪造(iss/aud/nonce 全可冒) | UpstreamIdToken.ValidateAsync(验签矩阵 + alg 白名单独立于本域签发) |
| 自管内存 store / 字典缓存 | 存储实现唯一性红线(两次判例:InMemory*Store 被删) | IClaimStore + TierKv 介质 spec |
| 应用层自拼「读-改-写」 | 破坏原子性分层(CAS/Functions/原子批是唯一原语) | 引擎原子面(见 TIER.md 红线) |
业务代码直用 System.IO |
IO 纪律红线 | KernLab.Tier.Core.IO(TierFs) |
| TokenService 构造后改 Issuer 不回填 | 签发 iss 与 discovery 漂移 | 启动回填(BuildAsync 形态)后再发 token |