Quant-Off/entanglementlib

# EntanglementLib [](https://github.com/Quant-Off/entanglementlib) [](README_EN.md) [](LICENSE) [](https://github.com/Quant-Off/entanglementlib) [](https://discord.gg/9utg4hp3m8)  EntanglementLib 是一个旨在安全、快速地处理所有安全运算的库。通过连接的 [Rust 层（原生）](https://github.com/Quant-Off/entlib-native)，它提供了经典及抗量子密码学（Post-Quantum Cryptography, PQC）技术，并提供了使用这些技术的面向未来的 TLS 协议。 ## 技术 EntanglementLib 通过基于 **Rust 的原生** 层来执行所有的安全运算。原生层从根本上防止了由于 `heap` 内存分配引发的垃圾回收（Garbage Collection, GC）清理机制可能产生的所有安全弱点。它将 Java 端的敏感数据通过 `off-heap` 接收以执行任务，并通过调用者或被调用者模式立即安全地清除该指针的数据。 在 Java 端与原生层交互时，不使用 JNI（Java Native Interface）功能。核心技术是基于 [JEP 389](https://openjdk.org/jeps/389)、[JEP 454](https://openjdk.org/jeps/454) 改进方案的高级原生调用功能：Linker 和 FFM API（Foreign Function & Memory API），而在原生端，则通过封装的逻辑以 FFI（Foreign Function Interface）进行交互。 在该库内部，用户的数据不会以字节数组（`byte[]`）或字符数组（`char[]`）的形式进行管理。这些类型会被写入 `heap` 内存，从而将控制权交给 GC。代替这种原始的使用方式，可以使用 `SensitiveDataContainer` 对象。该对象接管敏感数据的所有权，并将其安全地传递给原生层，从而帮助实现安全高效的任务处理。更具体地说，该对象类似于 [Rust 的 RAII（Resource Acquisition Is Initialization）模式](https://doc.rust-lang.org/rust-by-example/scope/raii.html)，在实例化时获取资源，并在调用 `close()` 时释放资源。 ### 多模块 EntanglementLib 是一个多模块项目。各模块的职责被划分为任务及包含实用注解和各种便利工具的实用程序。注解和 core 模块在 security 模块中是核心使用的，但 security 模块绝对不会在其他模块中使用。 | 模块 | 功能 | |--------------------------|------------------------------------------------------------------| | `security` | 核心安全模块。提供了与原生层交互的逻辑，以及通过 FFI 集成的各种安全功能。 | | `core` | 提供管理异常、国际化及异步、分块任务、字符串、数据结构的实用功能。 | | `annotations` | 包含用于简化代码设计及降低用户代码理解复杂度的注解。 | | `internal-shared-server` | 包含构建和管理封闭环境基础设施的功能。 | ## 注意事项及安全提供者设置 **EntanglementLib（Java）中调用原生层（Rust）的安全功能尚未得到充分的密码学验证。** Team Quant 正在努力实现对 `entlib-native` 的全面验证。 您可以将 Rust 层中实现的“安全功能提供者”设置为使用“已验证的安全提供者”，而不是 `entlib-native`。 ### 提供者设置 通过 FFI 边界使用的所有安全功能（摘要、编码、AEAD、随机数）都可以通过 `CryptoProviderConfig` 来选择后端。选项如下： - `CryptoBackend#JDK_VERIFIED` - 使用 JDK 标准 JCA（`MessageDigest`、`Cipher`、`SecureRandom`、`java.util.Base64`、`HexFormat`）的已验证后端（**默认值**） - `CryptoBackend#ENTLIB_NATIVE` - `entlib-native` FFI 后端（未验证，仅供实验） - 注入用户自行实现的已验证提供者实例（例如：HSM、PKCS#11、内部验证库） 默认值为 **已验证的 JDK 后端**。因此，如果不进行额外设置直接初始化，将使用已验证的提供者，而不是未验证的原生提供者。 ``` // 1) 기본값 (전체 검증된 JDK 백엔드) EntanglementLibSecurityFacade.initialize( EntanglementLibSecurityConfig.create(null, HeuristicArenaFactory.ArenaMode.AUTO)); // 2) 전역 + 기능별 혼합 + 외부 JCA 공급자(BouncyCastle 등) + 커스텀 공급자 주입 CryptoProviderConfig providers = CryptoProviderConfig.builder() .useVerifiedProviders() // 전역 기본을 검증된 JDK로 .aead(CryptoBackend.ENTLIB_NATIVE) // AEAD만 네이티브로 (실험) .jcaProviderName("BC") // 검증 백엔드가 사용할 JCA 공급자명 .random(myVerifiedRandomProvider) // 난수는 사용자 정의 검증 공급자 .build(); EntanglementLibSecurityFacade.initialize( EntanglementLibSecurityConfig.create( nativeSpecContext, HeuristicArenaFactory.ArenaMode.AUTO, providers)); // 3) 전체 entlib-native (실험용) EntanglementLibSecurityConfig.create(nativeSpecContext, null, CryptoProviderConfig.nativeDefaults()); ``` ## 封闭网络共享服务器 `internal-shared-server`（ISS）模块是一个在封闭网络中供多个内部节点访问的安全共享服务器。它排除了公共互联网的 CA 信任链，使用预共享密钥（PSK）对双方进行相互认证，并且所有记录都受到 `ChaCha20-Poly1305` 的保护。由于仅凭已验证的 JDK 提供者即可运行，因此无需分发原生二进制文件即可使用。它通过代码级别的嵌入式 API（`ISSServer`·`ISSClient`）和 CLI 两种途径进行控制。 ### 准备可执行文件 生成应用程序发行版时，将创建执行脚本。 ``` ./gradlew :internal-shared-server:installDist # 生成位置 # internal-shared-server/build/install/internal-shared-server/bin/internal-shared-server # 为方便起见注册 alias（可选） alias iss="$(pwd)/internal-shared-server/build/install/internal-shared-server/bin/internal-shared-server" ``` 或者可以直接使用 Gradle 运行。 ``` ./gradlew :internal-shared-server:run --args="--help" ``` ### CLI 用法 ``` iss serve --port N [--bind 127.0.0.1] (--psk-file F | --psk-env VAR) [--max-conn 64] [--allow-nonloopback] [--allow-peer IP]... iss ping --port N [--host 127.0.0.1] (--psk-file F | --psk-env VAR) iss put --port N [--host H] (--psk-file F | --psk-env VAR) --key K (--value V | --value-file F | --stdin) iss get --port N [--host H] (--psk-file F | --psk-env VAR) --key K [--out FILE] iss del --port N [--host H] (--psk-file F | --psk-env VAR) --key K iss list --port N [--host H] (--psk-file F | --psk-env VAR) iss status --port N [--host H] (--psk-file F | --psk-env VAR) iss gen-psk [--bytes 32] [--out FILE] iss --help | --version ``` | 命令 | 说明 | |-----------|--------------------------------------------------| | `serve` | 绑定服务器并开始接受连接（按 Ctrl-C 退出） | | `ping` | 握手后检查服务器响应 | | `put` | 将值存储到键中（值可以是参数·文件·标准输入之一） | | `get` | 查询键的值（如果指定了 `--out` 则保存到文件，未指定则输出到标准输出，不存在时返回 1） | | `del` | 删除键 | | `list` | 输出已存储的键列表 | | `status` | 查询服务器状态 | | `gen-psk` | 使用安全随机数生成 PSK（如果没有 `--out` 则将 hex 输出到标准输出） | ### 快速开始 ``` # 1) 生成 PSK（raw 32字节密钥文件，以仅所有者权限保存） iss gen-psk --out infra.psk # 2) 启动服务器（默认 loopback） iss serve --port 8443 --psk-file infra.psk # 3) 在另一个终端中执行 client 命令 iss ping --port 8443 --psk-file infra.psk iss put --port 8443 --psk-file infra.psk --key greeting --value "Hello" iss get --port 8443 --psk-file infra.psk --key greeting iss list --port 8443 --psk-file infra.psk iss status --port 8443 --psk-file infra.psk iss del --port 8443 --psk-file infra.psk --key greeting # 通过环境变量传递 PSK export ISS_PSK=$(iss gen-psk) iss ping --port 8443 --psk-env ISS_PSK ``` ## TODO EntanglementLib 希望明确以下 TODO，以便将来能够投入到金融和安全基础设施的生产环境中使用。 - [ ] 为方便在封闭网络环境中使用而开发 Local Hosted Web - 目前 ISS 仅通过 CLI 和嵌入式 API（`ISSServer`·`ISSClient`）进行控制。尚无基于 Web 的管理控制台。 - [ ] 添加 TLS 通信逻辑 - ISS 的 PSK 相互认证 + ChaCha20-Poly1305 安全通道已完成实现。 - 虽然在 `security` 模块中添加了 `ExternalTLS` 外观骨架，但在 ML-KEM 密钥协商、ChaCha20-Poly1305 记录 AEAD 和 RNG nonce 生成暴露给原生 FFI 之前，握手将处于禁用（stub）状态。 - [ ] 准备并执行综合验证工作 - 添加了安全提供者 SPI（`CryptoProviderConfig`），以便能够选择已验证的 JDK 提供者（或自定义提供者），而不是未验证的原生提供者。`entlib-native` 本身的密码学验证仍在进行中。 - [x] 优化自定义异常 - 构建了分为 checked/unchecked 及 core/security 层级的异常体系，并集成了支持 i18n 的 `ExceptionLogger`。 - [ ] 应用 JPMS（即使在多模块内也实现包的模块化） - 待完成安全的封装和一致的调用（或使用）模式后，计划通过 JPMS 将封装的包作为模块进行管理。 - [ ] 最小化外部依赖 - 从 `1.1.0` 版本开始不再使用 `BouncyCastle` 依赖，并移除了 `Lombok` 依赖。目前，提供编写代码所需的一些实用工具的依赖仍然存在，但最终这些也将被最小化。 - [ ] 更新 `i18n` - `core` 已包含 `EntanglementLibCoreI18n` 以及 `en_US`·`ko_KR` 消息包。但是，根据配置自动应用各语言日志记录的集成功能仍需进一步完善。 ## 许可证 本项目遵循 `PolyForm Noncommercial License 1.0.0`。由于在本项目内同时管理着 `entlib-native`，许可证有时会被错误地标记为 `MIT`，但请注意，它仍然遵循 `PolyForm` 许可证。有关此许可证的更多详细信息，请参阅 [LICENSE](LICENSE) 文件。 # 更改日志 您可以在 [CHANGE.md](CHANGE.md) 文档中查看更改记录。此文档将在 `1.1.0` 版本发布时添加。

标签：FFM API, JS文件枚举, Rust, 内存安全, 可视化界面, 后台面板检测, 后量子密码学, 域名枚举, 安全基础设施, 密码学, 手动系统调用, 智能代码审计, 网络流量审计, 量子信息技术