liesware/Vectis

# Vectis

Vectis 是一个用于敏感数据工作流的**密码学数据保护工具包**。 其核心理念很简单：TLS 保护的是连接，但在传输会话结束后，敏感数据通常仍会继续在应用程序、服务、队列、存储、日志、工作进程和最终系统中流转。Vectis 探索的是如何在数据对象或 payload 离开传输层之后对其进行保护。 目前，它通过统一的 HTTP 和 CLI 接口提供了混合加密、混合签名、受保护的消息、FF1 格式保留加密、可逆随机 token 化、MAC profile、盲索引、签名配置、API-key 权限、加密存储、健康探测、metrics、结构化日志以及专用的审计日志流。 本项目处于实验阶段，应被视为仍在开发中。**请勿使用 Vectis 来保护真实的敏感数据。** ## 设计理念 Vectis 尽量遵循 Unix 哲学。Peter H. Salus 在 1994 年对此进行了总结，并归功于 Doug McIlroy： ``` Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface. ``` Vectis 的职责非常单一：为敏感数据工作流提供可组合的密码学保护。它并不试图取代 TLS、KMS、HSM、数据库、访问控制或传统的 DLP 工具。这些系统已经各自承担了相应的职责。 Vectis 暴露了 HTTP、CLI 命令、JSON、OpenAPI、日志和 metrics，因为简洁的接口更容易被检查、自动化和组合。未来的功能（例如更强的集群、HSM/KMS 支持、mTLS 或额外的分布式存储）只应在运行环境需要时才加入，而不是作为产品层级或装饰性的复杂性存在。 ## 为什么选择 Vectis？ 现代系统已经采用了许多重要的安全控制措施： - TLS； - 加密磁盘； - 云端 KMS； - HSM； - 密钥管理器； - 访问控制； - 数据库加密； - 传统的 DLP 工具。 这些控制措施是必不可少的，但敏感数据仍然可能以明文形式出现在应用程序的 payload、日志、队列、数据库、备份、内部 API 以及临时处理步骤中。 Vectis 探索了一个不同的问题： ## Vectis 目前提供的功能 Vectis 目前提供了一个 HTTP 服务和 CLI，用于实验密码学数据保护原语和工作流。 **密码学** - 通过 XECDH + ML-KEM 建立混合后量子密钥； - 使用 EdDSA 和 ML-DSA 进行双重签名，两者均需验证； - 对受保护的 payload 进行认证加密； - 带有显式协议版本绑定的规范化 JSON 签名； - 可选的 crypto profile（参见 [Crypto Profiles](#crypto-profiles)）。 **协议与信任** - Vectis 实例之间受保护的消息传递，在解密前进行验证； - 一个经过运营者签名的配置文件（路由、远程路由、权限、FPE profile、token 化 profile 和 MAC profile）；其注册的 `remote_routes` 是对端公钥的唯一来源——不存在信任首次使用（trust-on-first-use）的路径； - 在最终交付给应用前进行本地重新加密：接收应用程序永远不会直接获取远程明文； - 通过 `kid` 发布公钥； - 用于本地受保护数据的内部加密/解密 endpoint； - 用于已签名字段 profile 的本地 FF1 格式保留加密； - 用于已签名 token profile 的本地可逆随机 token 化； - 用于已签名 MAC profile 的本地 MAC 创建/验证； - 复用已签名 MAC profile 并持久化确定性成员摘要的本地盲索引。 **密钥管理** - 加密的本地初始密钥材料； - 通过 HKDF 派生的内部密钥，用于存储加密和 API key 验证； - 操作密钥的创建和验证； - 加密的密钥生命周期元数据和运行时生命周期强制执行； - 以 SQLite/PostgreSQL 为后端的存储，在存储抽象层之后保存加密的操作密钥、加密的 token 化 payload 以及盲索引摘要。 **运维与可观测性** - 启动、存活和就绪健康探测； - 带有每个请求关联 ID 的专用安全审计日志流； - 用于操作可观测性的 Prometheus `/metrics` endpoint； - 本地 CLI 命令以及充当 HTTP API 客户端的 CLI 命令； - OpenAPI 和环境变量文档。 ## 高层级流程 ``` Application A | | private record / sensitive payload v Vectis A | | hybrid KEM + authenticated encryption + signatures v Vectis B | | verify + decrypt + local re-encrypt v Application B | | local decrypt through Vectis B v Recovered private record / sensitive payload ``` 接收应用程序不会直接收到远程明文。它收到的是本地加密交付物，必须向其本地的 Vectis 实例请求解密。 ## 临床数据交换演示 该代码库包含一个双站点的临床演示： - 诊所 A 读取一个患者记录的 JSON 文件。 - Vectis A 对记录进行保护并发送。 - Vectis B 对记录进行验证、解密，并为诊所 B 重新加密。 - 诊所 B 的最终应用调用本地 Vectis 进行解密并打印恢复的记录。 参见 [demo/message/README.md](demo/message/README.md)。 快速演示设置： ``` bash demo/message/setup.sh bash demo/message/create-keys.sh bash demo/message/configure-routes.sh ``` 然后运行这四个演示进程： ``` bash demo/message/start-vectis-a.sh bash demo/message/start-vectis-b.sh bash demo/message/start-app-a.sh bash demo/message/start-app-b.sh ``` 在诊所 A 的终端中： ``` clinic-a file: ../personaldata.json ``` ## 本地数据保护演示 该代码库还包括一个基于 SQLite 和 HTTP 的单节点本地演示。它展示了三种合成数据类别的字段级保护：信用卡 PAN、SSN 和银行账户值。 该演示演示了： - FPE 加密/解密； - 可逆 token 编码/解码； - MAC 创建/验证； - 盲索引创建/验证； - `/message/internal` 加密/解密； - 签名和验证。 参见 [demo/local/README.md](demo/local/README.md)。 快速本地演示设置： ``` bash demo/local/setup.sh bash demo/local/create-keys.sh bash demo/local/configure-config.sh ``` 然后运行本地 Vectis 实例和演示运行器： ``` bash demo/local/start-vectis.sh uv run demo/local/run-demo.py ``` ## 架构 Vectis 遵循简单的三层结构： - `core`：基础设施和可复用原语，例如配置、验证、crypto 辅助工具、日志、存储、路由和数据库访问。 - `ops`：应用程序操作和业务流程，例如初始化、密钥创建、签名、验证、受保护消息传递、FPE、token 化和测试。 - `io`：输入/输出适配器，例如 HTTP endpoint 和 CLI 命令。 其目的是将协议和业务逻辑排除在 HTTP 处理程序之外，并将底层可重用的原语排除在更高层级的操作流程之外。 ## 快速开始 要求： - 带有 `cargo` 的 Rust 工具链； - SQLite CLI (`sqlite3`)。 构建项目： ``` cargo build ``` 初始化本地加密密钥材料： ``` cargo run -- init ``` 该命令会打印输出： - `VECTIS_UNSEAL_KEY`：用于解密已配置的初始密钥文件； - `VECTIS_INIT_KEYS_FILE`：加密的初始密钥材料路径，默认为 `init.json`； - `VECTIS_APIKEY`：通过密码学随机数生成器生成的客户端密钥，以 `X-API-Key` 发送； - `VECTIS_APIKEY_HASH`：用于受保护的 HTTP endpoint 的服务端验证器。 对于本地开发，请将解封密钥保存在 `.unseal_key` 中： ``` printf '%s\n' '' > .unseal_key chmod 600 .unseal_key ``` 创建 SQLite 数据库文件和 schema： ``` mkdir -p src/db sqlite3 src/db/data.db < src/db/sqlite_schema.sql ``` 启动 HTTP 服务： ``` cargo run -- serve ``` 检查就绪状态： ``` cargo run -- health ready ``` 创建操作密钥： ``` cargo run -- keys create --tag payments --profile hybrid-performance-v1 ``` 列出内存中加载的公钥： ``` cargo run -- keys list ``` ## CLI 与 API CLI 主要是本地 Vectis 服务的 HTTP 客户端。 示例： ``` vectis version vectis health ready vectis apikey create vectis keys create --tag payments --profile hybrid-high-assurance-v1 vectis keys list vectis pub vectis fpe encrypt --file fpe-encrypt.json vectis token encode --file token-encode.json vectis mac create --file mac-create.json vectis mac verify --file mac-verify.json vectis message send --file send-message.json vectis message decrypt --file encrypted-message.json vectis config sign vectis config reload ``` 完整的 API 文档请参见 [doc/API.md](doc/API.md)。 ## 配置 运行时路由、远程对端、API-key 权限、FPE profile、token 化 profile 和 MAC profile 都位于一个**已签名的配置文件**（`config.json`，默认路径为 `VECTIS_CONFIG_PATH`）中，包含 `version`、`routes`、`remote_routes`、`permissions`、可选的 `fpe_profiles`、可选的 `tokenization_profiles` 以及可选的 `mac_profiles` 部分。盲索引复用 `mac_profiles`；没有单独的 `index_profiles` 部分。编辑它，然后使用 `vectis config sign` 进行签名。完整的 schema（每个字段、允许的值以及可选的对端 `public_keys`）记录在 [doc/API.md](doc/API.md) 的 **Configuration File (`config.json`)** 部分。 Vectis 会首先从进程环境变量读取进程/环境设置，其次是 `.env`，最后是内置的默认值。 所有 Vectis 专用的变量都使用 `VECTIS_` 前缀。 运行本地实例所需的基本要素： - `VECTIS_HTTP_BIND_ADDR`：监听地址，默认 `127.0.0.1:3000`； - `VECTIS_MODE`：`dev`（HTTP）或 `prod`（HTTPS，需要 TLS 证书和密钥）； - `VECTIS_INIT_KEYS_FILE`：加密的初始密钥材料，默认 `init.json`； - `VECTIS_UNSEAL_KEY_FILE`：解封密钥文件，默认 `.unseal_key`； - `VECTIS_STORAGE`：默认为 `sqlite`，或用于共享存储的 `postgres`； - `VECTIS_SQLITE_PATH`：SQLite 操作密钥存储，在开发构建中默认为 `src/db/data.db`； - `VECTIS_POSTGRES_DSN`：当 `VECTIS_STORAGE=postgres` 时的 PostgreSQL DSN； - `VECTIS_CONFIG_PATH`：已签名的配置文件，默认 `config.json`。 完整列表和预期值请参见 [doc/ENV.md](doc/ENV.md)。 ## Crypto Profile `POST /keys` 支持 crypto profile： - `hybrid-performance-v1`； - `hybrid-standard-v1`； - `hybrid-high-assurance-v1`； - `hybrid-long-term-v1`。 默认情况下，Vectis 使用仅限 profile 的策略： ``` VECTIS_DEFAULT_CRYPTO_PROFILE=hybrid-performance-v1 VECTIS_CRYPTO_POLICY=profile-only ``` 在开发和测试中，可以通过以下方式启用单个算法的覆盖： ``` VECTIS_CRYPTO_POLICY=allow-overrides ``` ## FPE、Token 化、MAC 和盲索引 FPE、token 化、MAC 和盲索引均由 profile 驱动。Profile 仅从已签名的配置中加载，并且请求通过名称选择 profile。盲索引复用 MAC profile 并持久化生成的确定性摘要。 FPE 目前支持： ``` fpe-ff1-2025 ``` Token 化目前支持： ``` token-random-v1 ``` MAC 目前支持使用操作密钥哈希算法的 HMAC，或者当操作密钥使用相应的 SHA-3 哈希大小时，支持 `KMAC-224`、`KMAC-256`、`KMAC-384` 和 `KMAC-512`。MAC profile 的 `context` 值使用结构化标签，例如 `tenant=mx;field=pan;purpose=blind-index;version=1`。 CLI 可以在本地编辑这些 profile 部分： ``` vectis config fpe add --name patient-id-decimal-v1 --kid --alphabet 0123456789 --min-len 6 --max-len 32 --tweak-aad 'tenant=acme;field=patient_id;version=1' vectis config token add --name patient-id-token-v1 --kid --token-prefix tok_patient --token-len 32 --max-plaintext-len 1024 vectis config mac add --name pan-blind-index-v1 --kid --context 'tenant=mx;field=pan;purpose=blind-index;version=1' vectis config sign vectis config reload ``` ## 测试 完整的测试策略（包括 Rust 检查、使用 `uv` 的 Python HTTP 工作流、Schemathesis OpenAPI 模糊测试以及原生的 `cargo-fuzz` 目标）请参见 [doc/Test.md](doc/Test.md)。 ## 文档 - [doc/API.md](doc/API.md)：HTTP API 和 CLI 映射。 - [doc/CLI.md](doc/CLI.md)：CLI 行为、命令、输出和环境。 - [doc/ENV.md](doc/ENV.md)：环境变量和预期值。 - [doc/Test.md](doc/Test.md)：测试策略和测试命令。 - [doc/Clustering.md](doc/Clustering.md)：多节点行为和共享存储模型。 - [doc/HA_DR.md](doc/HA_DR.md)：高可用性、备份、还原和恢复限制。 - [doc/openapi.yaml](doc/openapi.yaml)：OpenAPI 规范。 - [doc/ThreatModel.md](doc/ThreatModel.md)：威胁模型、显式假设和局限性。 - [doc/Reference.md](doc/Reference.md)：架构和设计参考。 - [doc/Internal.md](doc/Internal.md)：实现流程和内部不变式。 - [doc/Design.md](doc/Design.md)：从该项目中提炼出的可重用设计原则。 - [demo/message/README.md](demo/message/README.md)：临床数据交换演示。 - [demo/local/README.md](demo/local/README.md)：本地 FPE、token 化、MAC、盲索引、内部消息和签名演示。 - [charts/vectis/README.md](charts/vectis/README.md)：Kubernetes Helm chart。 ## Vectis 不包含什么 Vectis 不能替代： - TLS； - KMS； - HSM； - 密钥管理器； - 数据库加密； - 访问控制； - 传统的 DLP 产品。 Vectis 目前不提供脱敏、Merkle 证明、防篡改审计链、SLH-DSA、Vault/KMS/HSM 自动解封或 mTLS。 Vectis 旨在通过探索针对敏感数据工作流的密码学保护来补充现有的安全控制措施。它应该与其他工具协同工作，而不是承担它们的责任。 ## 安全状态 Vectis 目前- 是实验性的； - 不完整； - 未经审计； - 尚未达到生产就绪状态； - 可能会发生重大设计变更。 请勿将 Vectis 用于真实的患者数据、生产密钥、财务记录或任何其他真实的敏感数据。 威胁模型、显式假设和已知局限性记录在 [doc/ThreatModel.md](doc/ThreatModel.md) 中。 ## 许可证 基于 Apache License, Version 2.0 授权

标签：加密工具, 可视化界面, 密码学, 手动系统调用, 测试用例, 网络安全, 自定义请求头, 逆向工具, 通知系统, 隐私保护