框架初始化

.gitignore

@@ -2,3 +2,4 @@ build
 __pycache__
 .sconsign.dblite
 .vscode
+*.class

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. 打印结果并校验是否一致。
+* 可直接运行验证整体流程是否正确。
+
+---

java/zuc256.java

@@ -0,0 +1,552 @@
+import java.util.Arrays;
+
+public class zuc256 {
+    // S盒定义
+    private static final int[] S0 = {
+        0x3e,0x72,0x5b,0x47,0xca,0xe0,0x00,0x33,0x04,0xd1,0x54,0x98,0x09,0xb9,0x6d,0xcb,
+        0x7b,0x1b,0xf9,0x32,0xaf,0x9d,0x6a,0xa5,0xb8,0x2d,0xfc,0x1d,0x08,0x53,0x03,0x90,
+        0x4d,0x4e,0x84,0x99,0xe4,0xce,0xd9,0x91,0xdd,0xb6,0x85,0x48,0x8b,0x29,0x6e,0xac,
+        0xcd,0xc1,0xf8,0x1e,0x73,0x43,0x69,0xc6,0xb5,0xbd,0xfd,0x39,0x63,0x20,0xd4,0x38,
+        0x76,0x7d,0xb2,0xa7,0xcf,0xed,0x57,0xc5,0xf3,0x2c,0xbb,0x14,0x21,0x06,0x55,0x9b,
+        0xe3,0xef,0x5e,0x31,0x4f,0x7f,0x5a,0xa4,0x0d,0x82,0x51,0x49,0x5f,0xba,0x58,0x1c,
+        0x4a,0x16,0xd5,0x17,0xa8,0x92,0x24,0x1f,0x8c,0xff,0xd8,0xae,0x2e,0x01,0xd3,0xad,
+        0x3b,0x4b,0xda,0x46,0xeb,0xc9,0xde,0x9a,0x8f,0x87,0xd7,0x3a,0x80,0x6f,0x2f,0xc8,
+        0xb1,0xb4,0x37,0xf7,0x0a,0x22,0x13,0x28,0x7c,0xcc,0x3c,0x89,0xc7,0xc3,0x96,0x56,
+        0x07,0xbf,0x7e,0xf0,0x0b,0x2b,0x97,0x52,0x35,0x41,0x79,0x61,0xa6,0x4c,0x10,0xfe,
+        0xbc,0x26,0x95,0x88,0x8a,0xb0,0xa3,0xfb,0xc0,0x18,0x94,0xf2,0xe1,0xe5,0xe9,0x5d,
+        0xd0,0xdc,0x11,0x66,0x64,0x5c,0xec,0x59,0x42,0x75,0x12,0xf5,0x74,0x9c,0xaa,0x23,
+        0x0e,0x86,0xab,0xbe,0x2a,0x02,0xe7,0x67,0xe6,0x44,0xa2,0x6c,0xc2,0x93,0x9f,0xf1,
+        0xf6,0xfa,0x36,0xd2,0x50,0x68,0x9e,0x62,0x71,0x15,0x3d,0xd6,0x40,0xc4,0xe2,0x0f,
+        0x8e,0x83,0x77,0x6b,0x25,0x05,0x3f,0x0c,0x30,0xea,0x70,0xb7,0xa1,0xe8,0xa9,0x65,
+        0x8d,0x27,0x1a,0xdb,0x81,0xb3,0xa0,0xf4,0x45,0x7a,0x19,0xdf,0xee,0x78,0x34,0x60
+    };
+
+    private static final int[] S1 = {
+        0x55,0xc2,0x63,0x71,0x3b,0xc8,0x47,0x86,0x9f,0x3c,0xda,0x5b,0x29,0xaa,0xfd,0x77,
+        0x8c,0xc5,0x94,0x0c,0xa6,0x1a,0x13,0x00,0xe3,0xa8,0x16,0x72,0x40,0xf9,0xf8,0x42,
+        0x44,0x26,0x68,0x96,0x81,0xd9,0x45,0x3e,0x10,0x76,0xc6,0xa7,0x8b,0x39,0x43,0xe1,
+        0x3a,0xb5,0x56,0x2a,0xc0,0x6d,0xb3,0x05,0x22,0x66,0xbf,0xdc,0x0b,0xfa,0x62,0x48,
+        0xdd,0x20,0x11,0x06,0x36,0xc9,0xc1,0xcf,0xf6,0x27,0x52,0xbb,0x69,0xf5,0xd4,0x87,
+        0x7f,0x84,0x4c,0xd2,0x9c,0x57,0xa4,0xbc,0x4f,0x9a,0xdf,0xfe,0xd6,0x8d,0x7a,0xeb,
+        0x2b,0x53,0xd8,0x5c,0xa1,0x14,0x17,0xfb,0x23,0xd5,0x7d,0x30,0x67,0x73,0x08,0x09,
+        0xee,0xb7,0x70,0x3f,0x61,0xb2,0x19,0x8e,0x4e,0xe5,0x4b,0x93,0x8f,0x5d,0xdb,0xa9,
+        0xad,0xf1,0xae,0x2e,0xcb,0x0d,0xfc,0xf4,0x2d,0x46,0x6e,0x1d,0x97,0xe8,0xd1,0xe9,
+        0x4d,0x37,0xa5,0x75,0x5e,0x83,0x9e,0xab,0x82,0x9d,0xb9,0x1c,0xe0,0xcd,0x49,0x89,
+        0x01,0xb6,0xbd,0x58,0x24,0xa2,0x5f,0x38,0x78,0x99,0x15,0x90,0x50,0xb8,0x95,0xe4,
+        0xd0,0x91,0xc7,0xce,0xed,0x0f,0xb4,0x6f,0xa0,0xcc,0xf0,0x02,0x4a,0x79,0xc3,0xde,
+        0xa3,0xef,0xea,0x51,0xe6,0x6b,0x18,0xec,0x1b,0x2c,0x80,0xf7,0x74,0xe7,0xff,0x21,
+        0x5a,0x6a,0x54,0x1e,0x41,0x31,0x92,0x35,0xc4,0x33,0x07,0x0a,0xba,0x7e,0x0e,0x34,
+        0x88,0xb1,0x98,0x7c,0xf3,0x3d,0x60,0x6c,0x7b,0xca,0xd3,0x1f,0x32,0x65,0x04,0x28,
+        0x64,0xbe,0x85,0x9b,0x2f,0x59,0x8a,0xd7,0xb0,0x25,0xac,0xaf,0x12,0x03,0xe2,0xf2
+    };
+
+    // 常量数组D
+    private static final int[][] ZUC256_D = {
+        {0x22,0x2F,0x24,0x2A,0x6D,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x52,0x10,0x30},
+        {0x22,0x2F,0x25,0x2A,0x6D,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x52,0x10,0x30},
+        {0x23,0x2F,0x24,0x2A,0x6D,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x52,0x10,0x30},
+        {0x23,0x2F,0x25,0x2A,0x6D,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x52,0x10,0x30}
+    };
+
+    // ZUC状态类
+    public static class ZUCState {
+        int[] LFSR = new int[16];  // 线性反馈移位寄存器
+        int R1;                    // 寄存器1
+        int R2;                    // 寄存器2
+    }
+
+    // 加密上下文类
+    public static class ZUC256EncryptCtx {
+        ZUCState state = new ZUCState();
+        byte[] buf = new byte[4];
+        int buflen;
+    }
+
+    // MAC上下文类
+    public static class ZUC256MacCtx {
+        int[] LFSR = new int[16];
+        int R1;
+        int R2;
+        byte[] buf = new byte[4];
+        int buflen;
+        int[] T = new int[4];
+        int[] K0 = new int[4];
+        int macbits;
+    }
+
+    // 辅助方法：将字节数组转换为32位整数
+    private static int getU32(byte[] p, int offset) {
+        return ((p[offset] & 0xFF) << 24) | 
+               ((p[offset + 1] & 0xFF) << 16) | 
+               ((p[offset + 2] & 0xFF) << 8) | 
+               (p[offset + 3] & 0xFF);
+    }
+
+    // 辅助方法：将32位整数转换为字节数组
+    private static void putU32(byte[] p, int offset, int v) {
+        p[offset] = (byte) (v >> 24);
+        p[offset + 1] = (byte) (v >> 16);
+        p[offset + 2] = (byte) (v >> 8);
+        p[offset + 3] = (byte) v;
+    }
+
+    // 31位加法
+    private static int add31(int a, int b) {
+        long sum = (long)a + b;
+        return (int) ((sum & 0x7FFFFFFF) + (sum >> 31));
+    }
+
+    // 31位旋转
+    private static int rot31(int a, int k) {
+        return ((a << k) | (a >>> (31 - k))) & 0x7FFFFFFF;
+    }
+
+    // 32位旋转
+    private static int rot32(int a, int k) {
+        return (a << k) | (a >>> (32 - k));
+    }
+
+    // L1函数
+    private static int L1(int x) {
+        return x ^ rot32(x, 2) ^ rot32(x, 10) ^ rot32(x, 18) ^ rot32(x, 24);
+    }
+
+    // L2函数
+    private static int L2(int x) {
+        return x ^ rot32(x, 8) ^ rot32(x, 14) ^ rot32(x, 22) ^ rot32(x, 30);
+    }
+
+    // 初始化MAC密钥
+    private static void zuc256SetMacKey(ZUCState key, byte[] K, byte[] IV, int macbits) {
+        int[] LFSR = key.LFSR;
+        int R1 = 0;
+        int R2 = 0;
+        int X0, X1, X2;
+        int W, W1, W2, U, V;
+        int[] D;
+
+        int IV17 = (IV[17] & 0xFF) >> 2;
+        int IV18 = ((IV[17] & 0x03) << 4) | ((IV[18] & 0xFF) >> 4);
+        int IV19 = ((IV[18] & 0x0F) << 2) | ((IV[19] & 0xFF) >> 6);
+        int IV20 = IV[19] & 0x3F;
+        int IV21 = (IV[20] & 0xFF) >> 2;
+        int IV22 = ((IV[20] & 0x03) << 4) | ((IV[21] & 0xFF) >> 4);
+        int IV23 = ((IV[21] & 0x0F) << 2) | ((IV[22] & 0xFF) >> 6);
+        int IV24 = IV[22] & 0x3F;
+
+        D = (macbits / 32 < 3) ? ZUC256_D[macbits / 32] : ZUC256_D[3];
+        
+        LFSR[0] = makeU31(K[0] & 0xFF, D[0], K[21] & 0xFF, K[16] & 0xFF);
+        LFSR[1] = makeU31(K[1] & 0xFF, D[1], K[22] & 0xFF, K[17] & 0xFF);
+        LFSR[2] = makeU31(K[2] & 0xFF, D[2], K[23] & 0xFF, K[18] & 0xFF);
+        LFSR[3] = makeU31(K[3] & 0xFF, D[3], K[24] & 0xFF, K[19] & 0xFF);
+        LFSR[4] = makeU31(K[4] & 0xFF, D[4], K[25] & 0xFF, K[20] & 0xFF);
+        LFSR[5] = makeU31(IV[0] & 0xFF, (D[5] | IV17), K[5] & 0xFF, K[26] & 0xFF);
+        LFSR[6] = makeU31(IV[1] & 0xFF, (D[6] | IV18), K[6] & 0xFF, K[27] & 0xFF);
+        LFSR[7] = makeU31(IV[10] & 0xFF, (D[7] | IV19), K[7] & 0xFF, IV[2] & 0xFF);
+        LFSR[8] = makeU31(K[8] & 0xFF, (D[8] | IV20), IV[3] & 0xFF, IV[11] & 0xFF);
+        LFSR[9] = makeU31(K[9] & 0xFF, (D[9] | IV21), IV[12] & 0xFF, IV[4] & 0xFF);
+        LFSR[10] = makeU31(IV[5] & 0xFF, (D[10] | IV22), K[10] & 0xFF, K[28] & 0xFF);
+        LFSR[11] = makeU31(K[11] & 0xFF, (D[11] | IV23), IV[6] & 0xFF, IV[13] & 0xFF);
+        LFSR[12] = makeU31(K[12] & 0xFF, (D[12] | IV24), IV[7] & 0xFF, IV[14] & 0xFF);
+        LFSR[13] = makeU31(K[13] & 0xFF, D[13], IV[15] & 0xFF, IV[8] & 0xFF);
+        LFSR[14] = makeU31(K[14] & 0xFF, (D[14] | (K[31] >>> 4)), IV[16] & 0xFF, IV[9] & 0xFF);
+        LFSR[15] = makeU31(K[15] & 0xFF, (D[15] | (K[31] & 0x0F)), K[30] & 0xFF, K[29] & 0xFF);
+
+        for (int i = 0; i < 32; i++) {
+            // BitReconstruction3
+            X0 = ((LFSR[15] & 0x7FFF8000) << 1) | (LFSR[14] & 0xFFFF);
+            X1 = ((LFSR[11] & 0xFFFF) << 16) | (LFSR[9] >>> 15);
+            X2 = ((LFSR[7] & 0xFFFF) << 16) | (LFSR[5] >>> 15);
+            
+            // F(X0, X1, X2)
+            W = (X0 ^ R1) + R2;
+            W1 = R1 + X1;
+            W2 = R2 ^ X2;
+            U = L1((W1 << 16) | (W2 >>> 16));
+            V = L2((W2 << 16) | (W1 >>> 16));
+            
+            R1 = makeU32(S0[(U >>> 24) & 0xFF], 
+                         S1[(U >>> 16) & 0xFF], 
+                         S0[(U >>> 8) & 0xFF], 
+                         S1[U & 0xFF]);
+            
+            R2 = makeU32(S0[(V >>> 24) & 0xFF], 
+                         S1[(V >>> 16) & 0xFF], 
+                         S0[(V >>> 8) & 0xFF], 
+                         S1[V & 0xFF]);
+            
+            // LFSRWithInitialisationMode(W >> 1)
+            int v = LFSR[0];
+            v = add31(v, rot31(LFSR[0], 8));
+            v = add31(v, rot31(LFSR[4], 20));
+            v = add31(v, rot31(LFSR[10], 21));
+            v = add31(v, rot31(LFSR[13], 17));
+            v = add31(v, rot31(LFSR[15], 15));
+            v = add31(v, W >>> 1);
+            
+            System.arraycopy(LFSR, 1, LFSR, 0, 15);
+            LFSR[15] = v;
+        }
+
+        // BitReconstruction2
+        X1 = ((LFSR[11] & 0xFFFF) << 16) | (LFSR[9] >>> 15);
+        X2 = ((LFSR[7] & 0xFFFF) << 16) | (LFSR[5] >>> 15);
+        
+        // F_(X1, X2)
+        W1 = R1 + X1;
+        W2 = R2 ^ X2;
+        U = L1((W1 << 16) | (W2 >>> 16));
+        V = L2((W2 << 16) | (W1 >>> 16));
+        
+        R1 = makeU32(S0[(U >>> 24) & 0xFF], 
+                     S1[(U >>> 16) & 0xFF], 
+                     S0[(U >>> 8) & 0xFF], 
+                     S1[U & 0xFF]);
+        
+        R2 = makeU32(S0[(V >>> 24) & 0xFF], 
+                     S1[(V >>> 16) & 0xFF], 
+                     S0[(V >>> 8) & 0xFF], 
+                     S1[V & 0xFF]);
+        
+        // LFSRWithWorkMode
+        long a = LFSR[0];
+        a += (long)LFSR[0] << 8;
+        a += (long)LFSR[4] << 20;
+        a += (long)LFSR[10] << 21;
+        a += (long)LFSR[13] << 17;
+        a += (long)LFSR[15] << 15;
+        a = (a & 0x7FFFFFFF) + (a >>> 31);
+        int v = (int) ((a & 0x7FFFFFFF) + (a >>> 31));
+        
+        System.arraycopy(LFSR, 1, LFSR, 0, 15);
+        LFSR[15] = v;
+
+        key.R1 = R1;
+        key.R2 = R2;
+    }
+
+    // 创建31位无符号整数
+    private static int makeU31(int a, int b, int c, int d) {
+        return (((a & 0xFF) << 23) | 
+                ((b & 0xFF) << 16) | 
+                ((c & 0xFF) << 8) | 
+                (d & 0xFF)) & 0x7FFFFFFF;
+    }
+
+    // 创建32位无符号整数
+    private static int makeU32(int a, int b, int c, int d) {
+        return ((a & 0xFF) << 24) | 
+               ((b & 0xFF) << 16) | 
+               ((c & 0xFF) << 8) | 
+               (d & 0xFF);
+    }
+
+    // 初始化ZUC256状态
+    public static void zuc256Init(ZUCState state, byte[] K, byte[] IV) {
+        zuc256SetMacKey(state, K, IV, 0);
+    }
+
+    // 生成单个密钥字
+    public static int zuc256GenerateKeyword(ZUCState state) {
+        int[] LFSR = state.LFSR;
+        int R1 = state.R1;
+        int R2 = state.R2;
+        int X0, X1, X2, X3;
+        int W1, W2, U, V;
+        int Z;
+
+        // BitReconstruction4
+        X0 = ((LFSR[15] & 0x7FFF8000) << 1) | (LFSR[14] & 0xFFFF);
+        X1 = ((LFSR[11] & 0xFFFF) << 16) | (LFSR[9] >>> 15);
+        X2 = ((LFSR[7] & 0xFFFF) << 16) | (LFSR[5] >>> 15);
+        X3 = ((LFSR[2] & 0xFFFF) << 16) | (LFSR[0] >>> 15);
+
+        Z = X3 ^ ((X0 ^ R1) + R2);
+
+        // F_(X1, X2)
+        W1 = R1 + X1;
+        W2 = R2 ^ X2;
+        U = L1((W1 << 16) | (W2 >>> 16));
+        V = L2((W2 << 16) | (W1 >>> 16));
+
+        R1 = makeU32(S0[(U >>> 24) & 0xFF], 
+                     S1[(U >>> 16) & 0xFF], 
+                     S0[(U >>> 8) & 0xFF], 
+                     S1[U & 0xFF]);
+        
+        R2 = makeU32(S0[(V >>> 24) & 0xFF], 
+                     S1[(V >>> 16) & 0xFF], 
+                     S0[(V >>> 8) & 0xFF], 
+                     S1[V & 0xFF]);
+
+        // LFSRWithWorkMode
+        long a = LFSR[0];
+        a += (long)LFSR[0] << 8;
+        a += (long)LFSR[4] << 20;
+        a += (long)LFSR[10] << 21;
+        a += (long)LFSR[13] << 17;
+        a += (long)LFSR[15] << 15;
+        a = (a & 0x7FFFFFFF) + (a >>> 31);
+        int v = (int) ((a & 0x7FFFFFFF) + (a >>> 31));
+        
+        System.arraycopy(LFSR, 1, LFSR, 0, 15);
+        LFSR[15] = v;
+
+        state.R1 = R1;
+        state.R2 = R2;
+
+        return Z;
+    }
+
+    // 生成指定长度的密钥流
+    public static void zuc256GenerateKeystream(ZUCState state, int nwords, int[] keystream) {
+        int[] LFSR = state.LFSR;
+        int R1 = state.R1;
+        int R2 = state.R2;
+        int X0, X1, X2, X3;
+        int W1, W2, U, V;
+
+        for (int i = 0; i < nwords; i++) {
+            // BitReconstruction4
+            X0 = ((LFSR[15] & 0x7FFF8000) << 1) | (LFSR[14] & 0xFFFF);
+            X1 = ((LFSR[11] & 0xFFFF) << 16) | (LFSR[9] >>> 15);
+            X2 = ((LFSR[7] & 0xFFFF) << 16) | (LFSR[5] >>> 15);
+            X3 = ((LFSR[2] & 0xFFFF) << 16) | (LFSR[0] >>> 15);
+
+            keystream[i] = X3 ^ ((X0 ^ R1) + R2);
+
+            // F_(X1, X2)
+            W1 = R1 + X1;
+            W2 = R2 ^ X2;
+            U = L1((W1 << 16) | (W2 >>> 16));
+            V = L2((W2 << 16) | (W1 >>> 16));
+
+            // S盒查找
+            int T0 = S0[(U >>> 24) & 0xFF] & 0xFF;
+            int T2 = S0[(U >>> 8) & 0xFF] & 0xFF;
+            int T4 = S0[(V >>> 24) & 0xFF] & 0xFF;
+            int T6 = S0[(V >>> 8) & 0xFF] & 0xFF;
+
+            int T1 = S1[(U >>> 16) & 0xFF] & 0xFF;
+            int T3 = S1[U & 0xFF] & 0xFF;
+            int T5 = S1[(V >>> 16) & 0xFF] & 0xFF;
+            int T7 = S1[V & 0xFF] & 0xFF;
+
+            R1 = makeU32(T0, T1, T2, T3);
+            R2 = makeU32(T4, T5, T6, T7);
+
+            // LFSRWithWorkMode
+            long a = LFSR[0];
+            a += (long)LFSR[0] << 8;
+            a += (long)LFSR[4] << 20;
+            a += (long)LFSR[10] << 21;
+            a += (long)LFSR[13] << 17;
+            a += (long)LFSR[15] << 15;
+            a = (a & 0x7FFFFFFF) + (a >>> 31);
+            int v = (int) ((a & 0x7FFFFFFF) + (a >>> 31));
+            
+            System.arraycopy(LFSR, 1, LFSR, 0, 15);
+            LFSR[15] = v;
+        }
+
+        state.R1 = R1;
+        state.R2 = R2;
+    }
+
+    // 初始化加密上下文
+    public static void zuc256EncryptInit(ZUC256EncryptCtx ctx, byte[] K, byte[] IV) {
+        Arrays.fill(ctx.buf, (byte) 0);
+        ctx.buflen = 0;
+        zuc256Init(ctx.state, K, IV);
+    }
+
+    // 分阶段处理加密数据
+    public static void zuc256EncryptUpdate(ZUC256EncryptCtx ctx, byte[] in, int inlen, byte[] out) {
+        if (in == null || out == null || inlen == 0) return;
+
+        // 处理缓冲区中剩余的非4字节数据
+        if (ctx.buflen > 0) {
+            int need = 4 - ctx.buflen;
+            int copy = Math.min(inlen, need);
+            
+            System.arraycopy(in, 0, ctx.buf, ctx.buflen, copy);
+            ctx.buflen += copy;
+            
+            // 调整输入指针和长度
+            byte[] newIn = new byte[inlen - copy];
+            if (inlen - copy > 0) {
+                System.arraycopy(in, copy, newIn, 0, inlen - copy);
+            }
+            in = newIn;
+            inlen -= copy;
+
+            // 缓冲区已满，处理一个完整的4字节块
+            if (ctx.buflen == 4) {
+                int keystream = zuc256GenerateKeyword(ctx.state);
+                int plain = getU32(ctx.buf, 0);
+                putU32(out, 0, plain ^ keystream);
+                
+                ctx.buflen = 0;
+                Arrays.fill(ctx.buf, (byte) 0);
+                
+                // 调整输出指针
+                byte[] newOut = new byte[out.length - 4];
+                if (out.length - 4 > 0) {
+                    System.arraycopy(out, 4, newOut, 0, out.length - 4);
+                }
+                out = newOut;
+            }
+        }
+
+        // 处理完整的4字节块
+        int fullBlocks = inlen / 4;
+        if (fullBlocks > 0) {
+            int[] keystream = new int[fullBlocks];
+            zuc256GenerateKeystream(ctx.state, fullBlocks, keystream);
+            
+            // 逐块异或加密
+            for (int i = 0; i < fullBlocks; i++) {
+                int plain = getU32(in, i * 4);
+                putU32(out, i * 4, plain ^ keystream[i]);
+            }
+            
+            // 调整输入指针和长度
+            int processed = fullBlocks * 4;
+            byte[] newIn = new byte[inlen - processed];
+            if (inlen - processed > 0) {
+                System.arraycopy(in, processed, newIn, 0, inlen - processed);
+            }
+            in = newIn;
+            inlen -= processed;
+        }
+
+        // 缓存剩余不足4字节的数据
+        if (inlen > 0) {
+            System.arraycopy(in, 0, ctx.buf, 0, inlen);
+            ctx.buflen = inlen;
+        }
+    }
+
+    // 完成加密处理
+    public static void zuc256EncryptFinish(ZUC256EncryptCtx ctx, byte[] out) {
+        if (ctx == null || out == null) return;
+
+        // 处理缓冲区中剩余的不足4字节数据
+        if (ctx.buflen > 0) {
+            int keystream = zuc256GenerateKeyword(ctx.state);
+            byte[] keystreamBytes = new byte[4];
+            putU32(keystreamBytes, 0, keystream);
+            
+            // 逐字节异或
+            for (int i = 0; i < ctx.buflen; i++) {
+                out[i] = (byte) (ctx.buf[i] ^ keystreamBytes[i]);
+            }
+        }
+
+        // 清理上下文
+        Arrays.fill(ctx.buf, (byte) 0);
+        ctx.buflen = 0;
+        Arrays.fill(ctx.state.LFSR, 0);
+        ctx.state.R1 = 0;
+        ctx.state.R2 = 0;
+    }
+
+    // 一次性加密函数
+    public static void zuc256Crypt(ZUCState state, byte[] in, int inlen, byte[] out) {
+        if (state == null || in == null || out == null) return;
+
+        ZUC256EncryptCtx ctx = new ZUC256EncryptCtx();
+        // 复制状态
+        System.arraycopy(state.LFSR, 0, ctx.state.LFSR, 0, state.LFSR.length);
+        ctx.state.R1 = state.R1;
+        ctx.state.R2 = state.R2;
+
+        // 执行加解密
+        zuc256EncryptUpdate(ctx, in, inlen, out);
+        int remainingOffset = (inlen / 4) * 4;
+        byte[] finishOut = new byte[out.length - remainingOffset];
+        if (finishOut.length > 0) {
+            System.arraycopy(out, remainingOffset, finishOut, 0, finishOut.length);
+        }
+        zuc256EncryptFinish(ctx, finishOut);
+        System.arraycopy(finishOut, 0, out, remainingOffset, finishOut.length);
+        
+        // 更新状态
+        System.arraycopy(ctx.state.LFSR, 0, state.LFSR, 0, ctx.state.LFSR.length);
+        state.R1 = ctx.state.R1;
+        state.R2 = ctx.state.R2;
+    }
+
+    // 提取IV
+    public static void extractIv(byte[] input25Byte, byte[] output23Byte) {
+        if (input25Byte == null || output23Byte == null) return;
+        
+        // 复制前17字节
+        System.arraycopy(input25Byte, 0, output23Byte, 0, 17);
+        
+        // 处理剩余8字节
+        byte[] src = new byte[8];
+        for (int i = 0; i < 8; i++) {
+            src[i] = (byte) (input25Byte[17 + i] & 0x3F);
+        }
+        
+        output23Byte[17] = (byte) ((src[0] << 2) | (src[1] >>> 4));
+        output23Byte[18] = (byte) (((src[1] & 0x0F) << 4) | (src[2] >>> 2));
+        output23Byte[19] = (byte) (((src[2] & 0x03) << 6) | src[3]);
+        output23Byte[20] = (byte) ((src[4] << 2) | (src[5] >>> 4));
+        output23Byte[21] = (byte) (((src[5] & 0x0F) << 4) | (src[6] >>> 2));
+        output23Byte[22] = (byte) (((src[6] & 0x03) << 6) | src[7]);
+    }
+
+    // 打印字节数组为十六进制
+    public static void printHex(String label, byte[] data, int len) {
+        System.out.print(label + ": ");
+        for (int i = 0; i < len; i++) {
+            System.out.printf("%02x ", data[i] & 0xFF);
+        }
+        System.out.println();
+    }
+
+    // 主函数，验证ZUC256加解密功能
+    public static void main(String[] args) {
+        // 1. 明文
+        byte[] plaintext = "ZUC256对称加解密测试:1234567890".getBytes();
+        int plaintextLen = plaintext.length;
+        System.out.println("明文: " + new String(plaintext));
+        printHex("明文(十六进制)", plaintext, plaintextLen);
+
+        // 2. 密钥(32字节ASCII)
+        byte[] key = "0123456789abcdef0123456789abcdef".getBytes();
+        printHex("密钥", key, 32);
+
+        // 3. 初始向量(25字节ASCII)
+        byte[] inputIv25Byte = "0123456789abcdefg01234567".getBytes();
+        byte[] iv = new byte[23];
+        extractIv(inputIv25Byte, iv);
+        printHex("提取后的IV", iv, 23);
+
+        // 4. 分配加密/解密缓冲区
+        byte[] ciphertext = new byte[plaintextLen];
+        byte[] decryptedtext = new byte[plaintextLen];
+
+        // 5. 加密
+        ZUCState state = new ZUCState();
+        zuc256Init(state, key, iv);
+        zuc256Crypt(state, plaintext, plaintextLen, ciphertext);
+        printHex("密文", ciphertext, plaintextLen);
+
+        // 6. 解密(重新初始化状态)
+        zuc256Init(state, key, iv);
+        zuc256Crypt(state, ciphertext, plaintextLen, decryptedtext);
+        printHex("解密后", decryptedtext, plaintextLen);
+        System.out.println("解密文本: " + new String(decryptedtext));
+
+        // 7. 验证结果
+        if (Arrays.equals(plaintext, decryptedtext)) {
+            System.out.println("=== 测试成功: 解密结果与明文一致 ===");
+        } else {
+            System.out.println("=== 测试失败: 解密结果与明文不一致 ===");
+        }
+    }
+}

