mlkem-sync/.claude/plans/encaps_plan.md

ML-KEM Encaps 顶层集成 — 实现计划

在现有 mlkem_top(KeyGen 已 KAT 通过)基础上扩展 Encaps(FIPS 203 Alg 17 + K-PKE.Encrypt Alg 14)。 决策(已与用户确认):(1) 统一进 mlkem_top(加 op_i 选择 + ST_ENC_* 状态,复用同一套叶子 + BRAM 银行);(2) 一上来就做全 K(2/3/4);(3) golden 只做端到端 KAT(ct==KAT.ct, ss==KAT.ss),逐级用 dbg tap 在 bring-up 时对拍。

算法(Encaps,全 K)

输入:ek(=KAT.pk,384K+32 B)、m(=KAT.msg,32 B)。输出:K=ss(32 B)、c=ct(32·(du·K+dv) B)。

1. h = H(ek) = SHA3-256(ek)，多块。
2. (K_ss, r) = G(m ‖ h) = SHA3-512(64 B,单块)。K_ss = hash[255:0]，r = hash[511:256]。ss 即 K_ss,无 KDF/J。
3. t̂[i] = byteDecode₁₂(ek[i·384 .. (i+1)·384])，i∈0..K-1；rho = ek[384K .. 384K+32]。
4. Â[i][j] = SampleNTT(rho‖j‖i) —— 与 KeyGen ST_A 完全相同。
5. y[i] = CBD_η1(PRF(r, i))，i=0..K-1(nonce 0..K-1)。
6. e1[i] = CBD_η2(PRF(r, K+i))，i=0..K-1(nonce K..2K-1)。η2 恒=2。
7. e2 = CBD_η2(PRF(r, 2K))(nonce 2K)。
8. ŷ[i] = NTT(y[i])(mode=0)。
9. u[i] = INTT(Σⱼ Â[j][i]∘ŷ[j]) + e1[i]，i=0..K-1。注意转置:用 Â[j]i,不是 KeyGen 的 Â[i][j]。 INTT = ntt_core mode=1(内置 ×3303 缩放)。
10. mu[c] = Decompress₁(byteDecode₁(m)[c]) = m 第 c bit ? 1665 : 0(无需存储,m 寄存器逐 bit 算)。
11. v = INTT(Σⱼ t̂[j]∘ŷ[j]) + e2 + mu。
12. c1 = byteEncode_du(Compress_du(u[i])) 拼 K 个；c2 = byteEncode_dv(Compress_dv(v))；ct = c1 ‖ c2。
13. du/dv:K=2/3 → (10,4);K=4 → (11,5)。ct 长度:K=2→768,K=3→1088,K=4→1568。

复用与新增

直接复用(零改动或仅加 phase mux)

• u_sha3(sha3_top_shared):H(ek) 多块 + G 单块 —— 与 KeyGen ST_H/ST_G 同。
• 共享 u_keccak:扩 sel_* 4-way mux,加 Encaps phase 选择。
• u_snt(sample_ntt):A 再生 —— 与 ST_A 同。
• u_cbd(sample_cbd):y/e1/e2 —— 新增 η2=2 驱动(eta_i 现仅接 eta1_rt;Encaps 的 e1/e2 phase 驱动 2)。
• u_ntt(ntt_core):ŷ 用 mode=0;u/v 的 INTT 用 mode=1(缩放已内置)。
• u_pmul(poly_mul):点乘 Â[j][i]∘ŷ[j] 与 t̂[j]∘ŷ[j];累加在顶层逐系数 modQ(同 ST_M)。
• 3 个系数银行 bank_a/bank_se/bank_t:容量够,见存储编排,只加 Encaps 的读写 phase mux。

新增 RTL

