masoud-kaderpur/CrypticCore-Engine

# CrypticCore Engine     ## CrypticCore 是一个基于 Java 的高性能加密引擎，专为内存高效的文件 转换而设计。它实现了将加密逻辑与数据流处理分离的解耦架构，并通过 OpenTelemetry 丰富了生产级、厂商中立的分布式追踪。 ## 1. 理论基础 ### 1.1 转换（XOR 逻辑） 该引擎利用按位**异或 (XOR)**运算。鉴于 XOR 是一种对合运算，该转换是自反的，允许使用相同的加密和解密逻辑。该运算定义为： $$P \oplus K = C$$ $$C \oplus K = P$$ ### 1.2 密钥流（模运算） 为了处理明文长度超过密钥长度的数据流，实现了循环密钥调度： $$i_{key} = i_{file} \pmod{L_{key}}$$ ## 2. 实现细节 ### 2.1 Java 类型处理（符号扩展缓解） 为了防止在从 `byte` 隐式提升为 32 位 `int` 期间发生意外的符号扩展，应用了 $0xFF$ 的位掩码以保持 8 位完整性： $$Result = (P \land 0xFF) \oplus (K \land 0xFF)$$ ### 2.2 内存效率与性能 * **O(1) 空间复杂度**：以离散的 **8 KB 缓冲区**处理数据，允许处理任意大小的文件（已测试最高达 5 GB），且 RAM 占用极小。 * **吞吐量**：针对高速 I/O 进行了优化，在标准硬件上实现了超过 **400 MB/s** 的速度。 * **分布式追踪**：原生的 OpenTelemetry 监测可追踪执行流、文件大小和流状态，且不会阻塞性能。 ### 2.3 健壮性与安全性 * **原子写入**：采用 `.tmp` 文件暂存策略。最终输出仅在成功完成后通过原子 `move` 操作创建，防止在崩溃或断电期间发生数据损坏。 * **内存清理**：加密密钥在使用后立即通过 `Arrays.fill()` 在 JVM 堆中被显式覆盖，以缓解内存转储攻击。 * **头部验证**：严格的魔数和版本检查可防止处理不兼容或损坏的文件。 ### 2.4 SOLID 架构与解耦 该引擎基于 SOLID 原则构建，以确保可扩展性和可测试性： * **单一职责原则 (SRP)**：I/O 处理、头部验证、指标记录和加密逻辑被严格分离到专门的组件中（`HeaderHandler`、`FileValidator`、`EncryptionEngine`）。 * **依赖倒置原则 (DIP)**：该引擎不依赖于特定的 UI 或监控平台。它通过 `ProgressObserver` 接口传达进度，并通过构造函数注入接受厂商中立的 Micrometer `MeterRegistry`，使其与 Prometheus、Dynatrace 或 Datadog 兼容。 * **接口隔离原则：**加密策略通过 `CipherAlgorithm` 接口注入，使得引擎无需修改核心流处理逻辑即可开放支持未来的算法（例如 AES）。 ## 3. 云原生与容器化 该引擎已完全容器化，以确保环境的一致性和安全性。 * **多阶段 Docker 构建**：使用构建器阶段（Maven）和加固的运行时阶段（JRE Alpine），以最小化镜像大小和攻击面。 * **安全加固**：容器执行被限制为**非 Root 用户**。 * **编排栈**：包含一个统一的 `docker-compose.yml`，用于启动本地兼容 OpenTelemetry 的后端（Jaeger），以通过 OTLP 网络层接收和可视化应用程序性能追踪。 ## 4. 文件格式规范 每个加密文件均以一个 4 字节的元数据头部开始。 | 偏移量 | 长度 | 描述 | 值 (Hex / ASCII) | |:-------|:--------|:-------------------|:--------------------| | 0x00 | 3 Bytes | 魔数 (CCE) | `0x43 0x43 0x45` | | 0x03 | 1 Byte | 格式版本 | `0x01` | ## 5. 使用方法 ### 5.1 本地执行 ``` java -jar target/CrypticCore-jar-with-dependencies.jar