src/com/zuc/zuc256/Zuc256Core.java

@@ -0,0 +1,35 @@
+package com.zuc.zuc256;
+
+/**
+ * ZUC-256 核心：状态初始化、密钥字生成、密钥流生成。
+ * 仅保留对外 API 与内部步骤骨架，细节待填。
+ */
+public final class Zuc256Core {
+
+    private Zuc256Core() {}
+
+    /** 初始化状态（Key + IV） */
+    public static void init(Zuc256State st, byte[] key32, byte[] ivN) {
+        // TODO: 1) 按表和 key/iv 装载 LFSR 初值
+        // TODO: 2) 置 R1/R2
+        // TODO: 3) 预运行若干轮
+        throw new UnsupportedOperationException("TODO: init");
+    }
+
+    /** 生成单个 32bit 密钥字 */
+    public static int generateKeyword(Zuc256State st) {
+        // TODO: 1) BitReconstruction
+        // TODO: 2) 非线性变换 F -> W
+        // TODO: 3) LFSR 下一步（with/without carry 按标准）
+        // TODO: 4) 输出 W ⊕ X(??)（依实现）
+        throw new UnsupportedOperationException("TODO: generateKeyword");
+    }
+
+    /** 生成 nwords 个 32bit 密钥字到 ks[] */
+    public static void generateKeystream(Zuc256State st, int nwords, int[] ks) {
+        for (int i = 0; i < nwords; i++) {
+            ks[i] = generateKeyword(st); // TODO: 替换为高效批量实现（可选）
+        }
+    }
+}
+