• byteDecode₁₂:ek 3 字节 → 2 系数。c0=b0|((b1&0xF)<<8); c1=(b1>>4)|(b2<<4)。组合逻辑,流式写 bank_t。
• Compress 实例:实例化现有 comp_decomp_sync(mode=0,d=du/dv),top 当前未用。
• byteEncode_d 通用位打包器(d∈{4,5,10,11}):把 d-bit 压缩值 LSB-first 流式打包成字节写 ct_bram。新增(现有 byteEncode12 是 2→3 硬编码,不通用)。
• mu 流内生成:INTT v 输出时按 m 寄存器对应 bit 加 1665。
• ct_bram(sd_bram W=8 D=2048 A=11):ct 字节缓冲(≤1568 B)。
• ek 载入路径:m_i[255:0] 端口 + ek 流式载入接口(valid/ready 写入 ek_bram),Encaps 前预填。
• 输出:ss_o(寄存器 + dbg tap);ct 经 dbg tap 读 ct_bram(对齐现有"无流式输出、靠 readback"的风格)。
• op_i(KeyGen/Encaps 选择) + 新 FSM 状态。

存储编排(关键 — 全 K 用现有 28 slot 银行不扩容)

• bank_a (D=4096, 16 slot):Â[i][j],K=4 用满 16。
• bank_se (D=2048, 8 slot):y_hat[0..K-1] + e1[0..K-1] = 2K slot(K=4→8,刚好用满)。
• bank_t (D=1024, 4 slot):E0 先放 t̂[0..K-1](从 ek 解码),也用作 e2 的临时家。
• e2 落点:e2 只在算 v 时需要,算 u 时 bank_t 空闲 → e2 暂存 bank_t[K..](K=2/3 有空 slot)。K=4 时 bank_t 4 slot 被 t̂ 占满 → e2 先存 bank_se 某 slot(算 u 阶段 e1 仍在用,故 e2 需独立 slot)。
  • 解法(全 K 统一,避免分支):算 u 时 t̂ 尚未需要 → 先做 u(用 A+y_hat+e1),u 全部算完压缩进 ct 后,e1 已用完 → 复用 bank_se 的 e1 区放 e2,再从 ek 解码 t̂ 进 bank_t 算 v。峰值 slot = 16(A)+ 2K(se)+ 0(t 尚未填)= K=4 时 24 ≤ 28。✅
  • 时序:E_A(填 A)→ E_CBD(y/e1/e2... e2 先丢 bank_t[0])→ E_NTT(y→y_hat)→ E_U(算 u[i],压缩写 ct c1 区)→ E_V_PREP(t̂ 解码进 bank_t,e2 从 bank_t[0] 搬到 bank_se 空 slot 或就地)→ E_V(算 v,+e2+mu,压缩写 ct c2 区)。
  • 简化:e2 在 E_CBD 阶段先存 bank_se 的 e1 区之后的 slot 不够(K=4)。改为 e2 存 bank_t[0](此时 t̂ 未填),E_V_PREP 时 t̂ 从 ek 流式解码覆盖 bank_t,但 e2 要先读出暂存(单 poly 256×12b 可进一个小 reg 阵列,或搬到 bank_se 算完 u 后的空位)。bring-up 时定稿,以 dbg tap 验证。

运行时参数(新增)

eta2_rt = 2'd2;                              // 恒定
du_rt   = (k==4) ? 5'd11 : 5'd10;
dv_rt   = (k==4) ? 5'd5  : 5'd4;
c1_bytes_rt = 32*du_rt*k_r;                  // K2:640 K3:960 K4:1408
c2_bytes_rt = 32*dv_rt;                      // K2:128 K3:128 K4:160
ct_bytes_rt = c1_bytes_rt + c2_bytes_rt;     // 768 / 1088 / 1568

顶层接口新增

• op_i (1b):0=KeyGen(现有),1=Encaps。在 start_i 锁存为 op_r。
• m_i [255:0]:Encaps 消息(byte0 在低)。
• ek 载入:ek_in_valid_i/ek_in_byte_i[7:0]/ek_in_ready_o(或复用 dbg 写口),Encaps 前把 ek 流进 ek_bram。
• ss_o [255:0] + done_o(复用);ct 经 dbg_ct_idx_i[10:0] → dbg_ct_o[7:0] readback。

实现阶段(逐阶段 KAT/dbg 对拍)

