jasoncolburne/kels

# KELS - 密钥事件日志系统 KELS 是一种联邦式去中心化密钥管理基础设施（DKMI），受 [KERI](https://github.com/WebOfTrust/keripy) 启发。它通过具有预轮换承诺、分歧检测和恢复机制的密钥事件日志提供可加密验证的身份管理——提供针对密钥泄露的保护，且不依赖证书颁发机构或集中式信任。 ## 什么是 DKMI？ DKMI 的产物是**可移植身份**——属于个人的加密身份，而非任何服务提供商的身份。 如今，集中式平台收集并存储大量个人数据，其中很多数据其实并不需要。通过可移植身份，服务只需验证*您就是您所声称的人*——它们无需成为您的身份、数据或关系的信息来源。大量数据存储和计算可以卸载到消费者设备上，这是它们应该存在的地方。 这改变了力量平衡。数据由个人拥有和控制，而非被公司挟持。您的身份可以在不同服务间随身携带。您的密钥可以自行轮换，无需任何人许可。如果某个服务消失，您的身份不会随之消失。 通过[联邦注册表](docs/federation.md)，KELS 还可以作为多云、多运营商应用的安全身份骨干——独立组织各自运行自己的注册表，同时共享全局信任层，不依赖任何单一证书颁发机构或云提供商。 ## 工作原理 KELS 实现了密钥事件日志系统，其中： - 每个事件在需要之前就提交给*下一个*签名密钥（**预轮换承诺**） - 单独的恢复密钥支持从签名密钥泄露中恢复（**恢复密钥**） - 同一序列号的冲突事件会被检测并存储（**分歧检测**） - 合法所有者可以使用恢复密钥从对抗性事件中恢复（**恢复协议**） - 当双方都执行恢复操作时，KEL 将被永久冻结（**争议机制**） 所有事件都是自寻址的（通过 SAID 内容寻址）并经过加密签名，使整个日志防篡改且可端点验证。 ### 密钥层级 | 层级 | 密钥 | 用途 | |------|------|------| | 1 | **签名密钥** | 签署普通事件（`ixn`、`rot`） | | 2 | **轮换密钥** | 预提交的下一个签名密钥，在轮换时揭示 | | 3 | **恢复密钥** | 仅用于恢复事件，最高权限 | ### 事件类型 事件类型值在序列化形式中是版本限定的（例如 `kels/v1/icp`）。 | 类型 | 描述 | 所需签名 | |------|------|----------| | `icp` | 初始——创建 KEL | 签名密钥 | | `dip` | 委托初始——创建委托 KEL | 签名密钥 | | `rot` | 轮换——轮换签名密钥 | 轮换密钥 | | `ixn` | 交互——锚定外部数据 | 签名密钥 | | `ror` | 轮换恢复——轮换恢复密钥 | 轮换密钥 + 恢复密钥 | | `rec` | 恢复——从分歧中恢复 | 轮换密钥 + 恢复密钥 | | `cnt` | 争议——永久冻结 KEL | 轮换密钥 + 恢复密钥 | | `dec` | 停用——结束 KEL | 轮换密钥 + 恢复密钥 | ### 泄露场景 | 泄露的密钥 | 攻击者可以 | 所有者恢复 | |------------|------------|------------| | 仅签名 | 签署 `ixn` 事件 | `rec` 事件恢复 KEL | | 轮换 | 签署 `rot`，然后任何事件 | `rec` 事件恢复 KEL | | 轮换 + 恢复 | 完全控制 | `cnt` 事件冻结 KEL | ## 功能 ### 核心功能 - **密钥事件日志**，完整生命周期：初始、轮换、交互、委托、恢复、争议、停用 - **分歧检测和恢复**——冲突事件存储在 KEL 中，通过加密方式解决 - **类型安全验证**——`KelVerification` 令牌在编译时强制执行；未验证的数据不能用于安全决策 - **自寻址标识符（SAID）**——通过 Blake3-256 内容寻址，采用 CESR 编码 ### 凭证和策略 - **凭证框架**（[kels-creds](docs/design/creds.md)）——签发、基于模式的紧凑披露，以及针对 KEL 锚点的验证 - **策略引擎**（[kels-policy](docs/design/policy.md)）——可组合信任策略，支持 `endorse`、`delegate`、`threshold`、`weighted` 和嵌套 `policy` 引用；软/硬/免疫投毒 - **复制的自寻址数据存储**（[sadstore](docs/design/sadstore.md)）——内容寻址对象（MinIO）+ 认证链式记录（PostgreSQL），通过 gossip 复制 ### 加密交换 - **ESSR 认证加密**（[kels-exchange](docs/design/exchange.md)）——Encrypt-Sender-Sign-Receiver，通过 ML-KEM + AES-GCM-256 + ML-DSA 提供四种不可伪造属性 - **凭证交换消息**——IPEX 风格协议（Apply/Offer/Agree/Grant/Admit/Reject），具有链式、自寻址交换线程 - **邮件服务**（[mail](docs/design/mail.md)）——加密消息传递，具有每发送者/每 IP 速率限制、存储上限、blob 完整性验证和基于 gossip 的元数据复制 ### 基础设施 - **Gossip 复制**（[gossip](docs/gossip.md)）——HyParView + PlumTree，采用 ML-KEM-768/1024 密钥交换 + ML-DSA-65/87 相互认证 + AES-GCM-256 加密 - **联邦注册表**（[federation](docs/federation.md)）——Raft 共识，多方投票处理节点生命周期；编译时信任锚点 - **自动密钥轮换**——HSM 后端服务按可配置计划（默认 180 天）轮换签名密钥，每三次轮换覆盖一次恢复密钥 - **服务端缓存**——Redis + W-TinyLFU 本地缓存，用于高吞吐量部署 ### 后量子密码学 - **签名：**所有客户端和基础设施使用 ML-DSA-65 或 ML-DSA-87（FIPS 204）。移动客户端可以使用 P-256 作为后备 - **密钥交换：**ML-KEM-768 或 ML-KEM-1024（FIPS 203），通过临时密钥对实现前向保密 - **Gossip 传输：**ML-KEM + ML-DSA + BLAKE3 KDF + AES-GCM-256 - **HSM：**实现 ML-DSA-65 和 ML-DSA-87 的 PKCS#11 cdylib（生产环境中将 .so 路径替换为真实 HSM） - **预轮换承诺**本质上具有后量子安全特性——BLAKE3 轮换哈希在轮换发生前不会透露任何关于下一个密钥的信息 ### 平台支持 - **密钥提供者：**软件密钥、macOS/iOS Secure Enclave、PKCS#11 HSM、可扩展的 `KeyProvider` trait - **客户端：**Rust CLI、Swift（iOS/macOS）、C FFI 绑定（支持任何语言） - **目标平台：**原生（Linux、macOS、Windows）、WebAssembly（浏览器/wasm） ## 快速开始 ### 单节点（开发） 单个 KELS 节点提供完整的 KEL API，无需 gossip 或 federation——只有 kels 服务、PostgreSQL 和 Redis： ``` garden deploy --env=standalone ``` `make deploy-fresh-node` 约在 2.5 分钟内部署完成。`make test-node` 部署并针对它运行测试。 ### 完整联邦 `make deploy-fresh-federation` 约在 10 分钟内部署整个联邦（3+1 个注册表，6 个 gossip 节点）。`make test-federation` 约在 35 分钟内部署并运行完整测试套件，在 Kubernetes 中留下一个可工作的堆栈。 有关两阶段部署过程（独立注册表、收集前缀、重编译包含信任锚点、联邦化）的详细信息，请参阅[部署](docs/deployment.md)。 ### 构建 ``` make build # Build all packages make all # Full checks: format, deny, clippy, test, build make fmt # Format code make clippy # Run clippy lints make test # Run tests make deny # Check dependencies (requires cargo-deny) make coverage # Per-file coverage with cargo-llvm-cov ``` ### 集成测试 需要 [Garden](https://garden.io) >= 14.20 和本地 Kubernetes 集群（Docker Desktop、minikube、kind 等）。 ``` make deploy-fresh-node # Deploy standalone node (~2.5 min) make deploy-fresh-federation # Deploy full federation (~10 min) make test-node # Deploy + test standalone (~5 min) make test-federation # Deploy + full test suite (~35 min) # iOS 客户端（macOS — 先配置 /etc/hosts） make ios-simulator ``` ## 项目结构 ``` kels/ ├── lib/ │ ├── kels/ # Core library (types, verification, client, crypto, cache) │ ├── derive/ # Derive macros for storage traits │ ├── creds/ # Credential framework (issuance, disclosure, verification) │ ├── policy/ # Policy framework (composable trust policies, DSL) │ ├── exchange/ # Exchange protocol (ESSR encryption, messaging, mail types) │ ├── ffi/ # FFI bindings (Swift/C interop) │ ├── gossip/ # Custom gossip protocol library (HyParView + PlumTree) │ └── mock-hsm/ # Mock HSM PKCS#11 cdylib (ML-DSA-65/ML-DSA-87) ├── services/ │ ├── kels/ # KEL HTTP API (event submission, verification, retrieval) │ ├── sadstore/ # Replicated self-addressed data store (MinIO + PostgreSQL) │ ├── mail/ # Encrypted message delivery service │ ├── gossip/ # Gossip service (cross-deployment KEL/SAD/mail sync) │ ├── registry/ # Federation registry (Raft consensus, peer voting) │ ├── identity/ # Registry identity service (HSM-backed KEL management) │ ├── minio/ # MinIO configuration (S3-compatible object storage) │ ├── postgres/ # PostgreSQL configuration │ └── redis/ # Redis configuration ├── clients/ │ ├── cli/ # Command-line interface │ ├── ios/ # Swift client (iOS/macOS) │ ├── bench/ # Benchmarking tool │ └── test/ # Integration test scripts/container └── docs/ # Documentation ``` ## 部署拓扑### 注册表节点 每个注册表运行：`identity`、`registry`、`postgres`、`redis` ### Gossip 节点 每个 gossip 节点运行：`identity`、`kels`（2 个副本）、`gossip`、`sadstore`、`mail`、`postgres`、`redis`、`minio` ## 从主机查询 要使用 CLI 或 iOS 应用针对本地部署，需要配置主机名解析和入口。 ### /etc/hosts ``` 127.0.0.1 kels.node-a.kels 127.0.0.1 kels.node-b.kels 127.0.0.1 kels.node-c.kels 127.0.0.1 kels.node-d.kels 127.0.0.1 kels.node-e.kels 127.0.0.1 kels.node-f.kels 127.0.0.1 sadstore.node-a.kels 127.0.0.1 sadstore.node-b.kels 127.0.0.1 sadstore.node-c.kels 127.0.0.1 sadstore.node-d.kels 127.0.0.1 sadstore.node-e.kels 127.0.0.1 sadstore.node-f.kels 127.0.0.1 mail.node-a.kels 127.0.0.1 mail.node-b.kels 127.0.0.1 mail.node-c.kels 127.0.0.1 mail.node-d.kels 127.0.0.1 mail.node-e.kels 127.0.0.1 mail.node-f.kels 127.0.0.1 registry.registry-a.kels 127.0.0.1 registry.registry-b.kels 127.0.0.1 registry.registry-c.kels 127.0.0.1 registry.registry-d.kels ``` ### 入口控制器 某些版本的 Garden 将 Traefik 入口服务创建为 `ClusterIP` 而非 `LoadBalancer`。在 Docker Desktop 上，这会阻止主机访问。如果从 `curl` 收到空响应，请运行： ``` make fix-ingress ``` ## 与 KERI 的差异 全面比较请参阅 [KERI vs KELS 比较分析](docs/keri-comparison.md)。 KELS 大量借鉴了 KERI 的核心概念和术语。在发现 KERI 后，我发现最有用的两个东西是创建具有自寻址标识符的防篡改数据，以及预轮换承诺。 我使用 Base64 CESR 编码数据，主要是为了简化开发。未来可能会更改编码。 ### 主要差异 如果发生分歧，单个分歧事件会被接受到 KEL 中，而不是被拒绝。当发生这种情况时，在分歧解决之前不允许追加新事件。 ### 其他显著差异 - **前缀派生**：KEL 的"前缀"最初在 KERI 中命名，旨在传达该值是密钥事件链中的第一个 SAID，位于序列之前。现在，我已更改了算法（在 `verifiable-storage-rs` 中），它们不再是相同的值。为什么？现在它们的计算方式几乎相同，但前缀在算法中先于 said 派生，这意味着无法将标识密钥事件的裸 SAID 与该事件的所有者关联起来——这在某些情况下是一种改进。我们可能需要重新审视整个代码库中的名称。您仍然可以证明给定完整事件，前缀是与 said 一起派生的。 - **无见证人或收据**：KERI 依赖指定的证人池为事件签名收据。KELS 用基于 gossip 的复制和注册表锚定的节点允许列表取代了这一点——gossip 网络内的信任来自针对编译内注册表前缀的 KEL 验证。 - **分歧是可观察的，而非私有的**：在 KERI 中，重复是通过比较不同来源的日志在本地检测的。在 KELS 中，分歧直接存储在 KEL 中并通过 gossip 传播到所有节点——这是一个公开的、网络范围的信号。 - **恢复和争议协议**：KELS 定义了显式的 `rec`（恢复）和 `cnt`（争议）事件类型。恢复支持合法所有者解决分歧。当双方都持有恢复密钥时，争议会永久冻结 KEL——这是 KERI 没有正式定义的结果。 - **Gossip 复制模型**：KEL 同步通过 gossip 公告（`prefix:said` 对）和基于 HTTP 的事件获取进行，而不是 KERI 的证人收据协议。 ## 路线图 1. 为 mail、sadstore 和 kels 添加可选访问控制 2. 构建示例应用 3. 添加 Android SDK 4. 重新审视分布式环境中的穷举分歧协调证明 5. 清理和自审计 6. 第三方审计 7. 标准提案（IETF Internet-Draft 或等效方案） 8. DID 方法规范 ## 安全模型 ### 数据验证原则 KELS 中所有记录的数据都是 KEL 支持的，并在使用前独立验证： - **摄入时验证**：每当服务从外部来源（对等方、联邦、网络）摄入数据时，它会在缓存或持久化之前验证数据的真实性和来源。对于对等方数据，这意味着完整验证对等方记录链、提案 DAG、锚定在注册表 KEL 中的投票，以及对等方自己的 KEL 结构。 - **连接时认证**：当潜在对抗性对等方连接时，握手由已验证的数据支持——对等方的签名根据其 KEL 中的当前公钥进行检查，该公钥在摄入时已验证。 - **刷新时重新验证**：当重新获取对等方的 KEL（例如密钥轮换后）时，KEL 结构在更新任何缓存状态之前会被完全验证。 - **临时数据是例外**：只有临时协议消息（握手、gossip 公告）免于锚定。所有持久化的数据都是 KEL 支持的。 ### 自动密钥轮换 身份服务（由具有 HSM 后端密钥的注册表和 gossip 节点使用）运行自动轮换循环，定期检查当前 HSM 密钥绑定是否到期需要轮换。检查周期（`IDENTITY_ROTATION_CHECK_PERIOD_MINUTES`，默认：360）和轮换间隔（`IDENTITY_ROTATION_INTERVAL_DAYS`，默认：180）都是可配置的。当轮换到期时，它使用自动选择轮换类型的计划模式：每三次轮换是恢复密钥轮换（`ror`），其余是标准签名密钥轮换（`rot`）。这确保了签名密钥和恢复密钥都会定期刷新，无需手动干预。 所有 KEL 管理操作——自动和手动——都通过单一 `perform_kel_operation` 代码路径进行，该路径就地更新内存中的密钥提供程序，保持服务器的签名状态一致。管理端点（`POST /api/v1/identity/kel/manage`）需要针对身份自己的 KEL 验证的签名请求。 ### 主动保护 - HSM 后端服务自动轮换签名密钥（可配置间隔，默认 180 天）和恢复密钥（每三次轮换） - 通过管理 CLI 提供手动轮换，可立即刷新密钥 - 终端用户客户端应定期轮换密钥（建议：签名每 1-3 个月，恢复每 3-12 个月） - 尽可能使用硬件后端密钥（Secure Enclave、HSM） ## 开发 ### 前置条件 - Rust 2024 edition - `cargo-deny`（用于依赖审计）：`make install-deny` 对于集成测试： - [Garden](https://garden.io) >= 14.20 - 本地 Kubernetes 集群（Docker Desktop、minikube、kind 等） ### IDE 设置 对于带有 rust-analyzer 的 VSCode： ``` cp -r .vscode.example .vscode ``` 这为 rust-analyzer 提供所需的环境变量（如 `TRUSTED_REGISTRY_PREFIXES`），用于分析而不影响实际构建。 ### 压力测试 ``` # 重复对抗性、gossip 和 bootstrap 测试 for i in {1..10}; do echo && echo "run $i" && echo && kubectl exec -n node-a -it test-client -- ./test-adversarial.sh && kubectl exec -n node-a -it test-client -- ./test-adversarial-advanced.sh && kubectl exec -n node-a -it test-client -- ./test-gossip.sh && kubectl exec -n node-a -it test-client -- ./test-bootstrap.sh || break done # 跨节点一致性检查 kubectl exec -n node-a -it test-client -- ./test-consistency.sh ``` ### 开发工具 CLI 包含用于测试的对抗模拟工具（需要 `dev-tools` 特性）： ``` cargo build --package kels-cli --features dev-tools kels-cli adversary inject --prefix --events ixn,rot ``` ## 文档 ### 架构和设计 - [KEL 合并协议](docs/design/merge.md)——事件提交和合并逻辑 - [KEL 验证](docs/design/verification.md)——完整性和真实性验证 - [流式验证](docs/design/streaming-verification-architecture.md)——分页验证，无需加载完整 KEL - [分歧检测和恢复](docs/design/divergence-detection.md)——分歧协议 - [恢复工作流](docs/design/recovery-workflow.md)——恢复和协调程序 - [安全不变量](docs/design/security-invariant.md)——数据库信任模型和验证类别 ### 服务和协议 - [Gossip 协议](docs/gossip.md)——跨部署同步 - [节点注册表](docs/registry.md)——节点注册、发现和引导同步 - [多注册表联邦](docs/federation.md)——具有 Raft 共识的联邦注册表 - [联邦状态机](docs/design/federation-state-machine.md)——Raft 日志、提案和投票 - [安全注册](docs/design/secure-registration.md)——HSM 后端身份和节点允许列表 - [API 端点](docs/endpoints.md)——完整端点参考 ### 凭证和交换 - [凭证框架](docs/design/creds.md)——签发、压缩、披露和验证 - [策略框架](docs/design/policy.md)——可组合信任策略和 DSL - [SAD 存储](docs/design/sadstore.md)——复制的自寻址数据存储 - [交换协议](docs/design/exchange.md)——ESSR 认证加密和凭证交换 - [邮件服务](docs/design/mail.md)——加密消息传递 ### 运维 - [部署](docs/deployment.md)——信任锚点、联邦部署和配置 - [运维](docs/operations.md)——日常运维程序 - [注册表移除](docs/design/registry-removal.md)——联邦成员停用 - [拒绝阈值](docs/design/rejection-threshold.md)——节点提案拒绝机制 ### 安全分析 - [节点攻击面](docs/analysis/node-attack-surface.md)——KELS 数据平面服务安全分析 - [注册表攻击面](docs/analysis/registry-attack-surface.md——联邦和注册表安全分析 - [协议攻击面](docs/analysis/protocol-attack-surface.md)——KEL 协议安全分析 - [KERI vs KELS 比较分析](docs/keri-comparison.md)——安全、架构和部署比较 ### 其他 - [代码审计](docs/claudit/)——分支级代码审计历史 ## 生产就绪性 提供的 Garden 配置是一个测试工具，而非生产部署模板。本项目仍在进行中，在任何生产部署之前需要解决以下事项： ### 基础设施加固 - **真实 HSM**：当前部署使用 `kels-mock-hsm`（一个 PKCS#11 cdylib），带有硬编码 PIN。生产环境需要将 PKCS#11 .so 路径（`PKCS11_LIBRARY_PATH`）交换为真实 HSM 的 PKCS#11 库（CloudHSM、YubiHSM、Thales Luna 等） - **密钥管理**：数据库凭证、HSM PIN 和其他密钥是硬编码的或作为纯环境变量传递。使用密钥管理器（Vault、AWS Secrets Manager 等） - **数据库加固**：PostgreSQL 使用默认超级用户凭证运行，无复制、无备份策略、无静态加密。连接池大小未配置 - **Redis 凭证**：Redis 使用具有最小权限命令集和密钥模式隔离的每服务 ACL 用户，并启用了 RDB 持久化。但是，ACL 密码是通过 Garden 模板变量配置的——生产环境应使用密钥管理器管理 Redis 凭证 - **容器安全**：所有容器以 root 身份运行，无 `securityContext`、无只读文件系统、无除内存限制外的资源配额 - **网络策略**：未定义 Kubernetes NetworkPolicies——集群中的任何服务都可以访问所有其他服务。安全模型不依赖网络隔离来保证数据完整性（所有数据都是端点可验证的），但仍建议使用网络策略来限制爆炸半径并保护 pod 内部服务（identity） - **内部服务 TLS**：数据平面通信是纯文本 HTTP，这是可接受的设计——所有数据都是公开的且端点可验证（加密签名 + SAID 链式）。联邦 RPC 使用 `SignedFederationRpc` 保证完整性，gossip 使用 ML-KEM-768/1024 + ML-DSA-65/87 + AES-GCM-256 进行认证加密。TLS 仅需用于内部服务的深度防御，这些服务携带密钥（Redis、PostgreSQL 连接） ### 运维差距 - **审计日志**：没有针对认证失败或敏感操作的结构化审计跟踪（节点更改通过 Raft 日志跟踪） - **可观测性**：无指标收集（Prometheus）、无分布式跟踪 - **混沌和弹性测试**：基于 DNS 的故障注入（重新同步/重试队列）已测试。网络分区模拟、节点故障恢复、分裂脑场景和数据库故障转移尚未系统测试 ### 审计 - **安全审计**：密码学协议和实现需要独立审查 - **零信任验证**：从存储（PostgreSQL、Redis、Raft 状态机）读取的所有数据在信任决策之前都会通过加密重新验证。提案 DAG 在每个信任点都会完全验证（结构完整性、KEL 锚定、投票锚定）——gossip 允许列表刷新、客户端发现、注册表 `verify_and_authorize` 和 Raft 日志重放。阈值和成员集从编译内的 `trusted_prefixes()` 派生，而非从响应中派生。这是已实现的，但尚未独立审计 ## 许可证 MIT

标签：DKMI, KERI, WebOfTrust, 事件日志, 便携式身份, 分布式密钥基础设施, 分布式账本, 分歧检测, 加密身份, 去中心化身份, 可视化界面, 多云身份, 子域名突变, 密码学, 密钥轮换, 恢复机制, 手动系统调用, 抗审查, 搜索引擎查询, 测试用例, 网络安全, 联邦系统, 身份管理, 通知系统, 隐私保护, 零信任架构, 预轮换承诺