src/com/zuc/zuc256/Zuc256Demo.java

@@ -0,0 +1,51 @@
+package com.zuc.zuc256;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+
+/**
+ * 演示主函数：保持与你的单文件示例一致的调用路径。
+ * 说明：核心函数仍未实现，运行会抛出 UnsupportedOperationException。
+ */
+public final class Zuc256Demo {
+
+    public static void main(String[] args) {
+        // 1. 明文
+        byte[] plaintext = "ZUC256对称加解密测试:1234567890".getBytes(StandardCharsets.UTF_8);
+        System.out.println("明文: " + new String(plaintext, StandardCharsets.UTF_8));
+        Zuc256Util.printHex("明文(十六进制)", plaintext, plaintext.length);
+
+        // 2. 密钥(32字节ASCII)
+        byte[] key = "0123456789abcdef0123456789abcdef".getBytes(StandardCharsets.US_ASCII);
+        Zuc256Util.printHex("密钥", key, key.length);
+
+        // 3. 初始向量(25字节ASCII) -> 提取 23 字节
+        byte[] inputIv25Byte = "0123456789abcdefg01234567".getBytes(StandardCharsets.US_ASCII);
+        byte[] iv = new byte[23];
+        // TODO: 按你的 C 规则提取
+        // Zuc256Util.extractIv(inputIv25Byte, iv);
+        Zuc256Util.printHex("提取后的IV(占位)", iv, iv.length);
+
+        // 4. 加密/解密缓冲区
+        byte[] ciphertext = new byte[plaintext.length];
+        byte[] decrypted  = new byte[plaintext.length];
+
+        // 5. 加密
+        Zuc256EncryptCtx enc = new Zuc256EncryptCtx();
+        enc.init(key, iv);
+        enc.update(plaintext, 0, plaintext.length, ciphertext, 0);
+        Zuc256Util.printHex("密文", ciphertext, ciphertext.length);
+
+        // 6. 解密（重新初始化）
+        Zuc256EncryptCtx dec = new Zuc256EncryptCtx();
+        dec.init(key, iv);
+        dec.update(ciphertext, 0, ciphertext.length, decrypted, 0);
+        Zuc256Util.printHex("解密后", decrypted, decrypted.length);
+        System.out.println("解密文本: " + new String(decrypted, StandardCharsets.UTF_8));
+
+        // 7. 验证
+        System.out.println(Arrays.equals(plaintext, decrypted)
+                ? "=== 测试成功: 解密结果与明文一致 ==="
+                : "=== 测试失败: 解密结果与明文不一致 ===");
+    }
+}