• E0 — 脚手架 + ek 载入 + H/G:加 op_i/m_i/ek 载入,ST_ENC_LOAD→ST_ENC_H(H(ek))→ST_ENC_G(G(m‖h))。dbg 验证 ss=K_ss、r(对 ml-kem-r logging::Encaps 的 K/r/H(ek))。
• E1 — A 再生 + t̂ 解码:ST_ENC_A 复用 snt 写 bank_a;byteDecode12 把 ek 解码进 bank_t。dbg 读系数对 KeyGen golden 的 Ahat / 对 KAT pk 解码的 t̂。
• E2 — y/e1/e2 采样 (η1/η2):ST_ENC_C,nonce 0..2K,eta 在 e1/e2 切 2。dbg 验证 y/e1/e2(对 ml-kem-r)。
• E3 — ŷ = NTT(y):ST_ENC_N,mode=0,就地。dbg 对 y_hat。
• E4 — u = INTT(Σ Â[j][i]∘ŷ[j]) + e1:ST_ENC_U,poly_mul + 累加 + INTT(mode=1) + 加 e1。转置寻址 slot=j·K+i。dbg 对 u。
• E5 — Compress_du + byteEncode_du → c1 ✅:comp_decomp(mode0,d=du) + 通用 LSB-first 打包器(ST_ENC_C1)写 ct_bram c1 区。dbg_ct tap 比 ct[0..c1_bytes]==KAT.ct 前缀,K=2/3/4 全过(含 K=4 du=11 跨字节)。runner = ./run_tb.sh enc [K] [CASE](已并入 run_tb;旧 run_enc.sh 已删)。
• E6 — v = INTT(Σ t̂[j]∘ŷ[j]) + e2 + mu ✅:ST_ENC_C1→ST_ENC_TDEC(t̂ 解码进 bank_a slot j·K)→ST_ENC_E2MV(e2 从 bank_t[0] 搬到 bank_a[1])→ST_ENC_V(复用 u_* MAC/INTT/ADD,u_row≡0)。mu[w]=m_r[w]?1665:0。v 落 bank_t[UPSUM],dbg slot 9(K=2)。dbg 对 v==ml-kem-r golden 全过。踩坑:e2 搬迁曾 off-by-one(写 e2[i+1] 到 slot i),已修(em_widx==em_ridx,写延后 1 拍对齐 bram 读)。 verify_e1 已废弃(TDEC 覆盖 bank_a 的 A_hat;A_hat 由 E4 转置 MAC 间接验证)。
• E7 — Compress_dv + byteEncode_dv → c2 + 端到端 KAT ✅:ST_ENC_V→ST_ENC_C2,复用 E5 打包器(cp_d=dv,coeff 源 bank_t[UPSUM]=v,poly 数=1),cp_wa 接着 c1_bytes 续写(不重置)。FSM:V→C2→DONE。verify_e7 比全长 ct==KAT.ct。全 K(2/3/4)、多 case 端到端通过:ct==KAT.ct && ss==KAT.ss。Encaps 完成。

验证

• TB tb_mlkem_enc_katK_xsim.v:从 ~/Dev/ml-kem-r/test_data/kat_MLKEM_{512,768,1024}.rsp 取 pk(→ek)、msg(→m)、ct、ss,逐字节比 ct + 比 ss。
• bring-up 中间对拍:cargo run --example logging(已有 Encaps log::debug,输出 K/r/H(ek)/|c|),或临时加 dump_encaps.rs 出 256-coeff 中间量(仅工作树,不提交 ml-kem-r)。
• XSIM 环境同 KeyGen:source settings64.sh; export LD_PRELOAD=libtinfo.so.5; rm -rf xsim.dir .Xil。

风险 / 注意

• 转置:Encrypt 用 Â[j][i],KeyGen 用 Â[i][j]。slot = j*K+i(列优先)。最易错,E4 单列 dbg 对拍。
• G 字节序:KeyGen G 输入 d 原序无翻转(keygen_plan 已确认);但 xcheck 发现 KAT 文件 d/z 存的是翻转序。m 喂入字节序需 E0 用 KAT.msg 实测确认(很可能与 d 同约定)。
• INTT 缩放:ntt_core mode=1 已内置 ×3303,不要再缩放。
• e2 落点(K=4):见存储编排,bring-up 定稿,dbg 验证不踩 t̂/e1。
• byteEncode_d 通用打包:d=10/11 跨字节,位序 LSB-first(同 byte_encode)。新写、单独 TB 或 E5 dbg 即验。
• 共享 keccak 4-way mux:加 Encaps phase 的 sel_ + kc_valid_o 门控,勿与 KeyGen phase 冲突(op_r 已区分)。