``` ### 5.2 Docker 执行 ``` docker compose run --rm engine /app/data/input.txt /app/data/output.enc ``` **参数：** * **mode:** `ENCRYPTION` 或 `DECRYPTION`（不区分大小写）。 * **input:** 源文件路径。 * **output:** 转换后文件的最终目标路径。 * **key:** 用于转换的密钥。 ## 6. 质量保证 该项目遵循严格的测试策略，以确保数据完整性和系统稳定性： ### 6.1 自动化质量门禁 (CI/CD) 与可观测性 该项目利用 **GitHub Actions** 进行持续集成。每次推送和拉取请求都会自动进行以下验证： * **编译与测试套件：**确保在 Java 21 上实现 100% 的构建稳定性。 * **Checkstyle (Google Java 规范)：**严格执行 [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)。 * **测试覆盖率 (JaCoCo)：**设置了质量门禁，以确保最低 **85% 的代码覆盖率**。 * **混合结构化日志：**引擎会自动检测其环境，并在 Docker 内运行时切换为结构化 JSON 日志。 ### 6.2 测试策略 * **单元测试：**验证了对合属性和边缘情况（字节边界）。 * **集成测试：**对自定义 `.cce` 格式和头部完整性进行端到端验证。 * **韧性：**验证原子写入操作并防止数据截断。 * **端到端周期：**成功对真实文件流进行加密和解密。 * **原子完整性：**验证 `.tmp` 暂存和原子移动策略。 * **错误韧性：** *检测截断文件（预期大小与实际大小检查）。 * 防止原地损坏（同文件验证）。 * 健壮的头部和版本验证。 ## 7. 项目架构 该引擎被结构化为专门的包，以确保高可维护性和关注点分离： * **`at.tuwien.crypticcore.core.domain`**：核心契约、领域异常和算法策略（CipherAlgorithm）。 * **`at.tuwien.crypticcore.core.engine`**：编排层。无状态、性能优化的流式密码执行。 * **`at.tuwien.crypticcore.infrastructure.io`**：处理特定格式头部（`HeaderHandler`）、快速失败（Fail-fast）验证（`FileValidator`）的基础设施层。 * **`at.tuwien.crypticcore.infrastructure.observability`**：管理 OpenTelemetry SDK 自动配置初始化的核心引导层。 ## 8. 遥测与 Jaeger 流水线分步指南 按照以下步骤启动本地可观测性环境，执行加密操作，并可视化您的应用程序追踪。 ### 8.1 Docker Compose 环境配置 确保您的项目根目录包含以下现代化的 docker-compose.yml： ``` services: engine: build: . image: cryptic-core-engine:latest volumes: - .:/app/data extra_hosts: - "host.docker.internal:host-gateway" environment: - OTEL_SERVICE_NAME=cryptic-core - OTEL_TRACES_EXPORTER=otlp - OTEL_METRICS_EXPORTER=none - OTEL_LOGS_EXPORTER=none jaeger: image: jaegertracing/all-in-one:1.60 container_name: cc-jaeger ports: - "16686:16686" - "4317:4317" - "4318:4318" environment: - COLLECTOR_OTLP_ENABLED=true ``` ### 8.2 启动追踪后端 在您的 Docker 守护进程中启动 Jaeger： ``` docker compose up -d jaeger ``` ### 8.3 生成本地数据并运行引擎 生成一个大型测试文件（例如 100 MB 或 1 GB）以对吞吐量和延迟进行基准测试。 Linux/macOS: ``` dd if=/dev/urandom of=input.txt bs=10m count=100 ``` Windows(PowerShell): ``` $fs = New-Object System.IO.FileStream("large_input.txt", [System.IO.FileMode]::Create); $fs.SetLength(100MB); $fs.Close() ``` 执行转换循环。我们通过标准的环境标志指示 OpenTelemetry 自动配置器，将上下文和流数据接入本地守护进程： ``` mvn clean package # Windows (PowerShell) $env:OTEL_SERVICE_NAME="cryptic-core" $env:OTEL_TRACES_EXPORTER="otlp" $env:OTEL_METRICS_EXPORTER="none" $env:OTEL_LOGS_EXPORTER="none" java -jar target/CrypticCore-jar-with-dependencies.jar ENCRYPTION input.txt output.enc secretkey # Linux / macOS OTEL_SERVICE_NAME=cryptic-core \ OTEL_TRACES_EXPORTER=otlp \ OTEL_METRICS_EXPORTER=none \ OTEL_LOGS_EXPORTER=none \ java -jar target/CrypticCore-jar-with-dependencies.jar ENCRYPTION input.txt output.enc secretkey ``` ### 8.4 在浏览器中检查追踪 1. 打开浏览器并导航至 http://localhost:16686。 2. 从左侧面板的 Service 下拉菜单中选择 cryptic-core。 3. 点击 Find Traces。 4. 点击相应的追踪块以展开执行生命周期。检查自定义属性（例如 cryptic.file.size 或 cryptic.algorithm）以及您的时间线事件（inputs_verified、header_written、streaming_completed）。 累积数据量面板：

标签：GET参数, OpenTelemetry, 内存优化, 加密解密, 域名枚举, 流式处理, 版权保护, 用户代理, 请求拦截