src/com/zuc/zuc256/Zuc256EncryptCtx.java

@@ -0,0 +1,42 @@
+package com.zuc.zuc256;
+
+import java.util.Arrays;
+
+/**
+ * 分段加/解密上下文（流密码：同一流程）。
+ * 注意：JavaCard 上尽量复用缓冲，避免额外分配。
+ */
+public final class Zuc256EncryptCtx {
+    private final Zuc256State st = new Zuc256State();
+
+    // 流水寄存（可选）：缓存当前 32bit 密钥字与已用字节数
+    private int keystreamWord;
+    private int usedBytes;
+
+    public void init(byte[] key32, byte[] iv) {
+        Arrays.fill(st.lfsr, 0);
+        st.r1 = st.r2 = 0;
+        usedBytes = 4; // 令首次进入 update() 时强制拉取新字
+        Zuc256Core.init(st, key32, iv);
+    }
+
+    /**
+     * 分段处理：in/out 可同缓冲（就地异或）。
+     */
+    public void update(byte[] in, int inOff, int inLen, byte[] out, int outOff) {
+        // TODO: 逐字节与 keystreamWord 异或，4 字节耗尽后生成下一字
+        throw new UnsupportedOperationException("TODO: update");
+    }
+
+    public void finish(byte[] out, int outOff) {
+        // 流密码无填充；如需 MAC/尾处理，放到 MAC 上下文中
+    }
+
+    /** 一次性处理（便利方法） */
+    public static void crypt(byte[] key32, byte[] iv, byte[] in, int inOff, int inLen, byte[] out, int outOff) {
+        Zuc256EncryptCtx ctx = new Zuc256EncryptCtx();
+        ctx.init(key32, iv);
+        ctx.update(in, inOff, inLen, out, outOff);
+        ctx.finish(out, outOff + inLen);
+    }
+}

