框架初始化

README.md

@@ -10,3 +10,106 @@
 sudo apt-get install scons
 sudo apt-get install build-essential
 ```
+
+
+---
+
+# ZUC-256 Java 实现框架说明
+
+本工程提供了一个 **分层、模块化的 ZUC-256 流密码算法框架**，按照 C 参考实现逻辑翻译为 Java 版本，便于后续在 JavaCard 环境中移植。
+
+## 代码结构
+
+```
+com/iii/dragonstream/
+│
+├── Zuc256Tables.java      // 常量表（S盒、D数组）
+├── Zuc256State.java       // 内部状态（LFSR、R1、R2）
+├── Zuc256Util.java        // 工具类（U32转换、位运算、线性变换、打印）
+├── Zuc256Core.java        // 算法核心（初始化、密钥字生成、密钥流生成）
+├── Zuc256EncryptCtx.java  // 加解密上下文（流密码分段处理）
+├── Zuc256MacCtx.java      // MAC 上下文骨架（EIA3 类似流程）
+└── Zuc256Demo.java        // 演示主程序（明文→加密→解密→验证）
+```
+
+## 模块说明
+
+### 1. `Zuc256Tables`
+
+* 定义算法用到的 **S0/S1 S盒** 和 **常量数组 D**。
+* 这些表与 C 代码保持一一对应，只是存储在 Java 的 `static final int[]` 或 `int[][]` 中。
+* **填表后即可使用**，不涉及逻辑。
+
+---
+
+### 2. `Zuc256State`
+
+* 表示 ZUC-256 的 **运行时状态**。
+* 包含：
+
+    * `lfsr[16]`：16 个 31bit LFSR 元素（用 int 保存，低 31 位有效）；
+    * `r1, r2`：两个工作寄存器。
+* 提供 `reset()` 方法清零。
+
+---
+
+### 3. `Zuc256Util`
+
+* **通用工具函数集合**：
+
+    * `getU32` / `putU32`：字节数组与 32bit 整数互转（大端）；
+    * `add31`, `rot31`, `rot32`：位运算工具；
+    * `L1`, `L2`：线性变换骨架；
+    * `makeU31`, `makeU32`：拼接整数；
+    * `extractIv`：25B → 23B IV 转换（按标准规则实现）；
+    * `printHex`：调试用十六进制打印。
+* **注意**：JavaCard 环境中可去掉 `printHex`，避免额外依赖。
+
+---
+
+### 4. `Zuc256Core`
+
+* **算法内核**：
+
+    * `init`：根据 Key+IV 初始化状态（LFSR、R1/R2、预运行若干轮）；
+    * `generateKeyword`：生成单个 32bit 密钥字；
+    * `generateKeystream`：批量生成密钥流。
+* 该类仅依赖 `Zuc256State` 和 `Zuc256Tables`，是核心逻辑的承载处。
+
+---
+
+### 5. `Zuc256EncryptCtx`
+
+* **流密码上下文**，封装加解密 API：
+
+    * `init`：初始化状态；
+    * `update`：分段处理数据流，异或密钥流；
+    * `finish`：结束处理（流密码一般为空实现）；
+    * `crypt`：一次性便利方法。
+* 支持就地加解密，`in` 和 `out` 可相同。
+
+---
+
+### 6. `Zuc256MacCtx`
+
+* **MAC 骨架**（对应 ZUC-EIA3）。
+* 包含：
+
+    * `init`：初始化并设置 MAC 长度；
+    * `update`：累积输入数据；
+    * `finish`：输出认证标签。
+* 暂未实现细节，留空位便于后续扩展。
+
+---
+
+### 7. `Zuc256Demo`
+
+* **演示主程序**：完整展示 ZUC-256 加密/解密流程：
+
+    1. 准备明文、Key、IV；
+    2. 初始化状态，加密生成密文；
+    3. 重新初始化状态，解密得到明文；
+    4. 打印结果并校验是否一致。
+* 可直接运行验证整体流程是否正确。
+
+---