src/com/zuc/zuc256/Zuc256MacCtx.java

@@ -0,0 +1,29 @@
+package com.zuc.zuc256;
+
+/**
+ * MAC 上下文（可选：ZUC-256-EIA3 类似流程）
+ * 这里只给出骨架，按你的 C 代码把细节补齐。
+ */
+public final class Zuc256MacCtx {
+    private final Zuc256State st = new Zuc256State();
+    private int macBits;   // 32/64/128...
+    private int acc;       // 累加器/寄存器，视实现调整
+
+    public void init(byte[] key32, byte[] iv, int macBits) {
+        this.macBits = macBits;
+        this.acc = 0;
+        Zuc256Core.init(st, key32, iv);
+        // TODO: 若 MAC 需特殊 IV/派生，按 C 版本处理
+        throw new UnsupportedOperationException("TODO: MAC init details");
+    }
+
+    public void update(byte[] data, int off, int len) {
+        // TODO: 消耗比特/字节流并累积 acc
+        throw new UnsupportedOperationException("TODO: MAC update");
+    }
+
+    public void finish(byte[] tag, int tagOff) {
+        // TODO: 输出 macBits 位标签到 tag[]
+        throw new UnsupportedOperationException("TODO: MAC finish");
+    }
+}

src/com/zuc/zuc256/Zuc256State.java

@@ -0,0 +1,16 @@
+package com.zuc.zuc256;
+
+/**
+ * ZUC 内部状态：LFSR(16x31bit) + R1/R2。
+ * Java 中用 int 保存（仅低 31 位有效）。
+ */
+public final class Zuc256State {
+    public final int[] lfsr = new int[16]; // 线性反馈移位寄存器，31bit/项
+    public int r1;                          // 32bit working register
+    public int r2;                          // 32bit working register
+
+    public void reset() {
+        for (int i = 0; i < lfsr.length; i++) lfsr[i] = 0;
+        r1 = 0; r2 = 0;
+    }
+}

src/com/zuc/zuc256/Zuc256Tables.java

@@ -0,0 +1,28 @@
+package com.zuc.zuc256;
+
+/**
+ * 常量表：S0/S1 与 ZUC256_D。
+ * 注意：JavaCard 目标环境建议将表定义为 static final 数组，按 int/short 存放。
+ * TODO: 将 C 版本中的表逐项拷入。
+ */
+public final class Zuc256Tables {
+
+    private Zuc256Tables() {}
+
+    // S盒：S0, S1
+    public static final int[] S0 = {
+            // TODO: 填入 256 项
+    };
+
+    public static final int[] S1 = {
+            // TODO: 填入 256 项
+    };
+
+    /**
+     * 常量数组 D（按标准/实现定义）
+     * 说明：根据你的 C 代码布局选择 int[?][?] 或 int[] 线性展开。
+     */
+    public static final int[][] ZUC256_D = {
+            // TODO: 填入
+    };
+}

src/com/zuc/zuc256/Zuc256Util.java

@@ -0,0 +1,104 @@
+package com.zuc.zuc256;
+
+import java.util.Locale;
+
+/**
+ * 辅助工具：装载/存储、位运算、线性变换、打印等。
+ * 默认使用大端序（与大多数参考实现一致），如需小端请统一替换。
+ */
+public final class Zuc256Util {
+
+    private Zuc256Util() {}
+
+    // === Byte <-> U32 ===
+
+    /** 从 p[offset..offset+3] 读 32bit（大端） */
+    public static int getU32(byte[] p, int offset) {
+        // TODO: 如需小端，改为反序装载
+        int v = ((p[offset] & 0xFF) << 24)
+                | ((p[offset + 1] & 0xFF) << 16)
+                | ((p[offset + 2] & 0xFF) << 8)
+                |  (p[offset + 3] & 0xFF);
+        return v;
+    }
+
+    /** 将 v 写入 p[offset..offset+3]（大端） */
+    public static void putU32(byte[] p, int offset, int v) {
+        // TODO: 如需小端，改为反序存储
+        p[offset]     = (byte)((v >>> 24) & 0xFF);
+        p[offset + 1] = (byte)((v >>> 16) & 0xFF);
+        p[offset + 2] = (byte)((v >>> 8)  & 0xFF);
+        p[offset + 3] = (byte)(v & 0xFF);
+    }
+
+    // === 31/32 位运算 ===
+
+    /** 31 位加法（丢弃第 32 位），仅保留低 31 位 */
+    public static int add31(int a, int b) {
+        // TODO: 对齐 C 的具体实现细节（是否有进位回注）
+        return (a + b) & 0x7FFFFFFF;
+    }
+
+    /** 31 位循环左移（仅低 31 位参与） */
+    public static int rot31(int a, int k) {
+        int x = a & 0x7FFFFFFF;
+        k %= 31;
+        return ((x << k) | (x >>> (31 - k))) & 0x7FFFFFFF;
+    }
+
+    /** 32 位循环左移 */
+    public static int rot32(int a, int k) {
+        int s = k & 31;
+        return (a << s) | (a >>> (32 - s));
+    }
+
+    // === 线性变换（与标准一致） ===
+
+    public static int L1(int x) {
+        // TODO: 填入 L1 具体移位与异或
+        throw new UnsupportedOperationException("TODO: L1");
+    }
+
+    public static int L2(int x) {
+        // TODO: 填入 L2 具体移位与异或
+        throw new UnsupportedOperationException("TODO: L2");
+    }
+
+    // === 组装整数 ===
+
+    /** makeU31: 由 4 个 8bit 组为 31bit 值（按标准约定截断/掩码） */
+    public static int makeU31(int a, int b, int c, int d) {
+        // TODO: 对齐 C 代码的拼接与掩码方式
+        int v = ((a & 0xFF) << 23)
+                | ((b & 0xFF) << 15)
+                | ((c & 0xFF) << 7)
+                | ((d & 0x7F));
+        return v & 0x7FFFFFFF;
+    }
+
+    /** makeU32: 由 4 个 8bit 组为 32bit 值（大端） */
+    public static int makeU32(int a, int b, int c, int d) {
+        return ((a & 0xFF) << 24)
+                | ((b & 0xFF) << 16)
+                | ((c & 0xFF) << 8)
+                |  (d & 0xFF);
+    }
+
+    // === IV 处理与打印 ===
+
+    /** 将 25 字节输入提取/压缩为 23 字节 IV（按你的 C 规则） */
+    public static void extractIv(byte[] input25Byte, byte[] output23Byte) {
+        // TODO: 按 C 逻辑实现
+        throw new UnsupportedOperationException("TODO: extractIv");
+    }
+
+    /** 打印十六进制（调试用，生产/JC 环境可移除） */
+    public static void printHex(String label, byte[] data, int len) {
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < len; i++) {
+            sb.append(String.format(Locale.ROOT, "%02X", data[i]));
+            if (i + 1 < len) sb.append(i % 16 == 15 ? "\n" : " ");
+        }
+        System.out.println(label + ":\n" + sb);
+    }
+}