跳转到内容

std.crypto.ml_dsa

标准库Zig 0.17.0官方原文
源码std/crypto/ml_dsa.zig

第 1 行

NIST FIPS 204 规定的基于模格的数字签名算法(ML-DSA)。

ML-DSA 是具备后量子安全性的数字签名方案,其安全性基于 模格上的带误差模学习(MLWE)和模短整数解(MSIS) 问题的困难性。

提供三组参数:

  • ML-DSA-44:NIST 安全类别 2(128 位安全性)
  • ML-DSA-65:NIST 安全类别 3(192 位安全性)
  • ML-DSA-87:NIST 安全类别 5(256 位安全性)

std.crypto.ml_dsa.assert

别名

第 16 行

别名目标 std.debug.assert

std.crypto.ml_dsa.bitMask

函数

第 3458 行

根据单个位值创建全一或全零掩码。 若 bit == 1,则返回全一(0xFF...FF);若 bit == 0,则返回全零。

fn bitMask(comptime T: type, bit: T) T

参数

T: type
bit: T

std.crypto.ml_dsa.builtin

常量

第 14 行

std.crypto.ml_dsa.centeredToPositive

函数

第 1126 行

将系数从中心化表示转换为非负表示。 将值从 [0,γ₁] ∪ (Q-γ₁, Q) 变换到 [0, 2γ₁)。

fn centeredToPositive(val: u32, comptime gamma1: u32) u32

参数

val: u32
gamma1: u32

std.crypto.ml_dsa.computeInvZetas

函数

第 732 行

fn computeInvZetas() [N]u32

std.crypto.ml_dsa.computeZetas

函数

第 716 行

fn computeZetas() [N]u32

std.crypto.ml_dsa.ContextTooLongError

别名

第 23 行

别名目标 std.crypto.errors.ContextTooLongError

std.crypto.ml_dsa.crypto

别名

第 17 行

别名目标 std.crypto

std.crypto.ml_dsa.D

常量

第 117 行

u32

std.crypto.ml_dsa.decompose

类型函数

第 817 行

将 0 ≤ a < q 拆为 a0 和 a1,使 a = a1alpha + a0,且 -alpha/2 < a0 ≤ alpha/2; 例外是本应有 a1 = (q-1)/alpha 时,改取 a1=0, 且 -alpha/2 ≤ a0 < 0。返回 a0 + q。注意 0 ≤ a1 < (q-1)/alpha。 回顾:alpha = 2gamma2。

fn decompose(a: u32, comptime gamma2: u32) struct { a0_plus_q: u32, a1: u32 }

参数

a: u32
gamma2: u32

std.crypto.ml_dsa.dotHat

函数

第 672 行

fn dotHat(comptime len: u8, a: PolyVec(len), b: PolyVec(len)) Poly

参数

len: u8
a: PolyVec(len)
b: PolyVec(len)

std.crypto.ml_dsa.EncodingError

别名

第 24 行

别名目标 std.crypto.errors.EncodingError

std.crypto.ml_dsa.errors

别名

第 18 行

别名目标 std.crypto.errors

std.crypto.ml_dsa.expandMask

函数

第 1398 行

采样多项式,其系数在 (-gamma1, gamma1] 中均匀分布。 用于签名期间采样掩码向量 y。 FIPS 204:ExpandMask(算法 28)。

fn expandMask(comptime gamma1_bits: u8, seed: *const [64]u8, nonce: u16) Poly

参数

gamma1_bits: u8
seed: *const [64]u8
nonce: u16

std.crypto.ml_dsa.expandS

函数

第 1281 行

使用给定种子和 nonce,通过 SHAKE-256 均匀采样 p, 使系数范数小于或等于 η。 多项式不会归一化,系数位于 [q-η, q+η]。 FIPS 204:ExpandS,算法 27。

fn expandS(comptime eta: u8, seed: *const [64]u8, nonce: u16) Poly

参数

eta: u8
seed: *const [64]u8
nonce: u16

std.crypto.ml_dsa.extendedEuclidean

类型函数

第 3384 行

扩展欧几里得算法。 仅用于编译期值;重视正确性,不重视性能。

fn extendedEuclidean(comptime T: type, comptime a_: T, comptime b_: T) struct { gcd: T, x: T, y: T }

参数

T: type
a_: T
b_: T

std.crypto.ml_dsa.hexToBytes

函数

第 3075 行

fn hexToBytes(comptime hex: []const u8, out: []u8) !void

参数

hex: []const u8
out: []u8

std.crypto.ml_dsa.inv_zetas

常量

第 730 行

std.crypto.ml_dsa.le2Q

函数

第 684 行

fn le2Q(x: u32) u32

参数

x: u32

std.crypto.ml_dsa.le2qModQ

函数

第 699 行

fn le2qModQ(x: u32) u32

参数

x: u32

std.crypto.ml_dsa.makeHint

函数

第 859 行

创建提示位,帮助在小幅扰动后恢复高位。 给定:

  • z0:修改后的低位 r0 - f mod Q,其中 f 很小。
  • r1:原高位。 需要提示时返回 1,否则返回 0。

实现 FIPS 204 中的 makeHint。提示使得无需明确知道 f,也能从 r' = r - f 恢复 r1。

fn makeHint(z0: u32, r1: u32, comptime gamma2: u32) u32

参数

z0: u32
r1: u32
gamma2: u32

std.crypto.ml_dsa.Mat

类型函数

第 622 行

fn Mat(comptime k: u8, comptime l: u8) type

参数

k: u8
l: u8

字段

rows: [k]PolyVec(l)

std.crypto.ml_dsa.Mat.derive

函数

第 632 行

使用 SHAKE-128 从种子 rho 展开矩阵 A。 这是 FIPS 204 中的 ExpandA 函数。

fn derive(rho: *const [32]u8) Self

参数

rho: *const [32]u8

std.crypto.ml_dsa.Mat.mulVec

函数

第 649 行

在 NTT 域中将矩阵与向量相乘,并以普通域返回结果。 接受 NTT 形式的向量,返回普通形式的乘积。

fn mulVec(self: Self, v_hat: VecL) VecK

参数

self: Self
v_hat: VecL

std.crypto.ml_dsa.Mat.mulVecHat

函数

第 661 行

在 NTT 域中计算矩阵与向量的乘积,并返回 NTT 域中的结果。 接受 NTT 形式的向量,返回 NTT 形式的乘积。

fn mulVecHat(self: Self, v_hat: VecL) VecK

参数

self: Self
v_hat: VecL

std.crypto.ml_dsa.Mat.Self

别名

第 626 行

别名目标 std.crypto.ml_dsa.Mat

std.crypto.ml_dsa.Mat.VecK

类型

第 628 行

std.crypto.ml_dsa.Mat.VecL

类型

第 627 行

std.crypto.ml_dsa.math

别名

第 19 行

别名目标 std.math

std.crypto.ml_dsa.mem

别名

第 20 行

别名目标 std.mem

std.crypto.ml_dsa.MLDSA44

类型

第 47 行

NIST FIPS 204 规定的 ML-DSA-44,即基于模格的数字签名算法的 44 参数集。

这是一种后量子签名方案,提供 NIST 安全类别 2,大致相当于 SHA-256 或 AES-128 的安全性。

密钥大小:

  • 公钥:1312 字节
  • 私钥:2560 字节
  • 签名:2420 字节

使用示例:

const kp = MLDSA44.KeyPair.generate();
const msg = "Hello, post-quantum world!";
const sig = try kp.sign(msg, null);
try sig.verify(msg, kp.public_key);

std.crypto.ml_dsa.MLDSA65

类型

第 74 行

NIST FIPS 204 规定的 ML-DSA-65, 即基于模格的数字签名算法的 65 参数集。

这是一种后量子签名方案,提供 NIST 安全类别 3, 大致相当于 SHA-384 或 AES-192 的安全性。

密钥大小:

  • 公钥:1952 字节
  • 私钥:4032 字节
  • 签名:3309 字节

此参数集以更大的密钥和签名 换取比 ML-DSA-44 更高的安全性。

std.crypto.ml_dsa.MLDSA87

类型

第 101 行

NIST FIPS 204 规定的 ML-DSA-87,即基于模格的数字签名算法的 87 参数集。

这是一种后量子签名方案,提供 NIST 安全类别 5,大致相当于 SHA-512 或 AES-256 的安全性。

密钥大小:

  • 公钥:2592 字节
  • 私钥:4896 字节
  • 签名:4627 字节

此参数集在三种 ML-DSA 变体中提供最高安全级别,适用于需要最高安全保证的应用。

std.crypto.ml_dsa.MLDSAImpl

类型函数

第 1416 行

fn MLDSAImpl(comptime p: Params) type

参数

p: Params

std.crypto.ml_dsa.MLDSAImpl.alpha

常量

第 1422 行

u32

std.crypto.ml_dsa.MLDSAImpl.beta

常量

第 1421 行

u32

std.crypto.ml_dsa.MLDSAImpl.computeT

函数

第 1484 行

计算 t = As1 + s2 的辅助函数。 用于密钥生成和公钥重建。

fn computeT(A: MatKxL, s1_hat: PolyVecL, s2: PolyVecK) PolyVecK

参数

A: MatKxL
s1_hat: PolyVecL
s2: PolyVecK

std.crypto.ml_dsa.MLDSAImpl.crh

函数

第 1472 行

使用 SHAKE-256 计算 CRH(抗碰撞哈希)的辅助函数。 统一封装哈希操作中重复出现的 init-update-squeeze 模式。

fn crh(comptime outsize: usize, inputs: anytype) [outsize]u8

参数

outsize: usize

std.crypto.ml_dsa.MLDSAImpl.gamma1

常量

第 1420 行

u32

std.crypto.ml_dsa.MLDSAImpl.KeyPair

容器

第 2011 行

由私钥及其对应公钥组成的密钥对。

字段

public_key: PublicKey

公钥分量。

secret_key: SecretKey

秘密密钥分量。

std.crypto.ml_dsa.MLDSAImpl.KeyPair.fromSecretKey

函数

第 2041 行

从已有私钥派生公钥。 从私钥重新计算公钥的各个部分。

pub fn fromSecretKey(sk: SecretKey) !KeyPair

参数

sk: SecretKey

std.crypto.ml_dsa.MLDSAImpl.KeyPair.generate

函数

第 2022 行

生成新的随机密钥对。

pub fn generate(io: std.Io) KeyPair

参数

io: std.Io

std.crypto.ml_dsa.MLDSAImpl.KeyPair.generateDeterministic

函数

第 2031 行

根据种子确定性地生成密钥对。 用于测试或要求可重现性的场景。 种子应使用密码学安全的随机源生成。

pub fn generateDeterministic(seed: [32]u8) !KeyPair

参数

seed: [32]u8

std.crypto.ml_dsa.MLDSAImpl.KeyPair.seed_length

别名

第 2013 行

创建密钥对所需种子的长度(字节)。

别名目标 std.crypto.ml_dsa.MLDSAImpl.seed_length

std.crypto.ml_dsa.MLDSAImpl.KeyPair.sign

函数

第 2077 行

使用此密钥对对消息签名。 noise 参数可以为 null,以生成确定性签名; 也可提供随机性以生成对冲签名(建议用于抵御故障攻击)。

pub fn sign( kp: KeyPair, msg: []const u8, noise: ?[noise_length]u8, ) !Signature

参数

kp: KeyPair
msg: []const u8
noise: ?[noise_length]u8

std.crypto.ml_dsa.MLDSAImpl.KeyPair.signer

函数

第 2062 行

创建 Signer,用于增量签署消息。 noise 参数可为 null,以生成确定性签名; 也可提供随机性生成对冲签名,建议用于抵抗故障攻击。

pub fn signer(self: *const KeyPair, noise: ?[noise_length]u8) !Signer

参数

self: *const KeyPair
noise: ?[noise_length]u8

std.crypto.ml_dsa.MLDSAImpl.KeyPair.signerWithContext

函数

第 2070 行

创建 Signer,用于对带上下文的消息增量签名。 noise 参数可为 null,以生成确定性签名; 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。 context 参数为可选的上下文字符串(最多 255 字节)。

pub fn signerWithContext(self: *const KeyPair, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer

参数

self: *const KeyPair
noise: ?[noise_length]u8
context: []const u8

错误

ContextTooLong ContextTooLongError

std.crypto.ml_dsa.MLDSAImpl.KeyPair.signWithContext

函数

第 2089 行

使用此密钥对,对带上下文的消息签名。 noise 参数可为 null,以生成确定性签名; 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。 context 参数为可选的上下文字符串(最多 255 字节)。

pub fn signWithContext( kp: KeyPair, msg: []const u8, noise: ?[noise_length]u8, context: []const u8, ) ContextTooLongError!Signature

参数

kp: KeyPair
msg: []const u8
noise: ?[noise_length]u8
context: []const u8

错误

ContextTooLong ContextTooLongError

std.crypto.ml_dsa.MLDSAImpl.MatKxL

类型

第 1427 行

std.crypto.ml_dsa.MLDSAImpl.name

常量

第 1419 行

std.crypto.ml_dsa.MLDSAImpl.newKeyFromSeed

类型函数

第 1650 行

由种子生成新密钥对(确定性)

pub fn newKeyFromSeed(seed: *const [seed_length]u8) struct { pk: PublicKey, sk: SecretKey }

参数

seed: *const [seed_length]u8

std.crypto.ml_dsa.MLDSAImpl.noise_length

常量

第 1433 行

用于非确定性签名的可选随机字节长度(单位为字节)。

std.crypto.ml_dsa.MLDSAImpl.params

常量

第 1418 行

std.crypto.ml_dsa.MLDSAImpl.polyLeGamma1PackedSize

函数

第 1454 行

fn polyLeGamma1PackedSize() usize

std.crypto.ml_dsa.MLDSAImpl.polyLeqEtaPackedSize

函数

第 1447 行

fn polyLeqEtaPackedSize() usize

std.crypto.ml_dsa.MLDSAImpl.polyT0PackedSize

函数

第 1462 行

fn polyT0PackedSize() usize

std.crypto.ml_dsa.MLDSAImpl.polyT1PackedSize

函数

第 1458 行

fn polyT1PackedSize() usize

std.crypto.ml_dsa.MLDSAImpl.PolyVecK

类型

第 1426 行

std.crypto.ml_dsa.MLDSAImpl.PolyVecL

类型

第 1425 行

std.crypto.ml_dsa.MLDSAImpl.polyW1PackedSize

函数

第 1466 行

fn polyW1PackedSize() usize

std.crypto.ml_dsa.MLDSAImpl.private_key_bytes

常量

第 1439 行

编码后秘密密钥的字节大小。

usize

std.crypto.ml_dsa.MLDSAImpl.public_key_bytes

常量

第 1436 行

已编码公钥的大小,单位为字节。

usize

std.crypto.ml_dsa.MLDSAImpl.PublicKey

容器

第 1490 行

ML-DSA 公钥

字段

rho: [32]u8
t1: PolyVecK
t1_packed: [polyT1PackedSize() * p.k]u8
A: MatKxL
tr: [p.tr_size]u8

std.crypto.ml_dsa.MLDSAImpl.PublicKey.encoded_length

常量

第 1492 行

编码后的公钥大小,单位为字节

usize

std.crypto.ml_dsa.MLDSAImpl.PublicKey.fromBytes

函数

第 1511 行

从字节解码公钥

pub fn fromBytes(bytes: [encoded_length]u8) !PublicKey

参数

bytes: [encoded_length]u8

std.crypto.ml_dsa.MLDSAImpl.PublicKey.toBytes

函数

第 1503 行

将公钥编码为字节

pub fn toBytes(self: PublicKey) [encoded_length]u8

参数

self: PublicKey

std.crypto.ml_dsa.MLDSAImpl.SecretKey

容器

第 1525 行

ML-DSA 秘密密钥

字段

rho: [32]u8
key: [32]u8
tr: [p.tr_size]u8
s1: PolyVecL
s2: PolyVecK
t0: PolyVecK
A: MatKxL
s1_hat: PolyVecL
s2_hat: PolyVecK
t0_hat: PolyVecK

std.crypto.ml_dsa.MLDSAImpl.SecretKey.encoded_length

常量

第 1527 行

已编码私钥的大小,单位为字节

usize

std.crypto.ml_dsa.MLDSAImpl.SecretKey.fromBytes

函数

第 1578 行

从字节解码秘密密钥

pub fn fromBytes(bytes: [encoded_length]u8) !SecretKey

参数

bytes: [encoded_length]u8

std.crypto.ml_dsa.MLDSAImpl.SecretKey.public

函数

第 1616 行

从此私钥计算公钥

pub fn public(self: *const SecretKey) PublicKey

参数

self: *const SecretKey

std.crypto.ml_dsa.MLDSAImpl.SecretKey.signer

函数

第 1636 行

创建 Signer,用于增量签署消息。 noise 参数可为 null,以生成确定性签名; 也可提供随机性生成对冲签名,建议用于抵抗故障攻击。

pub fn signer(self: *const SecretKey, noise: ?[noise_length]u8) !Signer

参数

self: *const SecretKey
noise: ?[noise_length]u8

std.crypto.ml_dsa.MLDSAImpl.SecretKey.signerWithContext

函数

第 1644 行

创建 Signer,用于对带上下文的消息增量签名。 noise 参数可为 null,以生成确定性签名; 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。 context 参数为可选的上下文字符串(最多 255 字节)。

pub fn signerWithContext(self: *const SecretKey, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer

参数

self: *const SecretKey
noise: ?[noise_length]u8
context: []const u8

错误

ContextTooLong ContextTooLongError

std.crypto.ml_dsa.MLDSAImpl.SecretKey.toBytes

函数

第 1544 行

将秘密密钥编码为字节

pub fn toBytes(self: SecretKey) [encoded_length]u8

参数

self: SecretKey

std.crypto.ml_dsa.MLDSAImpl.seed_length

常量

第 1430 行

用于确定性密钥生成的种子长度(32 字节)。

usize

std.crypto.ml_dsa.MLDSAImpl.Self

别名

第 1424 行

别名目标 std.crypto.ml_dsa.MLDSAImpl

std.crypto.ml_dsa.MLDSAImpl.Signature

容器

第 1693 行

ML-DSA 签名

字段

c_tilde: [p.ctilde_size]u8
z: PolyVecL
hint: PolyVecK

std.crypto.ml_dsa.MLDSAImpl.signature_bytes

常量

第 1443 行

已编码签名的大小,单位为字节。

usize

std.crypto.ml_dsa.MLDSAImpl.Signature.encoded_length

常量

第 1695 行

编码后签名的字节大小

usize

std.crypto.ml_dsa.MLDSAImpl.Signature.fromBytes

函数

第 1719 行

从字节解码签名

pub fn fromBytes(bytes: [encoded_length]u8) EncodingError!Signature

参数

bytes: [encoded_length]u8

错误

InvalidEncoding EncodingError

std.crypto.ml_dsa.MLDSAImpl.Signature.toBytes

函数

第 1703 行

将签名编码为字节

pub fn toBytes(self: Signature) [encoded_length]u8

参数

self: Signature

std.crypto.ml_dsa.MLDSAImpl.Signature.verifier

函数

第 1804 行

创建用于增量验证签名的 Verifier。

pub fn verifier(self: Signature, public_key: PublicKey) !Verifier

参数

self: Signature
public_key: PublicKey

std.crypto.ml_dsa.MLDSAImpl.Signature.verifierWithContext

函数

第 1810 行

创建 Verifier,用于带上下文的增量签名验证。 context 参数是可选的上下文字符串(最多 255 字节)。

pub fn verifierWithContext(self: Signature, public_key: PublicKey, context: []const u8) ContextTooLongError!Verifier

参数

self: Signature
public_key: PublicKey
context: []const u8

错误

ContextTooLong ContextTooLongError

std.crypto.ml_dsa.MLDSAImpl.Signature.verify

函数

第 1743 行

针对消息和公钥验证此签名。 签名无效则返回错误。

pub fn verify( sig: Signature, msg: []const u8, public_key: PublicKey, ) VerifyError!void

参数

sig: Signature
msg: []const u8
public_key: PublicKey

错误

InvalidEncoding EncodingError
SignatureVerificationFailed SignatureVerificationError

std.crypto.ml_dsa.MLDSAImpl.Signature.VerifyError

错误集合

第 1739 行

错误

InvalidEncoding EncodingError
SignatureVerificationFailed SignatureVerificationError

std.crypto.ml_dsa.MLDSAImpl.Signature.verifyWithContext

函数

第 1754 行

根据消息、公钥及上下文验证此签名。 若签名无效,则返回错误。 context 参数为可选上下文字符串,最长 255 字节。

pub fn verifyWithContext( sig: Signature, msg: []const u8, public_key: PublicKey, context: []const u8, ) VerifyError!void

参数

sig: Signature
msg: []const u8
public_key: PublicKey
context: []const u8

错误

InvalidEncoding EncodingError
SignatureVerificationFailed SignatureVerificationError

std.crypto.ml_dsa.MLDSAImpl.Signer

容器

第 1817 行

Signer 用于对流式消息增量计算签名。 可通过 signer() 函数从 SecretKey 或 KeyPair 获取。

字段

h: sha3.Shake256
secret_key: *const SecretKey
rnd: [32]u8

std.crypto.ml_dsa.MLDSAImpl.Signer.finalize

函数

第 1852 行

计算整个消息的签名。

pub fn finalize(self: *Signer) Signature

参数

self: *Signer

std.crypto.ml_dsa.MLDSAImpl.Signer.init

函数

第 1826 行

初始化新的 Signer。 noise 参数可为 null,以生成确定性签名; 也可提供随机性以生成带随机防护的签名,建议用于抵御故障攻击。 context 参数是可选的上下文字符串,最长 255 字节。

pub fn init(secret_key: *const SecretKey, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer

参数

secret_key: *const SecretKey
noise: ?[noise_length]u8
context: []const u8

错误

ContextTooLong ContextTooLongError

std.crypto.ml_dsa.MLDSAImpl.Signer.update

函数

第 1847 行

向正在签名的消息加入新数据。

pub fn update(self: *Signer, data: []const u8) void

参数

self: *Signer
data: []const u8

std.crypto.ml_dsa.MLDSAImpl.Verifier

容器

第 1941 行

Verifier 用于对流式消息增量验证签名。 可通过 Signature 的 verifier() 函数获取。

字段

h: sha3.Shake256
signature: Signature
public_key: PublicKey

std.crypto.ml_dsa.MLDSAImpl.Verifier.init

函数

第 1951 行

初始化新的 Verifier。 context 参数是可选的上下文字符串,最长 255 字节。

pub fn init(signature: Signature, public_key: PublicKey, context: []const u8) ContextTooLongError!Verifier

参数

signature: Signature
public_key: PublicKey
context: []const u8

错误

ContextTooLong ContextTooLongError

std.crypto.ml_dsa.MLDSAImpl.Verifier.InitError

别名

第 1946 行

别名目标 std.crypto.ml_dsa.EncodingError

std.crypto.ml_dsa.MLDSAImpl.Verifier.update

函数

第 1972 行

向待验证消息添加新内容。

pub fn update(self: *Verifier, data: []const u8) void

参数

self: *Verifier
data: []const u8

std.crypto.ml_dsa.MLDSAImpl.Verifier.verify

函数

第 1977 行

验证签名对整个消息有效。

pub fn verify(self: *Verifier) SignatureVerificationError!void

参数

self: *Verifier

错误

SignatureVerificationFailed SignatureVerificationError

std.crypto.ml_dsa.MLDSAImpl.Verifier.VerifyError

别名

第 1947 行

别名目标 std.crypto.ml_dsa.SignatureVerificationError

std.crypto.ml_dsa.modQ

函数

第 694 行

fn modQ(x: u32) u32

参数

x: u32

std.crypto.ml_dsa.modularInverse

函数

第 3412 行

模逆:计算 a^(-1) mod p 要求 gcd(a,p) = 1。结果规范化到范围 [0, p)。

fn modularInverse(comptime T: type, comptime a: T, comptime p: T) T

参数

T: type
a: T
p: T

std.crypto.ml_dsa.modularPow

函数

第 3436 行

模幂:使用平方乘算法计算 a^s mod p。

fn modularPow(comptime T: type, comptime a: T, s: T, comptime p: T) T

参数

T: type
a: T
s: T
p: T

std.crypto.ml_dsa.montgomeryReduce

函数

第 3489 行

蒙哥马利约减:对于输入 x,返回满足 y ≡ x*R^(-1) (mod q) 的 y。 此通用实现由模数 q、其逆元 qInv、 蒙哥马利常量 R 及结果边界参数化。

对于 ML-DSA:R = 2^32,返回 y < 2q。 对于 ML-KEM:R = 2^16,返回范围为 (-q, q) 的 y。

fn montgomeryReduce( comptime InT: type, comptime OutT: type, comptime q: comptime_int, comptime qInv: comptime_int, comptime r_bits: comptime_int, x: InT, ) OutT

参数

InT: type
OutT: type
q: comptime_int
qInv: comptime_int
r_bits: comptime_int
x: InT

std.crypto.ml_dsa.montReduceLe2Q

函数

第 707 行

fn montReduceLe2Q(x: u64) u32

参数

x: u64

std.crypto.ml_dsa.N

常量

第 114 行

usize

std.crypto.ml_dsa.Params

容器

第 131 行

字段

name: []const u8
k: u8
l: u8
eta: u8
omega: u16
tau: u16
gamma1_bits: u8
gamma2: u32
tr_size: usize
ctilde_size: usize

std.crypto.ml_dsa.Poly

容器

第 156 行

字段

cs: [N]u32

std.crypto.ml_dsa.Poly.add

函数

第 162 行

fn add(a: Poly, b: Poly) Poly

参数

a: Poly
b: Poly

std.crypto.ml_dsa.Poly.exceeds

函数

第 287 行

fn exceeds(p: Poly, bound: u32) bool

参数

p: Poly
bound: u32

std.crypto.ml_dsa.Poly.invNTT

函数

第 243 行

fn invNTT(p: Poly) Poly

参数

p: Poly

std.crypto.ml_dsa.Poly.invNTTInPlace

函数

第 250 行

fn invNTTInPlace(p: *Poly) void

参数

p: *Poly

std.crypto.ml_dsa.Poly.mulHat

函数

第 207 行

fn mulHat(a: Poly, b: Poly) Poly

参数

a: Poly
b: Poly

std.crypto.ml_dsa.Poly.normalize

函数

第 189 行

fn normalize(p: Poly) Poly

参数

p: Poly

std.crypto.ml_dsa.Poly.normalizeAssumingLe2Q

函数

第 198 行

fn normalizeAssumingLe2Q(p: Poly) Poly

参数

p: Poly

std.crypto.ml_dsa.Poly.ntt

函数

第 216 行

fn ntt(p: Poly) Poly

参数

p: Poly

std.crypto.ml_dsa.Poly.nttInPlace

函数

第 223 行

fn nttInPlace(p: *Poly) void

参数

p: *Poly

std.crypto.ml_dsa.Poly.power2RoundPoly

类型函数

第 275 行

对所有系数应用 Power2Round 返回 t0 和 t1 两个多项式

fn power2RoundPoly(p: Poly) struct { t0: Poly, t1: Poly }

参数

p: Poly

std.crypto.ml_dsa.Poly.reduceLe2Q

函数

第 180 行

fn reduceLe2Q(p: Poly) Poly

参数

p: Poly

std.crypto.ml_dsa.Poly.sub

函数

第 171 行

fn sub(a: Poly, b: Poly) Poly

参数

a: Poly
b: Poly

std.crypto.ml_dsa.Poly.zero

常量

第 159 行

Poly

std.crypto.ml_dsa.polyDeriveUniform

函数

第 1262 行

fn polyDeriveUniform(seed: *const [32]u8, nonce: u16) Poly

参数

seed: *const [32]u8
nonce: u16

std.crypto.ml_dsa.polyMakeHint

类型函数

第 927 行

为扰动后高位与原始高位的差异创建提示多项式。 返回设置为 1 的提示位数量,即置位计数。

在生成签名时使用,以创建帮助验证方在不访问秘密的情况下恢复高位的提示。

fn polyMakeHint(p0: Poly, p1: Poly, comptime gamma2: u32) struct { hint: Poly, count: u32 }

参数

p0: Poly
p1: Poly
gamma2: u32

std.crypto.ml_dsa.polyPackLeGamma1

函数

第 1136 行

将系数位于 (-gamma1, gamma1] 的多项式打包为字节。 gamma1_bits=17 时:每个系数打包为 18 位,4 个系数占 9 字节。 gamma1_bits=19 时:每个系数打包为 20 位,2 个系数占 5 字节。 假定系数已归一化。

fn polyPackLeGamma1(p: Poly, comptime gamma1_bits: u8, buf: []u8) void

参数

p: Poly
gamma1_bits: u8
buf: []u8

std.crypto.ml_dsa.polyPackLeqEta

函数

第 958 行

将系数位于 [Q-eta, Q+eta] 的多项式打包为字节。 eta=2 时:每个系数打包为 3 位(共 96 字节)。 eta=4 时:每个系数打包为 4 位(共 128 字节)。 假定系数未归一化,但位于 [q-η, q+η]。

fn polyPackLeqEta(p: Poly, comptime eta: u8, buf: []u8) void

参数

p: Poly
eta: u8
buf: []u8

std.crypto.ml_dsa.polyPackT0

函数

第 1071 行

将系数位于 (-2^(D-1), 2^(D-1)](T0)的多项式打包为字节。 每个系数打包 13 位:8 个系数打包为 13 字节。 假定系数未规范化,而是位于 (q-2^(D-1), q+2^(D-1)]。

fn polyPackT0(p: Poly, buf: []u8) void

参数

p: Poly
buf: []u8

std.crypto.ml_dsa.polyPackT1

函数

第 1039 行

将系数 < 1024(T1)的多项式打包为字节。 每个系数占 10 位:4 个系数打包为 5 字节。 假定系数已归一化。

fn polyPackT1(p: Poly, buf: []u8) void

参数

p: Poly
buf: []u8

std.crypto.ml_dsa.polyPackW1

函数

第 1239 行

打包用于验证的 W1 多项式。 gamma1_bits=17 时:每个系数打包为 6 位(4 个系数共 3 字节)。 gamma1_bits=19 时:每个系数打包为 4 位(2 个系数共 1 字节)。 假定系数已归一化。

fn polyPackW1(p: Poly, comptime gamma1_bits: u8, buf: []u8) void

参数

p: Poly
gamma1_bits: u8
buf: []u8

std.crypto.ml_dsa.polyUnpackLeGamma1

函数

第 1185 行

从字节解包系数位于 (-gamma1, gamma1] 的多项式。 输出系数将被规范化。

fn polyUnpackLeGamma1(comptime gamma1_bits: u8, buf: []const u8) Poly

参数

gamma1_bits: u8
buf: []const u8

std.crypto.ml_dsa.polyUnpackLeqEta

函数

第 999 行

从字节解包系数位于 [Q-eta, Q+eta] 的多项式。 输出系数不会归一化,而是位于 [q-η, q+η]。

fn polyUnpackLeqEta(comptime eta: u8, buf: []const u8) Poly

参数

eta: u8
buf: []const u8

std.crypto.ml_dsa.polyUnpackT0

函数

第 1105 行

从字节解包系数位于 (-2^(D-1), 2^(D-1)](T0)的多项式。 输出系数不会归一化,而是位于 (-2^(D-1), 2^(D-1)]。

fn polyUnpackT0(buf: []const u8) Poly

参数

buf: []const u8

std.crypto.ml_dsa.polyUnpackT1

函数

第 1054 行

从字节中解包系数 < 1024 的多项式(T1)。 输出系数将归一化。

fn polyUnpackT1(buf: []const u8) Poly

参数

buf: []const u8

std.crypto.ml_dsa.polyUseHint

函数

第 944 行

应用提示,从扰动后的多项式重建高位。

在签名验证期间,使用签名中提供的提示 恢复高位。

fn polyUseHint(q: Poly, hint: Poly, comptime gamma2: u32) Poly

参数

q: Poly
hint: Poly
gamma2: u32

std.crypto.ml_dsa.PolyVec

类型函数

第 300 行

fn PolyVec(comptime len: u8) type

参数

len: u8

字段

ps: [len]Poly

std.crypto.ml_dsa.PolyVec.add

函数

第 334 行

fn add(a: Self, b: Self) Self

参数

a: Self
b: Self

std.crypto.ml_dsa.PolyVec.decomposeVec

函数

第 490 行

将向量中的每个多项式分解为高位和低位

fn decomposeVec(v: Self, comptime gamma2: u32, w0_out: *Self) Self

参数

v: Self
gamma2: u32
w0_out: *Self

std.crypto.ml_dsa.PolyVec.deriveUniformLeGamma1

函数

第 536 行

采样系数均匀分布于 (-gamma1, gamma1] 的向量 封装 expandMask(FIPS 204:ExpandMask)

fn deriveUniformLeGamma1(comptime gamma1_bits: u8, seed: *const [64]u8, nonce: u16) Self

参数

gamma1_bits: u8
seed: *const [64]u8
nonce: u16

std.crypto.ml_dsa.PolyVec.exceeds

函数

第 363 行

fn exceeds(v: Self, bound: u32) bool

参数

v: Self
bound: u32

std.crypto.ml_dsa.PolyVec.invNTT

函数

第 346 行

fn invNTT(v: Self) Self

参数

v: Self

std.crypto.ml_dsa.PolyVec.makeHintVec

类型函数

第 503 行

为向量创建提示,返回提示中置位的数量。

fn makeHintVec(w0mcs2pct0: Self, w1: Self, comptime gamma2: u32) struct { hint: Self, pop: u32 }

参数

w0mcs2pct0: Self
w1: Self
gamma2: u32

std.crypto.ml_dsa.PolyVec.map

函数

第 308 行

对向量中的每个多项式执行一元运算

fn map(v: Self, comptime op: fn (Poly) Poly) Self

参数

v: Self
op: fn (Poly) Poly

std.crypto.ml_dsa.PolyVec.mapBinary

函数

第 317 行

对两个向量逐对应用二元运算。

fn mapBinary(a: Self, b: Self, comptime op: fn (Poly, Poly) Poly) Self

参数

a: Self
b: Self
op: fn (Poly, Poly) Poly

std.crypto.ml_dsa.PolyVec.mapBinaryPoly

函数

第 326 行

对向量与标量多项式应用二元运算。

fn mapBinaryPoly(v: Self, scalar: Poly, comptime op: fn (Poly, Poly) Poly) Self

参数

v: Self
scalar: Poly
op: fn (Poly, Poly) Poly

std.crypto.ml_dsa.PolyVec.mulBy2toD

函数

第 524 行

将向量乘以 2^D(左移)

fn mulBy2toD(v: Self) Self

参数

v: Self

std.crypto.ml_dsa.PolyVec.normalize

函数

第 350 行

fn normalize(v: Self) Self

参数

v: Self

std.crypto.ml_dsa.PolyVec.normalizeAssumingLe2Q

函数

第 358 行

fn normalizeAssumingLe2Q(v: Self) Self

参数

v: Self

std.crypto.ml_dsa.PolyVec.ntt

函数

第 342 行

fn ntt(v: Self) Self

参数

v: Self

std.crypto.ml_dsa.PolyVec.packHint

函数

第 546 行

将提示打包为字节 格式:对于每个多项式,找出 hint[i]=1 的位置,并编码这些位置

fn packHint(v: Self, comptime omega: u16, buf: []u8) bool

参数

v: Self
omega: u16
buf: []u8

std.crypto.ml_dsa.PolyVec.packLeGamma1

函数

第 457 行

打包系数 < gamma1 的多项式向量

fn packLeGamma1(v: Self, comptime gamma1_bits: u8, buf: []u8) void

参数

v: Self
gamma1_bits: u8
buf: []u8

std.crypto.ml_dsa.PolyVec.packLeGamma1.pack

函数

第 460 行

fn pack(p: Poly, b: []u8) void

参数

p: Poly
b: []u8

std.crypto.ml_dsa.PolyVec.packLeqEta

函数

第 435 行

打包系数位于 [-eta, eta] 内的向量

fn packLeqEta(v: Self, comptime eta: u8, buf: []u8) void

参数

v: Self
eta: u8
buf: []u8

std.crypto.ml_dsa.PolyVec.packLeqEta.pack

函数

第 438 行

fn pack(p: Poly, b: []u8) void

参数

p: Poly
b: []u8

std.crypto.ml_dsa.PolyVec.packT0

函数

第 423 行

将 T0 向量打包为字节

fn packT0(v: Self, buf: []u8) void

参数

v: Self
buf: []u8

std.crypto.ml_dsa.PolyVec.packT1

函数

第 411 行

将 T1 向量打包为字节

fn packT1(v: Self, buf: []u8) void

参数

v: Self
buf: []u8

std.crypto.ml_dsa.PolyVec.packW1

函数

第 479 行

为签名验证打包高位 w1

fn packW1(v: Self, comptime gamma1_bits: u8, buf: []u8) void

参数

v: Self
gamma1_bits: u8
buf: []u8

std.crypto.ml_dsa.PolyVec.packW1.pack

函数

第 482 行

fn pack(p: Poly, b: []u8) void

参数

p: Poly
b: []u8

std.crypto.ml_dsa.PolyVec.packWith

函数

第 384 行

通用向量打包函数

fn packWith( v: Self, buf: []u8, comptime poly_size: usize, comptime pack_fn: fn (Poly, []u8) void, ) void

参数

v: Self
buf: []u8
poly_size: usize
pack_fn: fn (Poly, []u8) void

std.crypto.ml_dsa.PolyVec.power2Round

函数

第 373 行

对向量中的每个多项式应用 Power2Round 返回 t0 和 t1 两个向量

fn power2Round(v: Self, t0_out: *Self) Self

参数

v: Self
t0_out: *Self

std.crypto.ml_dsa.PolyVec.reduceLe2Q

函数

第 354 行

fn reduceLe2Q(v: Self) Self

参数

v: Self

std.crypto.ml_dsa.PolyVec.Self

别名

第 304 行

别名目标 std.crypto.ml_dsa.PolyVec

std.crypto.ml_dsa.PolyVec.sub

函数

第 338 行

fn sub(a: Self, b: Self) Self

参数

a: Self
b: Self

std.crypto.ml_dsa.PolyVec.unpackHint

函数

第 583 行

从字节解包提示

fn unpackHint(comptime omega: u16, buf: []const u8) ?Self

参数

omega: u16
buf: []const u8

std.crypto.ml_dsa.PolyVec.unpackLeGamma1

函数

第 468 行

解包系数 < gamma1 的多项式向量

fn unpackLeGamma1(comptime gamma1_bits: u8, buf: []const u8) Self

参数

gamma1_bits: u8
buf: []const u8

std.crypto.ml_dsa.PolyVec.unpackLeGamma1.unpack

函数

第 471 行

fn unpack(b: []const u8) Poly

参数

b: []const u8

std.crypto.ml_dsa.PolyVec.unpackLeqEta

函数

第 446 行

解包系数位于 [-eta, eta] 的向量。

fn unpackLeqEta(comptime eta: u8, buf: []const u8) Self

参数

eta: u8
buf: []const u8

std.crypto.ml_dsa.PolyVec.unpackLeqEta.unpack

函数

第 449 行

fn unpack(b: []const u8) Poly

参数

b: []const u8

std.crypto.ml_dsa.PolyVec.unpackT0

函数

第 429 行

从字节解包 T0 向量

fn unpackT0(buf: []const u8) Self

参数

buf: []const u8

std.crypto.ml_dsa.PolyVec.unpackT1

函数

第 417 行

从字节解包 T1 向量

fn unpackT1(bytes: []const u8) Self

参数

bytes: []const u8

std.crypto.ml_dsa.PolyVec.unpackWith

函数

第 397 行

向量的通用解包函数

fn unpackWith( comptime poly_size: usize, comptime unpack_fn: fn ([]const u8) Poly, buf: []const u8, ) Self

参数

poly_size: usize
unpack_fn: fn ([]const u8) Poly
buf: []const u8

std.crypto.ml_dsa.PolyVec.useHint

函数

第 515 行

应用提示以恢复高位

fn useHint(v: Self, hint: Self, comptime gamma2: u32) Self

参数

v: Self
hint: Self
gamma2: u32

std.crypto.ml_dsa.PolyVec.zero

常量

第 305 行

Self

std.crypto.ml_dsa.power2Round

类型函数

第 791 行

将 0 ≤ a < Q 拆为 a0 和 a1,满足 a = a1*2^D + a0 及 -2^(D-1) < a0 ≤ 2^(D-1)。返回 a0 + Q 和 a1。 FIPS 204:Power2Round(算法 19)

fn power2Round(a: u32) struct { a0_plus_q: u32, a1: u32 }

参数

a: u32

std.crypto.ml_dsa.Q

常量

第 115 行

u32

std.crypto.ml_dsa.Q_BITS

常量

第 116 行

u32

std.crypto.ml_dsa.Q_INV

常量

第 123 行

u32

std.crypto.ml_dsa.R

常量

第 120 行

u64

std.crypto.ml_dsa.R_OVER_256

常量

第 126 行

u32

std.crypto.ml_dsa.sampleInBall

函数

第 1344 行

使用 SHAKE-256 均匀采样 p,使其具有 τ 个取自 {Q-1, 1} 的非零系数。 由此创建一个恰含 tau 个非零 ±1 系数的“球”多项式。 多项式将归一化为系数取自 {0, 1, Q-1} 的形式。 FIPS 204:SampleInBall(算法 18)

fn sampleInBall(comptime tau: u16, seed: []const u8) Poly

参数

tau: u16
seed: []const u8

std.crypto.ml_dsa.sampleUniformRejection

函数

第 3516 行

使用 SHAKE-128 和拒绝采样进行均匀采样。 通过拒绝采样,从 [0, q) 中均匀采样多项式系数。

参数:

  • PolyType:要返回的多项式类型
  • q:模数
  • bits_per_coef:每个系数的位数,12 或 23
  • n:系数数量
  • seed:随机种子
  • domain_sep:域分离字节,追加到种子之后
fn sampleUniformRejection( comptime PolyType: type, comptime q: comptime_int, comptime bits_per_coef: comptime_int, comptime n: comptime_int, seed: []const u8, domain_sep: []const u8, ) PolyType

参数

PolyType: type
q: comptime_int
bits_per_coef: comptime_int
n: comptime_int
seed: []const u8
domain_sep: []const u8

std.crypto.ml_dsa.sha3

别名

第 21 行

别名目标 std.crypto.hash.sha3

std.crypto.ml_dsa.SignatureVerificationError

别名

第 25 行

别名目标 std.crypto.errors.SignatureVerificationError

std.crypto.ml_dsa.signMask

函数

第 3468 行

由有符号整数的符号位创建掩码。 x < 0 时返回全 1(0xFF...FF),x >= 0 时返回全 0。

fn signMask(comptime T: type, x: T) @Int(.unsigned, @typeInfo(T).int.bits)

参数

T: type
x: T

std.crypto.ml_dsa.std

别名

第 13 行

别名目标 std

std.crypto.ml_dsa.testing

别名

第 15 行

别名目标 std.testing

std.crypto.ml_dsa.testKeyGenerationBasic

函数

第 2821 行

fn testKeyGenerationBasic(comptime MlDsa: type, seed: [32]u8) !void

参数

MlDsa: type
seed: [32]u8

std.crypto.ml_dsa.testSignAndVerify

函数

第 2893 行

fn testSignAndVerify(comptime MlDsa: type, seed: [32]u8, message: []const u8) !void

参数

MlDsa: type
seed: [32]u8
message: []const u8

std.crypto.ml_dsa.toMont

函数

第 756 行

fn toMont(x: u32) u32

参数

x: u32

std.crypto.ml_dsa.useHint

函数

第 883 行

利用提示从扰动值重建高位。 给定:

  • rp:扰动值(r' = r - f)
  • hint:makeHint 产生的提示位 返回重建的高位 r1。

实现 FIPS 204 中的 useHint。

fn useHint(rp: u32, hint: u32, comptime gamma2: u32) u32

参数

rp: u32
hint: u32
gamma2: u32

std.crypto.ml_dsa.ZETA

常量

第 129 行

u32

std.crypto.ml_dsa.zetas

常量

第 714 行

源码

std/crypto/ml_dsa.zig

//! NIST FIPS 204 规定的基于模格的数字签名算法(ML-DSA)。
//!
//! ML-DSA 是具备后量子安全性的数字签名方案,其安全性基于
//! 模格上的带误差模学习(MLWE)和模短整数解(MSIS)
//! 问题的困难性。
//!
//! 提供三组参数:
//!
//! - ML-DSA-44:NIST 安全类别 2(128 位安全性)
//! - ML-DSA-65:NIST 安全类别 3(192 位安全性)
//! - ML-DSA-87:NIST 安全类别 5(256 位安全性)

const std = @import("std");
const builtin = @import("builtin");
const testing = std.testing;
const assert = std.debug.assert;
const crypto = std.crypto;
const errors = std.crypto.errors;
const math = std.math;
const mem = std.mem;
const sha3 = crypto.hash.sha3;

const ContextTooLongError = errors.ContextTooLongError;
const EncodingError = errors.EncodingError;
const SignatureVerificationError = errors.SignatureVerificationError;

/// NIST FIPS 204 规定的 ML-DSA-44,即基于模格的数字签名算法的 44 参数集。
///
/// 这是一种后量子签名方案,提供 NIST 安全类别 2,大致相当于 SHA-256 或 AES-128 的安全性。
///
/// 密钥大小:
///
/// - 公钥:1312 字节
/// - 私钥:2560 字节
/// - 签名:2420 字节
///
/// 使用示例:
///
/// ```zig
/// const kp = MLDSA44.KeyPair.generate();
/// const msg = "Hello, post-quantum world!";
/// const sig = try kp.sign(msg, null);
/// try sig.verify(msg, kp.public_key);
/// ```
///
///
pub const MLDSA44 = MLDSAImpl(.{
    .name = "ML-DSA-44",
    .k = 4,
    .l = 4,
    .eta = 2,
    .omega = 80,
    .tau = 39,
    .gamma1_bits = 17,
    .gamma2 = 95232, // (Q-1)/88
    .tr_size = 64,
    .ctilde_size = 32,
});

/// NIST FIPS 204 规定的 ML-DSA-65,
/// 即基于模格的数字签名算法的 65 参数集。
///
/// 这是一种后量子签名方案,提供 NIST 安全类别 3,
/// 大致相当于 SHA-384 或 AES-192 的安全性。
///
/// 密钥大小:
///
/// - 公钥:1952 字节
/// - 私钥:4032 字节
/// - 签名:3309 字节
///
/// 此参数集以更大的密钥和签名
/// 换取比 ML-DSA-44 更高的安全性。
pub const MLDSA65 = MLDSAImpl(.{
    .name = "ML-DSA-65",
    .k = 6,
    .l = 5,
    .eta = 4,
    .omega = 55,
    .tau = 49,
    .gamma1_bits = 19,
    .gamma2 = 261888, // (Q-1)/32
    .tr_size = 64,
    .ctilde_size = 48,
});

/// NIST FIPS 204 规定的 ML-DSA-87,即基于模格的数字签名算法的 87 参数集。
///
/// 这是一种后量子签名方案,提供 NIST 安全类别 5,大致相当于 SHA-512 或 AES-256 的安全性。
///
/// 密钥大小:
///
/// - 公钥:2592 字节
/// - 私钥:4896 字节
/// - 签名:4627 字节
///
/// 此参数集在三种 ML-DSA 变体中提供最高安全级别,适用于需要最高安全保证的应用。
///
///
///
pub const MLDSA87 = MLDSAImpl(.{
    .name = "ML-DSA-87",
    .k = 8,
    .l = 7,
    .eta = 2,
    .omega = 75,
    .tau = 60,
    .gamma1_bits = 19,
    .gamma2 = 261888, // (Q-1)/32
    .tr_size = 64,
    .ctilde_size = 64,
});

const N: usize = 256; // 多项式的次数
const Q: u32 = 8380417; // 模数:2^23 - 2^13 + 1
const Q_BITS: u32 = 23;
const D: u32 = 13; // power2Round 中丢弃的位

// 蒙哥马利常量 R = 2^32 mod q
const R: u64 = 1 << 32;

// Q^(-1) mod 2^32 = -(q^-1) mod 2^32
const Q_INV: u32 = 4236238847;

// (256)^(-1) * R^2 mod q,用于逆 NTT
const R_OVER_256: u32 = 41978;

// 本原 512 次单位根
const ZETA: u32 = 1753;

const Params = struct {
    name: []const u8,

    // 矩阵维度
    k: u8, // 矩阵 A 的高度
    l: u8, // 矩阵 A 的宽度

    // 采样参数
    eta: u8, // 秘密系数的边界

    // 提示参数
    omega: u16, // 提示位的最大数量

    // 挑战参数
    tau: u16, // 挑战多项式的权重

    // 舍入参数
    gamma1_bits: u8, // gamma1 的位数
    gamma2: u32, // 分解运算的参数

    // 大小
    tr_size: usize, // tr 哈希的大小
    ctilde_size: usize, // 挑战哈希的大小
};

const Poly = struct {
    cs: [N]u32,

    const zero: Poly = .{ .cs = @splat(0) };

    // 两个多项式相加(不进行归一化)
    fn add(a: Poly, b: Poly) Poly {
        var ret: Poly = undefined;
        for (0..N) |i| {
            ret.cs[i] = a.cs[i] + b.cs[i];
        }
        return ret;
    }

    // 两个多项式相减(假定 b 的系数 < 2q)
    fn sub(a: Poly, b: Poly) Poly {
        var ret: Poly = undefined;
        for (0..N) |i| {
            ret.cs[i] = a.cs[i] +% (@as(u32, 2 * Q) -% b.cs[i]);
        }
        return ret;
    }

    // 将每个系数约减至 < 2q
    fn reduceLe2Q(p: Poly) Poly {
        var ret = p;
        for (0..N) |i| {
            ret.cs[i] = le2Q(ret.cs[i]);
        }
        return ret;
    }

    // 将系数规范化至 [0, q)
    fn normalize(p: Poly) Poly {
        var ret = p;
        for (0..N) |i| {
            ret.cs[i] = modQ(ret.cs[i]);
        }
        return ret;
    }

    // 假定系数已 < 2q,执行规范化
    fn normalizeAssumingLe2Q(p: Poly) Poly {
        var ret = p;
        for (0..N) |i| {
            ret.cs[i] = le2qModQ(ret.cs[i]);
        }
        return ret;
    }

    // NTT 域中的逐点乘法(Montgomery 表示)
    fn mulHat(a: Poly, b: Poly) Poly {
        var ret: Poly = undefined;
        for (0..N) |i| {
            ret.cs[i] = montReduceLe2Q(@as(u64, a.cs[i]) * @as(u64, b.cs[i]));
        }
        return ret;
    }

    // 正向 NTT
    fn ntt(p: Poly) Poly {
        var ret = p;
        ret.nttInPlace();
        return ret;
    }

    // 原地正向 NTT
    fn nttInPlace(p: *Poly) void {
        var k: usize = 0;
        var l: usize = N / 2;

        while (l > 0) : (l >>= 1) {
            var offset: usize = 0;
            while (offset < N - l) : (offset += 2 * l) {
                k += 1;
                const zeta: u64 = zetas[k];

                for (offset..offset + l) |j| {
                    const t = montReduceLe2Q(zeta * @as(u64, p.cs[j + l]));
                    p.cs[j + l] = p.cs[j] +% (2 * Q -% t);
                    p.cs[j] +%= t;
                }
            }
        }
    }

    // 逆 NTT
    fn invNTT(p: Poly) Poly {
        var ret = p;
        ret.invNTTInPlace();
        return ret;
    }

    // 原地逆 NTT
    fn invNTTInPlace(p: *Poly) void {
        var k: usize = 0;
        var l: usize = 1;

        while (l < N) : (l <<= 1) {
            var offset: usize = 0;
            while (offset < N - l) : (offset += 2 * l) {
                const zeta: u64 = inv_zetas[k];
                k += 1;

                for (offset..offset + l) |j| {
                    const t = p.cs[j];
                    p.cs[j] = t +% p.cs[j + l];
                    p.cs[j + l] = montReduceLe2Q(zeta * @as(u64, t +% 256 * Q -% p.cs[j + l]));
                }
            }
        }

        for (0..N) |j| {
            p.cs[j] = montReduceLe2Q(@as(u64, R_OVER_256) * @as(u64, p.cs[j]));
        }
    }

    /// 对所有系数应用 Power2Round
    /// 返回 t0 和 t1 两个多项式
    fn power2RoundPoly(p: Poly) struct { t0: Poly, t1: Poly } {
        var t0 = Poly.zero;
        var t1 = Poly.zero;
        for (0..N) |i| {
            const result = power2Round(p.cs[i]);
            t0.cs[i] = result.a0_plus_q;
            t1.cs[i] = result.a1;
        }
        return .{ .t0 = t0, .t1 = t1 };
    }

    // 检查无穷范数是否超出边界
    fn exceeds(p: Poly, bound: u32) bool {
        var result: u32 = 0;
        for (0..N) |i| {
            const x = @as(i32, @intCast((Q - 1) / 2)) - @as(i32, @intCast(p.cs[i]));
            const abs_x = x ^ (x >> 31);
            const norm = @as(i32, @intCast((Q - 1) / 2)) - abs_x;
            const exceeds_bit = @intFromBool(@as(u32, @intCast(norm)) >= bound);
            result |= exceeds_bit;
        }
        return result != 0;
    }
};

fn PolyVec(comptime len: u8) type {
    return struct {
        ps: [len]Poly,

        const Self = @This();
        const zero: Self = .{ .ps = @splat(.zero) };

        /// 对向量中的每个多项式执行一元运算
        fn map(v: Self, comptime op: fn (Poly) Poly) Self {
            var ret: Self = undefined;
            inline for (0..len) |i| {
                ret.ps[i] = op(v.ps[i]);
            }
            return ret;
        }

        /// 对两个向量逐对应用二元运算。
        fn mapBinary(a: Self, b: Self, comptime op: fn (Poly, Poly) Poly) Self {
            var ret: Self = undefined;
            inline for (0..len) |i| {
                ret.ps[i] = op(a.ps[i], b.ps[i]);
            }
            return ret;
        }

        /// 对向量与标量多项式应用二元运算。
        fn mapBinaryPoly(v: Self, scalar: Poly, comptime op: fn (Poly, Poly) Poly) Self {
            var ret: Self = undefined;
            inline for (0..len) |i| {
                ret.ps[i] = op(v.ps[i], scalar);
            }
            return ret;
        }

        fn add(a: Self, b: Self) Self {
            return mapBinary(a, b, Poly.add);
        }

        fn sub(a: Self, b: Self) Self {
            return mapBinary(a, b, Poly.sub);
        }

        fn ntt(v: Self) Self {
            return map(v, Poly.ntt);
        }

        fn invNTT(v: Self) Self {
            return map(v, Poly.invNTT);
        }

        fn normalize(v: Self) Self {
            return map(v, Poly.normalize);
        }

        fn reduceLe2Q(v: Self) Self {
            return map(v, Poly.reduceLe2Q);
        }

        fn normalizeAssumingLe2Q(v: Self) Self {
            return map(v, Poly.normalizeAssumingLe2Q);
        }

        // 检查向量中是否有任何多项式超出界限。
        fn exceeds(v: Self, bound: u32) bool {
            var result = false;
            for (0..len) |i| {
                result = result or v.ps[i].exceeds(bound);
            }
            return result;
        }

        /// 对向量中的每个多项式应用 Power2Round
        /// 返回 t0 和 t1 两个向量
        fn power2Round(v: Self, t0_out: *Self) Self {
            var t1: Self = undefined;
            for (0..len) |i| {
                const result = v.ps[i].power2RoundPoly();
                t0_out.ps[i] = result.t0;
                t1.ps[i] = result.t1;
            }
            return t1;
        }

        /// 通用向量打包函数
        fn packWith(
            v: Self,
            buf: []u8,
            comptime poly_size: usize,
            comptime pack_fn: fn (Poly, []u8) void,
        ) void {
            inline for (0..len) |i| {
                const offset = i * poly_size;
                pack_fn(v.ps[i], buf[offset..][0..poly_size]);
            }
        }

        /// 向量的通用解包函数
        fn unpackWith(
            comptime poly_size: usize,
            comptime unpack_fn: fn ([]const u8) Poly,
            buf: []const u8,
        ) Self {
            var result: Self = undefined;
            inline for (0..len) |i| {
                const offset = i * poly_size;
                result.ps[i] = unpack_fn(buf[offset..][0..poly_size]);
            }
            return result;
        }

        /// 将 T1 向量打包为字节
        fn packT1(v: Self, buf: []u8) void {
            const poly_size = (N * (Q_BITS - D)) / 8;
            packWith(v, buf, poly_size, polyPackT1);
        }

        /// 从字节解包 T1 向量
        fn unpackT1(bytes: []const u8) Self {
            const poly_size = (N * (Q_BITS - D)) / 8;
            return unpackWith(poly_size, polyUnpackT1, bytes);
        }

        /// 将 T0 向量打包为字节
        fn packT0(v: Self, buf: []u8) void {
            const poly_size = (N * D) / 8;
            packWith(v, buf, poly_size, polyPackT0);
        }

        /// 从字节解包 T0 向量
        fn unpackT0(buf: []const u8) Self {
            const poly_size = (N * D) / 8;
            return unpackWith(poly_size, polyUnpackT0, buf);
        }

        /// 打包系数位于 [-eta, eta] 内的向量
        fn packLeqEta(v: Self, comptime eta: u8, buf: []u8) void {
            const poly_size = if (eta == 2) 96 else 128;
            const pack_fn = struct {
                fn pack(p: Poly, b: []u8) void {
                    polyPackLeqEta(p, eta, b);
                }
            }.pack;
            packWith(v, buf, poly_size, pack_fn);
        }

        /// 解包系数位于 [-eta, eta] 的向量。
        fn unpackLeqEta(comptime eta: u8, buf: []const u8) Self {
            const poly_size = if (eta == 2) 96 else 128;
            const unpack_fn = struct {
                fn unpack(b: []const u8) Poly {
                    return polyUnpackLeqEta(eta, b);
                }
            }.unpack;
            return unpackWith(poly_size, unpack_fn, buf);
        }

        /// 打包系数 < gamma1 的多项式向量
        fn packLeGamma1(v: Self, comptime gamma1_bits: u8, buf: []u8) void {
            const poly_size = ((gamma1_bits + 1) * N) / 8;
            const pack_fn = struct {
                fn pack(p: Poly, b: []u8) void {
                    polyPackLeGamma1(p, gamma1_bits, b);
                }
            }.pack;
            packWith(v, buf, poly_size, pack_fn);
        }

        /// 解包系数 < gamma1 的多项式向量
        fn unpackLeGamma1(comptime gamma1_bits: u8, buf: []const u8) Self {
            const poly_size = ((gamma1_bits + 1) * N) / 8;
            const unpack_fn = struct {
                fn unpack(b: []const u8) Poly {
                    return polyUnpackLeGamma1(gamma1_bits, b);
                }
            }.unpack;
            return unpackWith(poly_size, unpack_fn, buf);
        }

        /// 为签名验证打包高位 w1
        fn packW1(v: Self, comptime gamma1_bits: u8, buf: []u8) void {
            const poly_size = (N * (Q_BITS - gamma1_bits)) / 8;
            const pack_fn = struct {
                fn pack(p: Poly, b: []u8) void {
                    polyPackW1(p, gamma1_bits, b);
                }
            }.pack;
            packWith(v, buf, poly_size, pack_fn);
        }

        /// 将向量中的每个多项式分解为高位和低位
        fn decomposeVec(v: Self, comptime gamma2: u32, w0_out: *Self) Self {
            var w1: Self = undefined;
            for (0..len) |i| {
                for (0..N) |j| {
                    const r = decompose(v.ps[i].cs[j], gamma2);
                    w0_out.ps[i].cs[j] = r.a0_plus_q;
                    w1.ps[i].cs[j] = r.a1;
                }
            }
            return w1;
        }

        /// 为向量创建提示,返回提示中置位的数量。
        fn makeHintVec(w0mcs2pct0: Self, w1: Self, comptime gamma2: u32) struct { hint: Self, pop: u32 } {
            var hint: Self = undefined;
            var pop: u32 = 0;
            for (0..len) |i| {
                const result = polyMakeHint(w0mcs2pct0.ps[i], w1.ps[i], gamma2);
                hint.ps[i] = result.hint;
                pop += result.count;
            }
            return .{ .hint = hint, .pop = pop };
        }

        /// 应用提示以恢复高位
        fn useHint(v: Self, hint: Self, comptime gamma2: u32) Self {
            var result: Self = undefined;
            for (0..len) |i| {
                result.ps[i] = polyUseHint(v.ps[i], hint.ps[i], gamma2);
            }
            return result;
        }

        /// 将向量乘以 2^D(左移)
        fn mulBy2toD(v: Self) Self {
            var result: Self = undefined;
            for (0..len) |i| {
                for (0..N) |j| {
                    result.ps[i].cs[j] = v.ps[i].cs[j] << D;
                }
            }
            return result;
        }

        /// 采样系数均匀分布于 (-gamma1, gamma1] 的向量
        /// 封装 expandMask(FIPS 204:ExpandMask)
        fn deriveUniformLeGamma1(comptime gamma1_bits: u8, seed: *const [64]u8, nonce: u16) Self {
            var result: Self = undefined;
            for (0..len) |i| {
                result.ps[i] = expandMask(gamma1_bits, seed, nonce + @as(u16, @intCast(i)));
            }
            return result;
        }

        /// 将提示打包为字节
        /// 格式:对于每个多项式,找出 hint[i]=1 的位置,并编码这些位置
        fn packHint(v: Self, comptime omega: u16, buf: []u8) bool {
            var idx: usize = 0;
            var count: u32 = 0;

            for (0..len) |i| {
                for (0..N) |j| {
                    if (v.ps[i].cs[j] != 0) {
                        count += 1;
                    }
                }
            }

            if (count > omega) {
                return false;
            }

            // FIPS 204 规定的提示编码格式:
            // 前 omega 个字节:所有多项式中置位位的位置。
            // 后 len 个字节:指示各多项式提示结束位置的边界索引。
            for (0..len) |i| {
                for (0..N) |j| {
                    if (v.ps[i].cs[j] != 0) {
                        buf[idx] = @intCast(j);
                        idx += 1;
                    }
                }
                buf[omega + i] = @intCast(idx);
            }

            while (idx < omega) : (idx += 1) {
                buf[idx] = 0;
            }

            return true;
        }

        /// 从字节解包提示
        fn unpackHint(comptime omega: u16, buf: []const u8) ?Self {
            var result: Self = .{ .ps = @splat(.zero) };
            var prev_sop: u8 = 0; // 前一个切换点

            for (0..len) |i| {
                const sop = buf[omega + i]; // 切换点
                if (sop < prev_sop or sop > omega) {
                    return null; // 确保各切换点递增
                }

                var j = prev_sop;
                while (j < sop) : (j += 1) {
                    // 验证:每个多项式内的索引必须严格递增。
                    if (j > prev_sop and buf[j] <= buf[j - 1]) {
                        return null;
                    }
                    const pos = buf[j];
                    if (pos >= N) {
                        return null;
                    }
                    result.ps[i].cs[pos] = 1;
                }
                prev_sop = sop;
            }

            var j = prev_sop;
            while (j < omega) : (j += 1) {
                if (buf[j] != 0) {
                    return null;
                }
            }

            return result;
        }
    };
}

// k x l 个多项式组成的矩阵

fn Mat(comptime k: u8, comptime l: u8) type {
    return struct {
        rows: [k]PolyVec(l),

        const Self = @This();
        const VecL = PolyVec(l);
        const VecK = PolyVec(k);

        /// 使用 SHAKE-128 从种子 rho 展开矩阵 A。
        /// 这是 FIPS 204 中的 ExpandA 函数。
        fn derive(rho: *const [32]u8) Self {
            var m: Self = undefined;
            for (0..k) |i| {
                if (i + 1 < k) {
                    @prefetch(&m.rows[i + 1], .{ .rw = .write, .locality = 2 });
                }
                for (0..l) |j| {
                    // Nonce 为 i*256 + j
                    const nonce: u16 = (@as(u16, @intCast(i)) << 8) | @as(u16, @intCast(j));
                    m.rows[i].ps[j] = polyDeriveUniform(rho, nonce);
                }
            }
            return m;
        }

        /// 在 NTT 域中将矩阵与向量相乘,并以普通域返回结果。
        /// 接受 NTT 形式的向量,返回普通形式的乘积。
        fn mulVec(self: Self, v_hat: VecL) VecK {
            var result = VecK.zero;
            for (0..k) |i| {
                result.ps[i] = dotHat(l, self.rows[i], v_hat);
                result.ps[i] = result.ps[i].reduceLe2Q();
                result.ps[i] = result.ps[i].invNTT();
            }
            return result;
        }

        /// 在 NTT 域中计算矩阵与向量的乘积,并返回 NTT 域中的结果。
        /// 接受 NTT 形式的向量,返回 NTT 形式的乘积。
        fn mulVecHat(self: Self, v_hat: VecL) VecK {
            var result: VecK = undefined;
            for (0..k) |i| {
                result.ps[i] = dotHat(l, self.rows[i], v_hat);
            }
            return result;
        }
    };
}

// NTT 域中的点积
fn dotHat(comptime len: u8, a: PolyVec(len), b: PolyVec(len)) Poly {
    var ret = Poly.zero;
    for (0..len) |i| {
        const prod = a.ps[i].mulHat(b.ps[i]);
        ret = ret.add(prod);
    }
    return ret;
}

// 模算术运算

// 利用 2^23 = 2^13 - 1 (mod q),将 x 约减到 [0, 2q)。
fn le2Q(x: u32) u32 {
    // 写为 x = x1 * 2^23 + x2,其中 x2 < 2^23 且 x1 < 2^9
    // 于是 x = x2 + x1 * 2^13 - x1 (mod q)
    // 且 x2 + x1 * 2^13 - x1 <= 2^23 + 2^13 < 2q
    const x1 = x >> 23;
    const x2 = x & 0x7FFFFF; // 2^23 - 1
    return x2 +% (x1 << 13) -% x1;
}

// 将 x 约减至 [0, q)
fn modQ(x: u32) u32 {
    return le2qModQ(le2Q(x));
}

// 已知 x < 2q,将其约减至 [0, q)
fn le2qModQ(x: u32) u32 {
    const r = x -% Q;
    const mask = signMask(u32, r);
    return r +% (mask & Q);
}

// 蒙哥马利约简:对于 x < q*2^32,返回 y < 2q,且 y ≡ x*R^(-1) (mod q),
// 其中 R = 2^32。用于 NTT 运算中的高效模乘。
fn montReduceLe2Q(x: u64) u32 {
    const m = (x *% Q_INV) & 0xffffffff;
    return @truncate((x +% m * @as(u64, Q)) >> 32);
}

// 用于 NTT 的预计算 zeta(Montgomery 形式)
// zetas[i] = zeta^brv(i) * R mod q
const zetas = computeZetas();

fn computeZetas() [N]u32 {
    @setEvalBranchQuota(100000);
    var ret: [N]u32 = undefined;

    for (0..N) |i| {
        const brv_i = @bitReverse(@as(u8, @intCast(i)));
        const power = modularPow(u32, ZETA, brv_i, Q);
        ret[i] = toMont(power);
    }

    return ret;
}

// 逆 NTT 使用的预计算逆 zeta 值
const inv_zetas = computeInvZetas();

fn computeInvZetas() [N]u32 {
    @setEvalBranchQuota(100000);
    var ret: [N]u32 = undefined;

    const inv_zeta = modularInverse(u32, ZETA, Q);

    for (0..N) |i| {
        const idx = 255 - i;
        const brv_idx = @bitReverse(@as(u8, @intCast(idx)));

        // 指数为 -(brv_idx - 256) = 256 - brv_idx
        const exp: u32 = @as(u32, 256) - brv_idx;

        // 计算 inv_zeta^exp
        const power = modularPow(u32, inv_zeta, exp, Q);

        // 转换为蒙哥马利形式
        ret[i] = toMont(power);
    }

    return ret;
}

// 转换为蒙哥马利形式:x -> x * R mod q
fn toMont(x: u32) u32 {
    // R = 2^32,R mod q 可计算为:
    // 2^32 mod q = 2^32 mod (2^23 - 2^13 + 1)
    // 利用恒等式 2^23 = 2^13 - 1 (mod q),可以约减 2^32。
    // 不过,更简单的是直接计算:return montReduce(x * R^2 mod q)
    // 其中 R^2 mod q 预先计算。

    // 计算 R^2 mod q:
    // R = 2^32,因此 R^2 = 2^64
    // 可先考察 R mod q 来计算:
    // 2^32 = 2^32 mod q
    // 但采用更简单的方法:在蒙哥马利域中将 x 乘以 R。
    // 实际上,最简单的是:x * R mod q = montReduceLe2Q(x * R^2 mod q)

    // 在编译时预计算 R^2 mod q
    const r_mod_q = comptime blk: {
        // 2^32 mod q - 通过连续平方计算
        var r: u64 = 1;
        for (0..32) |_| {
            r = (r * 2) % Q;
        }
        break :blk @as(u32, @intCast(r));
    };

    const r2_mod_q = comptime blk: {
        const r = @as(u64, r_mod_q);
        break :blk @as(u32, @intCast((r * r) % Q));
    };

    return montReduceLe2Q(@as(u64, x) * @as(u64, r2_mod_q));
}

/// 将 0 ≤ a < Q 拆为 a0 和 a1,满足 a = a1*2^D + a0
/// 及 -2^(D-1) < a0 ≤ 2^(D-1)。返回 a0 + Q 和 a1。
/// FIPS 204:Power2Round(算法 19)
fn power2Round(a: u32) struct { a0_plus_q: u32, a1: u32 } {
    // 实际计算 a0 = a mod± 2^D
    // 以及 a1 = (a - a0) / 2^D。
    var a0 = a & ((1 << D) - 1); // a mod 2^D

    // a0 是 0, 1, ..., 2^(D-1)-1, 2^(D-1), 2^(D-1)+1, ..., 2^D-1 中的一个
    a0 -%= (1 << (D - 1)) + 1;
    // 现在 a0 为 -2^(D-1)-1, -2^(D-1), ..., -2, -1, 0, ..., 2^(D-1)-2。

    // 接着,对所有为负数(视为 i32)的 a0 加上 2^D
    a0 +%= @as(u32, @bitCast(@as(i32, @bitCast(a0)) >> 31)) & (1 << D);
    // 现在 a0 依次为 2^(D-1)-1, 2^(D-1), ..., 2^D-2, 2^D-1, 0, ..., 2^(D-1)-2

    a0 -%= (1 << (D - 1)) - 1;
    // 此时 a0 为 0, 1, 2, ..., 2^(D-1)-1, 2^(D-1), -2^(D-1)+1, ..., -1

    const a0_plus_q = Q +% a0;
    const a1 = (a -% a0) >> D;

    return .{ .a0_plus_q = a0_plus_q, .a1 = a1 };
}

/// 将 0 ≤ a < q 拆为 a0 和 a1,使 a = a1*alpha + a0,且 -alpha/2 < a0 ≤ alpha/2;
/// 例外是本应有 a1 = (q-1)/alpha 时,改取 a1=0,
/// 且 -alpha/2 ≤ a0 < 0。返回 a0 + q。注意 0 ≤ a1 < (q-1)/alpha。
/// 回顾:alpha = 2*gamma2。
fn decompose(a: u32, comptime gamma2: u32) struct { a0_plus_q: u32, a1: u32 } {
    const alpha = 2 * gamma2;

    // a1 = ⌈a / 128⌉
    var a1 = (a + 127) >> 7;

    if (alpha == 523776) {
        // 对于 ML-DSA-87:gamma2 = 261888, alpha = 523776
        // 1025/2^22 与 1/4092 足够接近,使 a1 成为 a/alpha 向下取整的结果
        a1 = ((a1 * 1025 + (1 << 21)) >> 22);

        // 对于 a1 = (q-1)/alpha = 16 的边界情况,必须设置 a1=0
        a1 &= 15;
    } else if (alpha == 190464) {
        // 对于 ML-DSA-65:gamma2 = 95232, alpha = 190464
        // 11275/2^24 足够接近 1/1488,因此 a1 等于 a/alpha 向下舍入
        a1 = ((a1 * 11275) + (1 << 23)) >> 24;

        // 对于边界情况 a1 = (q-1)/alpha = 44,必须令 a1=0
        a1 ^= @as(u32, @bitCast(@as(i32, @bitCast(43 -% a1)) >> 31)) & a1;
    } else {
        @compileError("unsupported gamma2/alpha value");
    }

    var a0_plus_q = a -% a1 * alpha;

    // 在边界情况中,若设 a1=0,则会错误地得到
    // a0 > (q-1)/2,因而需要减去 q。由于返回
    // a0 + q,这等价于在 a0 < (q-1)/2 时加上 q。
    a0_plus_q +%= @as(u32, @bitCast(@as(i32, @bitCast(a0_plus_q -% (Q - 1) / 2)) >> 31)) & Q;

    return .{ .a0_plus_q = a0_plus_q, .a1 = a1 };
}

/// 创建提示位,帮助在小幅扰动后恢复高位。
/// 给定:
/// - z0:修改后的低位 r0 - f mod Q,其中 f 很小。
/// - r1:原高位。
/// 需要提示时返回 1,否则返回 0。
///
/// 实现 FIPS 204 中的 makeHint。提示使得无需明确知道 f,也能从 r' = r - f 恢复 r1。
///
fn makeHint(z0: u32, r1: u32, comptime gamma2: u32) u32 {
    // 若 -alpha/2 < r0 - f <= alpha/2,则 r1*alpha + r0 - f 满足 decompose() 的限制,是 r' 的有效分解,因此 r'1 = r1,提示值应为 0。前两个不等式涵盖了此情况。
    // 还有一种情况:若 r0 - f = -alpha/2,且 r1 = 0,则 r1*alpha + r0 - f 也是有效分解。
    // 其他情况下会进位 1,提示值应为 1。
    //
    //
    //

    const cond1 = @intFromBool(z0 <= gamma2);
    const cond2 = @intFromBool(z0 > Q - gamma2);
    const eq_gamma2 = @intFromBool(z0 == Q - gamma2);
    const r1_is_zero = @intFromBool(r1 == 0);
    const cond3 = eq_gamma2 & r1_is_zero;

    return 1 - (cond1 | cond2 | cond3);
}

/// 利用提示从扰动值重建高位。
/// 给定:
/// - rp:扰动值(r' = r - f)
/// - hint:makeHint 产生的提示位
/// 返回重建的高位 r1。
///
/// 实现 FIPS 204 中的 useHint。
fn useHint(rp: u32, hint: u32, comptime gamma2: u32) u32 {
    const decomp = decompose(rp, gamma2);
    const rp0_plus_q = decomp.a0_plus_q;
    var rp1 = decomp.a1;

    if (hint == 0) {
        return rp1;
    }

    // 根据 gamma2,采用不同的调整方式
    if (gamma2 == 261888) {
        // ML-DSA-65 和 ML-DSA-87:r1 的最大值为 15
        if (rp0_plus_q > Q) {
            rp1 = (rp1 + 1) & 15;
        } else {
            rp1 = (rp1 -% 1) & 15;
        }
    } else if (gamma2 == 95232) {
        // ML-DSA-44:r1 最大为 43
        if (rp0_plus_q > Q) {
            if (rp1 == 43) {
                rp1 = 0;
            } else {
                rp1 += 1;
            }
        } else {
            if (rp1 == 0) {
                rp1 = 43;
            } else {
                rp1 -= 1;
            }
        }
    } else {
        @compileError("unsupported gamma2 value");
    }

    return rp1;
}

/// 为扰动后高位与原始高位的差异创建提示多项式。
/// 返回设置为 1 的提示位数量,即置位计数。
///
/// 在生成签名时使用,以创建帮助验证方在不访问秘密的情况下恢复高位的提示。
///
fn polyMakeHint(p0: Poly, p1: Poly, comptime gamma2: u32) struct { hint: Poly, count: u32 } {
    var hint = Poly.zero;
    var count: u32 = 0;

    for (0..N) |i| {
        const h = makeHint(p0.cs[i], p1.cs[i], gamma2);
        hint.cs[i] = h;
        count += h;
    }

    return .{ .hint = hint, .count = count };
}

/// 应用提示,从扰动后的多项式重建高位。
///
/// 在签名验证期间,使用签名中提供的提示
/// 恢复高位。
fn polyUseHint(q: Poly, hint: Poly, comptime gamma2: u32) Poly {
    var result = Poly.zero;

    for (0..N) |i| {
        result.cs[i] = useHint(q.cs[i], hint.cs[i], gamma2);
    }

    return result;
}

/// 将系数位于 [Q-eta, Q+eta] 的多项式打包为字节。
/// eta=2 时:每个系数打包为 3 位(共 96 字节)。
/// eta=4 时:每个系数打包为 4 位(共 128 字节)。
/// 假定系数未归一化,但位于 [q-η, q+η]。
fn polyPackLeqEta(p: Poly, comptime eta: u8, buf: []u8) void {
    comptime {
        if (eta != 2 and eta != 4) {
            @compileError("eta must be 2 or 4");
        }
    }

    if (eta == 2) {
        // 每个系数 3 位:将 8 个系数打包为 3 字节。
        var j: usize = 0;
        var i: usize = 0;
        while (i < buf.len) : (i += 3) {
            const c0 = Q + eta - p.cs[j];
            const c1 = Q + eta - p.cs[j + 1];
            const c2 = Q + eta - p.cs[j + 2];
            const c3 = Q + eta - p.cs[j + 3];
            const c4 = Q + eta - p.cs[j + 4];
            const c5 = Q + eta - p.cs[j + 5];
            const c6 = Q + eta - p.cs[j + 6];
            const c7 = Q + eta - p.cs[j + 7];

            buf[i] = @truncate(c0 | (c1 << 3) | (c2 << 6));
            buf[i + 1] = @truncate((c2 >> 2) | (c3 << 1) | (c4 << 4) | (c5 << 7));
            buf[i + 2] = @truncate((c5 >> 1) | (c6 << 2) | (c7 << 5));

            j += 8;
        }
    } else { // eta == 4
        // 每个系数占 4 位:将两个系数打包到一个字节中
        var j: usize = 0;
        for (0..buf.len) |i| {
            const c0 = Q + eta - p.cs[j];
            const c1 = Q + eta - p.cs[j + 1];
            buf[i] = @truncate(c0 | (c1 << 4));
            j += 2;
        }
    }
}

/// 从字节解包系数位于 [Q-eta, Q+eta] 的多项式。
/// 输出系数不会归一化,而是位于 [q-η, q+η]。
fn polyUnpackLeqEta(comptime eta: u8, buf: []const u8) Poly {
    comptime {
        if (eta != 2 and eta != 4) {
            @compileError("eta must be 2 or 4");
        }
    }

    var p = Poly.zero;

    if (eta == 2) {
        // 每个系数 3 位:从 3 字节解包 8 个系数。
        var j: usize = 0;
        var i: usize = 0;
        while (i < buf.len) : (i += 3) {
            p.cs[j] = Q + eta - (buf[i] & 7);
            p.cs[j + 1] = Q + eta - ((buf[i] >> 3) & 7);
            p.cs[j + 2] = Q + eta - ((buf[i] >> 6) | ((buf[i + 1] << 2) & 7));
            p.cs[j + 3] = Q + eta - ((buf[i + 1] >> 1) & 7);
            p.cs[j + 4] = Q + eta - ((buf[i + 1] >> 4) & 7);
            p.cs[j + 5] = Q + eta - ((buf[i + 1] >> 7) | ((buf[i + 2] << 1) & 7));
            p.cs[j + 6] = Q + eta - ((buf[i + 2] >> 2) & 7);
            p.cs[j + 7] = Q + eta - ((buf[i + 2] >> 5) & 7);
            j += 8;
        }
    } else { // eta == 4
        // 每个系数 4 位:从 1 字节解包 2 个系数。
        var j: usize = 0;
        for (0..buf.len) |i| {
            p.cs[j] = Q + eta - (buf[i] & 15);
            p.cs[j + 1] = Q + eta - (buf[i] >> 4);
            j += 2;
        }
    }

    return p;
}

/// 将系数 < 1024(T1)的多项式打包为字节。
/// 每个系数占 10 位:4 个系数打包为 5 字节。
/// 假定系数已归一化。
fn polyPackT1(p: Poly, buf: []u8) void {
    var j: usize = 0;
    var i: usize = 0;
    while (i < buf.len) : (i += 5) {
        buf[i] = @truncate(p.cs[j]);
        buf[i + 1] = @truncate((p.cs[j] >> 8) | (p.cs[j + 1] << 2));
        buf[i + 2] = @truncate((p.cs[j + 1] >> 6) | (p.cs[j + 2] << 4));
        buf[i + 3] = @truncate((p.cs[j + 2] >> 4) | (p.cs[j + 3] << 6));
        buf[i + 4] = @truncate(p.cs[j + 3] >> 2);
        j += 4;
    }
}

/// 从字节中解包系数 < 1024 的多项式(T1)。
/// 输出系数将归一化。
fn polyUnpackT1(buf: []const u8) Poly {
    var p = Poly.zero;
    var j: usize = 0;
    var i: usize = 0;
    while (i < buf.len) : (i += 5) {
        p.cs[j] = (@as(u32, buf[i]) | (@as(u32, buf[i + 1]) << 8)) & 0x3ff;
        p.cs[j + 1] = ((@as(u32, buf[i + 1]) >> 2) | (@as(u32, buf[i + 2]) << 6)) & 0x3ff;
        p.cs[j + 2] = ((@as(u32, buf[i + 2]) >> 4) | (@as(u32, buf[i + 3]) << 4)) & 0x3ff;
        p.cs[j + 3] = ((@as(u32, buf[i + 3]) >> 6) | (@as(u32, buf[i + 4]) << 2)) & 0x3ff;
        j += 4;
    }
    return p;
}

/// 将系数位于 (-2^(D-1), 2^(D-1)](T0)的多项式打包为字节。
/// 每个系数打包 13 位:8 个系数打包为 13 字节。
/// 假定系数未规范化,而是位于 (q-2^(D-1), q+2^(D-1)]。
fn polyPackT0(p: Poly, buf: []u8) void {
    const bound = 1 << (D - 1);
    var j: usize = 0;
    var i: usize = 0;
    while (i < buf.len) : (i += 13) {
        const p0 = Q + bound - p.cs[j];
        const p1 = Q + bound - p.cs[j + 1];
        const p2 = Q + bound - p.cs[j + 2];
        const p3 = Q + bound - p.cs[j + 3];
        const p4 = Q + bound - p.cs[j + 4];
        const p5 = Q + bound - p.cs[j + 5];
        const p6 = Q + bound - p.cs[j + 6];
        const p7 = Q + bound - p.cs[j + 7];

        buf[i] = @truncate(p0 >> 0);
        buf[i + 1] = @truncate((p0 >> 8) | (p1 << 5));
        buf[i + 2] = @truncate(p1 >> 3);
        buf[i + 3] = @truncate((p1 >> 11) | (p2 << 2));
        buf[i + 4] = @truncate((p2 >> 6) | (p3 << 7));
        buf[i + 5] = @truncate(p3 >> 1);
        buf[i + 6] = @truncate((p3 >> 9) | (p4 << 4));
        buf[i + 7] = @truncate(p4 >> 4);
        buf[i + 8] = @truncate((p4 >> 12) | (p5 << 1));
        buf[i + 9] = @truncate((p5 >> 7) | (p6 << 6));
        buf[i + 10] = @truncate(p6 >> 2);
        buf[i + 11] = @truncate((p6 >> 10) | (p7 << 3));
        buf[i + 12] = @truncate(p7 >> 5);

        j += 8;
    }
}

/// 从字节解包系数位于 (-2^(D-1), 2^(D-1)](T0)的多项式。
/// 输出系数不会归一化,而是位于 (-2^(D-1), 2^(D-1)]。
fn polyUnpackT0(buf: []const u8) Poly {
    const bound = 1 << (D - 1);
    var p = Poly.zero;
    var j: usize = 0;
    var i: usize = 0;
    while (i < buf.len) : (i += 13) {
        p.cs[j] = Q + bound - ((@as(u32, buf[i]) | (@as(u32, buf[i + 1]) << 8)) & 0x1fff);
        p.cs[j + 1] = Q + bound - (((@as(u32, buf[i + 1]) >> 5) | (@as(u32, buf[i + 2]) << 3) | (@as(u32, buf[i + 3]) << 11)) & 0x1fff);
        p.cs[j + 2] = Q + bound - (((@as(u32, buf[i + 3]) >> 2) | (@as(u32, buf[i + 4]) << 6)) & 0x1fff);
        p.cs[j + 3] = Q + bound - (((@as(u32, buf[i + 4]) >> 7) | (@as(u32, buf[i + 5]) << 1) | (@as(u32, buf[i + 6]) << 9)) & 0x1fff);
        p.cs[j + 4] = Q + bound - (((@as(u32, buf[i + 6]) >> 4) | (@as(u32, buf[i + 7]) << 4) | (@as(u32, buf[i + 8]) << 12)) & 0x1fff);
        p.cs[j + 5] = Q + bound - (((@as(u32, buf[i + 8]) >> 1) | (@as(u32, buf[i + 9]) << 7)) & 0x1fff);
        p.cs[j + 6] = Q + bound - (((@as(u32, buf[i + 9]) >> 6) | (@as(u32, buf[i + 10]) << 2) | (@as(u32, buf[i + 11]) << 10)) & 0x1fff);
        p.cs[j + 7] = Q + bound - ((@as(u32, buf[i + 11]) >> 3) | (@as(u32, buf[i + 12]) << 5));
        j += 8;
    }
    return p;
}

/// 将系数从中心化表示转换为非负表示。
/// 将值从 [0,γ₁] ∪ (Q-γ₁, Q) 变换到 [0, 2γ₁)。
fn centeredToPositive(val: u32, comptime gamma1: u32) u32 {
    var result = gamma1 -% val;
    result +%= (signMask(u32, result) & Q);
    return result;
}

/// 将系数位于 (-gamma1, gamma1] 的多项式打包为字节。
/// gamma1_bits=17 时:每个系数打包为 18 位,4 个系数占 9 字节。
/// gamma1_bits=19 时:每个系数打包为 20 位,2 个系数占 5 字节。
/// 假定系数已归一化。
fn polyPackLeGamma1(p: Poly, comptime gamma1_bits: u8, buf: []u8) void {
    const gamma1: u32 = @as(u32, 1) << gamma1_bits;

    if (gamma1_bits == 17) {
        // 将 4 个系数打包到 9 字节中(每个占 18 位)
        var j: usize = 0;
        var i: usize = 0;
        while (i < buf.len) : (i += 9) {
            // 从 [0,γ₁] ∪ (Q-γ₁, Q) 转换至 [0, 2γ₁)
            const p0 = centeredToPositive(p.cs[j], gamma1);
            const p1 = centeredToPositive(p.cs[j + 1], gamma1);
            const p2 = centeredToPositive(p.cs[j + 2], gamma1);
            const p3 = centeredToPositive(p.cs[j + 3], gamma1);

            buf[i] = @truncate(p0);
            buf[i + 1] = @truncate(p0 >> 8);
            buf[i + 2] = @truncate((p0 >> 16) | (p1 << 2));
            buf[i + 3] = @truncate(p1 >> 6);
            buf[i + 4] = @truncate((p1 >> 14) | (p2 << 4));
            buf[i + 5] = @truncate(p2 >> 4);
            buf[i + 6] = @truncate((p2 >> 12) | (p3 << 6));
            buf[i + 7] = @truncate(p3 >> 2);
            buf[i + 8] = @truncate(p3 >> 10);

            j += 4;
        }
    } else if (gamma1_bits == 19) {
        // 将 2 个系数打包为 5 字节(各 20 位)。
        var j: usize = 0;
        var i: usize = 0;
        while (i < buf.len) : (i += 5) {
            const p0 = centeredToPositive(p.cs[j], gamma1);
            const p1 = centeredToPositive(p.cs[j + 1], gamma1);

            buf[i] = @truncate(p0);
            buf[i + 1] = @truncate(p0 >> 8);
            buf[i + 2] = @truncate((p0 >> 16) | (p1 << 4));
            buf[i + 3] = @truncate(p1 >> 4);
            buf[i + 4] = @truncate(p1 >> 12);

            j += 2;
        }
    } else {
        @compileError("gamma1_bits must be 17 or 19");
    }
}

/// 从字节解包系数位于 (-gamma1, gamma1] 的多项式。
/// 输出系数将被规范化。
fn polyUnpackLeGamma1(comptime gamma1_bits: u8, buf: []const u8) Poly {
    const gamma1: u32 = @as(u32, 1) << gamma1_bits;
    var p = Poly.zero;

    if (gamma1_bits == 17) {
        // 从 9 字节解包 4 个系数(各 18 位)。
        var j: usize = 0;
        var i: usize = 0;
        while (i < buf.len) : (i += 9) {
            var p0 = @as(u32, buf[i]) | (@as(u32, buf[i + 1]) << 8) | ((@as(u32, buf[i + 2]) & 0x3) << 16);
            var p1 = (@as(u32, buf[i + 2]) >> 2) | (@as(u32, buf[i + 3]) << 6) | ((@as(u32, buf[i + 4]) & 0xf) << 14);
            var p2 = (@as(u32, buf[i + 4]) >> 4) | (@as(u32, buf[i + 5]) << 4) | ((@as(u32, buf[i + 6]) & 0x3f) << 12);
            var p3 = (@as(u32, buf[i + 6]) >> 6) | (@as(u32, buf[i + 7]) << 2) | (@as(u32, buf[i + 8]) << 10);

            // 从 [0, 2γ₁) 转换至 (-γ₁, γ₁]
            p0 = centeredToPositive(p0, gamma1);
            p1 = centeredToPositive(p1, gamma1);
            p2 = centeredToPositive(p2, gamma1);
            p3 = centeredToPositive(p3, gamma1);

            p.cs[j] = p0;
            p.cs[j + 1] = p1;
            p.cs[j + 2] = p2;
            p.cs[j + 3] = p3;

            j += 4;
        }
    } else if (gamma1_bits == 19) {
        // 从 5 字节解包 2 个系数(各 20 位)
        var j: usize = 0;
        var i: usize = 0;
        while (i < buf.len) : (i += 5) {
            var p0 = @as(u32, buf[i]) | (@as(u32, buf[i + 1]) << 8) | ((@as(u32, buf[i + 2]) & 0xf) << 16);
            var p1 = (@as(u32, buf[i + 2]) >> 4) | (@as(u32, buf[i + 3]) << 4) | (@as(u32, buf[i + 4]) << 12);

            p0 = centeredToPositive(p0, gamma1);
            p1 = centeredToPositive(p1, gamma1);

            p.cs[j] = p0;
            p.cs[j + 1] = p1;

            j += 2;
        }
    } else {
        @compileError("gamma1_bits must be 17 or 19");
    }

    return p;
}

/// 打包用于验证的 W1 多项式。
/// gamma1_bits=17 时:每个系数打包为 6 位(4 个系数共 3 字节)。
/// gamma1_bits=19 时:每个系数打包为 4 位(2 个系数共 1 字节)。
/// 假定系数已归一化。
fn polyPackW1(p: Poly, comptime gamma1_bits: u8, buf: []u8) void {
    if (gamma1_bits == 17) {
        // 将 4 个系数打包到 3 字节(各 6 位)
        var j: usize = 0;
        var i: usize = 0;
        while (i < buf.len) : (i += 3) {
            buf[i] = @truncate(p.cs[j] | (p.cs[j + 1] << 6));
            buf[i + 1] = @truncate((p.cs[j + 1] >> 2) | (p.cs[j + 2] << 4));
            buf[i + 2] = @truncate((p.cs[j + 2] >> 4) | (p.cs[j + 3] << 2));
            j += 4;
        }
    } else if (gamma1_bits == 19) {
        // 将 2 个系数打包到 1 字节(各 4 位)——等价于 packLe16
        var j: usize = 0;
        for (0..buf.len) |i| {
            buf[i] = @truncate(p.cs[j] | (p.cs[j + 1] << 4));
            j += 2;
        }
    } else {
        @compileError("gamma1_bits must be 17 or 19");
    }
}

fn polyDeriveUniform(seed: *const [32]u8, nonce: u16) Poly {
    var domain_sep: [2]u8 = undefined;
    domain_sep[0] = @truncate(nonce);
    domain_sep[1] = @truncate(nonce >> 8);

    return sampleUniformRejection(
        Poly,
        Q,
        23,
        N,
        seed,
        &domain_sep,
    );
}

/// 使用给定种子和 nonce,通过 SHAKE-256 均匀采样 p,
/// 使系数范数小于或等于 η。
/// 多项式不会归一化,系数位于 [q-η, q+η]。
/// FIPS 204:ExpandS,算法 27。
fn expandS(comptime eta: u8, seed: *const [64]u8, nonce: u16) Poly {
    comptime {
        if (eta != 2 and eta != 4) {
            @compileError("eta must be 2 or 4");
        }
    }

    var p = Poly.zero;
    var i: usize = 0;

    var buf: [sha3.Shake256.block_length]u8 = undefined; // SHAKE-256 的速率为 136 字节

    // 准备输入:seed || nonce(小端 u16)
    var input: [66]u8 = undefined;
    @memcpy(input[0..64], seed);
    input[64] = @truncate(nonce);
    input[65] = @truncate(nonce >> 8);

    var h = sha3.Shake256.init(.{});
    h.update(&input);

    while (i < N) {
        h.squeeze(&buf);

        // 处理缓冲区:每字节提取两个样本(4 位半字节)
        var j: usize = 0;
        while (j < buf.len and i < N) : (j += 1) {
            var t1 = @as(u32, buf[j]) & 15;
            var t2 = @as(u32, buf[j]) >> 4;

            if (eta == 2) {
                // 对于 eta=2:若 t > 14 则拒绝,然后对 5 取模
                if (t1 <= 14) {
                    t1 -%= ((205 * t1) >> 10) * 5; // 对 5 取模
                    p.cs[i] = Q + eta - t1;
                    i += 1;
                }
                if (t2 <= 14 and i < N) {
                    t2 -%= ((205 * t2) >> 10) * 5; // 对 5 取模
                    p.cs[i] = Q + eta - t2;
                    i += 1;
                }
            } else if (eta == 4) {
                // eta=4 时:若 t <= 2*eta = 8,则接受
                if (t1 <= 2 * eta) {
                    p.cs[i] = Q + eta - t1;
                    i += 1;
                }
                if (t2 <= 2 * eta and i < N) {
                    p.cs[i] = Q + eta - t2;
                    i += 1;
                }
            }
        }
    }

    return p;
}

/// 使用 SHAKE-256 均匀采样 p,使其具有 τ 个取自 {Q-1, 1} 的非零系数。
/// 由此创建一个恰含 tau 个非零 ±1 系数的“球”多项式。
/// 多项式将归一化为系数取自 {0, 1, Q-1} 的形式。
/// FIPS 204:SampleInBall(算法 18)
fn sampleInBall(comptime tau: u16, seed: []const u8) Poly {
    var p = Poly.zero;

    var buf: [sha3.Shake256.block_length]u8 = undefined; // SHAKE-256 的速率为 136 字节

    var h = sha3.Shake256.init(.{});
    h.update(seed);
    h.squeeze(&buf);

    // 从前 8 个字节提取符号
    var signs: u64 = 0;
    for (0..8) |j| {
        signs |= @as(u64, buf[j]) << @intCast(j * 8);
    }
    var buf_off: usize = 8;

    // 使用 Fisher-Yates 洗牌生成 tau 个非零系数。
    // 先放置 N-tau 个零,再加入 tau 个 ±1 值。
    var i: u16 = N - tau;
    while (i < N) : (i += 1) {
        var b: u16 = undefined;

        // 使用拒绝采样查找位置
        while (true) {
            if (buf_off >= buf.len) {
                h.squeeze(&buf);
                buf_off = 0;
            }

            b = buf[buf_off];
            buf_off += 1;

            if (b <= i) {
                break;
            }
        }

        // 洗牌:将现有值移到位置 i
        p.cs[i] = p.cs[b];

        // 根据符号位将位置 b 设为 ±1
        p.cs[b] = 1;
        const sign_bit: u1 = @truncate(signs);
        const mask = bitMask(u32, sign_bit);
        p.cs[b] ^= mask & (1 | (Q - 1));
        signs >>= 1;
    }

    return p;
}

/// 采样多项式,其系数在 (-gamma1, gamma1] 中均匀分布。
/// 用于签名期间采样掩码向量 y。
/// FIPS 204:ExpandMask(算法 28)。
fn expandMask(comptime gamma1_bits: u8, seed: *const [64]u8, nonce: u16) Poly {
    const packed_size = ((gamma1_bits + 1) * N) / 8;
    var buf: [packed_size]u8 = undefined;

    // 构造初始向量:seed || nonce(小端序)
    var iv: [66]u8 = undefined;
    @memcpy(iv[0..64], seed);
    iv[64] = @truncate(nonce & 0xFF);
    iv[65] = @truncate(nonce >> 8);

    var h = sha3.Shake256.init(.{});
    h.update(&iv);
    h.squeeze(&buf);

    // 解包多项式
    return polyUnpackLeGamma1(gamma1_bits, &buf);
}

fn MLDSAImpl(comptime p: Params) type {
    return struct {
        pub const params = p;
        pub const name = p.name;
        pub const gamma1: u32 = @as(u32, 1) << p.gamma1_bits;
        pub const beta: u32 = p.tau * p.eta;
        pub const alpha: u32 = 2 * p.gamma2;

        const Self = @This();
        const PolyVecL = PolyVec(p.l);
        const PolyVecK = PolyVec(p.k);
        const MatKxL = Mat(p.k, p.l);

        /// 用于确定性密钥生成的种子长度(32 字节)。
        pub const seed_length: usize = 32;

        /// 用于非确定性签名的可选随机字节长度(单位为字节)。
        pub const noise_length = 32;

        /// 已编码公钥的大小,单位为字节。
        pub const public_key_bytes: usize = 32 + polyT1PackedSize() * p.k;

        /// 编码后秘密密钥的字节大小。
        pub const private_key_bytes: usize = 32 + 32 + p.tr_size +
            polyLeqEtaPackedSize() * (p.l + p.k) + polyT0PackedSize() * p.k;

        /// 已编码签名的大小,单位为字节。
        pub const signature_bytes: usize = p.ctilde_size +
            polyLeGamma1PackedSize() * p.l + p.omega + p.k;

        // 不同多项式表示的打包大小。
        fn polyLeqEtaPackedSize() usize {
            // eta=2 时:每个系数 3 位(值位于 [0,4])
            // eta=4 时:每个系数 4 位(值位于 [0,8])
            const double_eta_bits = if (p.eta == 2) 3 else 4;
            return (N * double_eta_bits) / 8;
        }

        fn polyLeGamma1PackedSize() usize {
            return ((p.gamma1_bits + 1) * N) / 8;
        }

        fn polyT1PackedSize() usize {
            return (N * (Q_BITS - D)) / 8;
        }

        fn polyT0PackedSize() usize {
            return (N * D) / 8;
        }

        fn polyW1PackedSize() usize {
            return (N * (Q_BITS - p.gamma1_bits)) / 8;
        }

        /// 使用 SHAKE-256 计算 CRH(抗碰撞哈希)的辅助函数。
        /// 统一封装哈希操作中重复出现的 init-update-squeeze 模式。
        fn crh(comptime outsize: usize, inputs: anytype) [outsize]u8 {
            var h = sha3.Shake256.init(.{});
            inline for (inputs) |input| {
                h.update(input);
            }
            var out: [outsize]u8 = undefined;
            h.squeeze(&out);
            return out;
        }

        /// 计算 t = As1 + s2 的辅助函数。
        /// 用于密钥生成和公钥重建。
        fn computeT(A: MatKxL, s1_hat: PolyVecL, s2: PolyVecK) PolyVecK {
            const t = A.mulVec(s1_hat).add(s2);
            return t.normalize();
        }

        /// ML-DSA 公钥
        pub const PublicKey = struct {
            /// 编码后的公钥大小,单位为字节
            pub const encoded_length: usize = 32 + polyT1PackedSize() * p.k;

            rho: [32]u8, // 矩阵 A 的种子
            t1: PolyVecK, // t = As1 + s2 的高位

            // 缓存值
            t1_packed: [polyT1PackedSize() * p.k]u8,
            A: MatKxL,
            tr: [p.tr_size]u8, // CRH(rho || t1)

            /// 将公钥编码为字节
            pub fn toBytes(self: PublicKey) [encoded_length]u8 {
                var out: [encoded_length]u8 = undefined;
                @memcpy(out[0..32], &self.rho);
                @memcpy(out[32..], &self.t1_packed);
                return out;
            }

            /// 从字节解码公钥
            pub fn fromBytes(bytes: [encoded_length]u8) !PublicKey {
                var pk: PublicKey = undefined;
                @memcpy(&pk.rho, bytes[0..32]);
                @memcpy(&pk.t1_packed, bytes[32..]);

                pk.t1 = PolyVecK.unpackT1(pk.t1_packed[0..]);
                pk.A = MatKxL.derive(&pk.rho);
                pk.tr = crh(p.tr_size, .{&bytes});

                return pk;
            }
        };

        /// ML-DSA 秘密密钥
        pub const SecretKey = struct {
            /// 已编码私钥的大小,单位为字节
            pub const encoded_length: usize = 32 + 32 + p.tr_size +
                polyLeqEtaPackedSize() * (p.l + p.k) + polyT0PackedSize() * p.k;

            rho: [32]u8, // 矩阵 A 的种子
            key: [32]u8, // 签名生成随机性的种子
            tr: [p.tr_size]u8, // CRH(rho || t1)
            s1: PolyVecL, // 秘密向量 1
            s2: PolyVecK, // 秘密向量 2
            t0: PolyVecK, // t = As1 + s2 的低位

            // 缓存值(处于 NTT 域)
            A: MatKxL,
            s1_hat: PolyVecL,
            s2_hat: PolyVecK,
            t0_hat: PolyVecK,

            /// 将秘密密钥编码为字节
            pub fn toBytes(self: SecretKey) [encoded_length]u8 {
                var out: [encoded_length]u8 = undefined;
                var offset: usize = 0;

                @memcpy(out[offset .. offset + 32], &self.rho);
                offset += 32;

                @memcpy(out[offset .. offset + 32], &self.key);
                offset += 32;

                @memcpy(out[offset .. offset + p.tr_size], &self.tr);
                offset += p.tr_size;

                if (p.eta == 2) {
                    self.s1.packLeqEta(2, out[offset..][0 .. p.l * polyLeqEtaPackedSize()]);
                } else {
                    self.s1.packLeqEta(4, out[offset..][0 .. p.l * polyLeqEtaPackedSize()]);
                }
                offset += p.l * polyLeqEtaPackedSize();

                if (p.eta == 2) {
                    self.s2.packLeqEta(2, out[offset..][0 .. p.k * polyLeqEtaPackedSize()]);
                } else {
                    self.s2.packLeqEta(4, out[offset..][0 .. p.k * polyLeqEtaPackedSize()]);
                }
                offset += p.k * polyLeqEtaPackedSize();

                self.t0.packT0(out[offset..][0 .. p.k * polyT0PackedSize()]);
                offset += p.k * polyT0PackedSize();

                return out;
            }

            /// 从字节解码秘密密钥
            pub fn fromBytes(bytes: [encoded_length]u8) !SecretKey {
                var sk: SecretKey = undefined;
                var offset: usize = 0;

                @memcpy(&sk.rho, bytes[offset .. offset + 32]);
                offset += 32;

                @memcpy(&sk.key, bytes[offset .. offset + 32]);
                offset += 32;

                @memcpy(&sk.tr, bytes[offset .. offset + p.tr_size]);
                offset += p.tr_size;

                sk.s1 = if (p.eta == 2)
                    PolyVecL.unpackLeqEta(2, bytes[offset..][0 .. p.l * polyLeqEtaPackedSize()])
                else
                    PolyVecL.unpackLeqEta(4, bytes[offset..][0 .. p.l * polyLeqEtaPackedSize()]);
                offset += p.l * polyLeqEtaPackedSize();

                sk.s2 = if (p.eta == 2)
                    PolyVecK.unpackLeqEta(2, bytes[offset..][0 .. p.k * polyLeqEtaPackedSize()])
                else
                    PolyVecK.unpackLeqEta(4, bytes[offset..][0 .. p.k * polyLeqEtaPackedSize()]);
                offset += p.k * polyLeqEtaPackedSize();

                sk.t0 = PolyVecK.unpackT0(bytes[offset..][0 .. p.k * polyT0PackedSize()]);
                offset += p.k * polyT0PackedSize();

                // 计算缓存的 NTT 值,以提高签名效率
                sk.A = MatKxL.derive(&sk.rho);
                sk.s1_hat = sk.s1.ntt();
                sk.s2_hat = sk.s2.ntt();
                sk.t0_hat = sk.t0.ntt();

                return sk;
            }

            /// 从此私钥计算公钥
            pub fn public(self: *const SecretKey) PublicKey {
                var pk: PublicKey = undefined;
                pk.rho = self.rho;
                pk.A = self.A;
                pk.tr = self.tr;

                // 重建 t = As1 + s2,再提取高位 t1
                // 使用 power2Round:t = t1 * 2^D + t0
                const t = computeT(self.A, self.s1_hat, self.s2);

                var t0_unused: PolyVecK = undefined;
                pk.t1 = t.power2Round(&t0_unused);
                pk.t1.packT1(&pk.t1_packed);

                return pk;
            }

            /// 创建 Signer,用于增量签署消息。
            /// noise 参数可为 null,以生成确定性签名;
            /// 也可提供随机性生成对冲签名,建议用于抵抗故障攻击。
            pub fn signer(self: *const SecretKey, noise: ?[noise_length]u8) !Signer {
                return self.signerWithContext(noise, "");
            }

            /// 创建 Signer,用于对带上下文的消息增量签名。
            /// noise 参数可为 null,以生成确定性签名;
            /// 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。
            /// context 参数为可选的上下文字符串(最多 255 字节)。
            pub fn signerWithContext(self: *const SecretKey, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer {
                return Signer.init(self, noise, context);
            }
        };

        /// 由种子生成新密钥对(确定性)
        pub fn newKeyFromSeed(seed: *const [seed_length]u8) struct { pk: PublicKey, sk: SecretKey } {
            var sk: SecretKey = undefined;
            var pk: PublicKey = undefined;

            // NIST 模式:使用 SHAKE-256 扩展 seed || k || l,得到 128 字节的扩展种子
            const e_seed = crh(128, .{ seed, &[_]u8{ p.k, p.l } });

            @memcpy(&pk.rho, e_seed[0..32]);
            const s_seed = e_seed[32..96];
            @memcpy(&sk.key, e_seed[96..128]);
            @memcpy(&sk.rho, &pk.rho);

            sk.A = MatKxL.derive(&pk.rho);
            pk.A = sk.A;

            const s_seed_array: *const [64]u8 = s_seed[0..64];
            for (0..p.l) |i| {
                sk.s1.ps[i] = expandS(p.eta, s_seed_array, @intCast(i));
            }

            for (0..p.k) |i| {
                sk.s2.ps[i] = expandS(p.eta, s_seed_array, @intCast(p.l + i));
            }

            sk.s1_hat = sk.s1.ntt();
            sk.s2_hat = sk.s2.ntt();

            const t = computeT(sk.A, sk.s1_hat, sk.s2);

            pk.t1 = t.power2Round(&sk.t0);
            sk.t0_hat = sk.t0.ntt();
            pk.t1.packT1(&pk.t1_packed);

            // tr = H(pk) = H(rho || t1)
            const pk_bytes = pk.toBytes();
            const tr = crh(p.tr_size, .{&pk_bytes});
            sk.tr = tr;
            pk.tr = tr;

            return .{ .pk = pk, .sk = sk };
        }

        /// ML-DSA 签名
        pub const Signature = struct {
            /// 编码后签名的字节大小
            pub const encoded_length: usize = p.ctilde_size +
                polyLeGamma1PackedSize() * p.l + p.omega + p.k;

            c_tilde: [p.ctilde_size]u8, // 挑战哈希
            z: PolyVecL, // 响应向量
            hint: PolyVecK, // 提示向量

            /// 将签名编码为字节
            pub fn toBytes(self: Signature) [encoded_length]u8 {
                var out: [encoded_length]u8 = undefined;
                var offset: usize = 0;

                @memcpy(out[offset .. offset + p.ctilde_size], &self.c_tilde);
                offset += p.ctilde_size;

                self.z.packLeGamma1(p.gamma1_bits, out[offset .. offset + polyLeGamma1PackedSize() * p.l]);
                offset += polyLeGamma1PackedSize() * p.l;

                _ = self.hint.packHint(p.omega, out[offset..]);

                return out;
            }

            /// 从字节解码签名
            pub fn fromBytes(bytes: [encoded_length]u8) EncodingError!Signature {
                var sig: Signature = undefined;
                var offset: usize = 0;

                @memcpy(&sig.c_tilde, bytes[offset .. offset + p.ctilde_size]);
                offset += p.ctilde_size;

                sig.z = PolyVecL.unpackLeGamma1(p.gamma1_bits, bytes[offset .. offset + polyLeGamma1PackedSize() * p.l]);
                offset += polyLeGamma1PackedSize() * p.l;

                // 根据 FIPS 204 验证 ||z||_inf < gamma1 - beta
                if (sig.z.exceeds(gamma1 - beta)) {
                    return error.InvalidEncoding;
                }

                sig.hint = PolyVecK.unpackHint(p.omega, bytes[offset..]) orelse return error.InvalidEncoding;

                return sig;
            }

            pub const VerifyError = Verifier.InitError || Verifier.VerifyError;

            /// 针对消息和公钥验证此签名。
            /// 签名无效则返回错误。
            pub fn verify(
                sig: Signature,
                msg: []const u8,
                public_key: PublicKey,
            ) VerifyError!void {
                return sig.verifyWithContext(msg, public_key, "");
            }

            /// 根据消息、公钥及上下文验证此签名。
            /// 若签名无效,则返回错误。
            /// context 参数为可选上下文字符串,最长 255 字节。
            pub fn verifyWithContext(
                sig: Signature,
                msg: []const u8,
                public_key: PublicKey,
                context: []const u8,
            ) VerifyError!void {
                if (context.len > 255) {
                    return error.SignatureVerificationFailed;
                }

                var h = sha3.Shake256.init(.{});
                h.update(&public_key.tr);
                h.update(&[_]u8{0}); // 域分隔符:纯 ML-DSA 时为 0
                h.update(&[_]u8{@intCast(context.len)});
                if (context.len > 0) {
                    h.update(context);
                }
                h.update(msg);
                var mu: [64]u8 = undefined;
                h.squeeze(&mu);

                const z_hat = sig.z.ntt();
                const Az = public_key.A.mulVecHat(z_hat);

                // 计算 w' ≈ Az - 2^d·c·t1(近似签名时使用的 w)
                var Az2dct1 = public_key.t1.mulBy2toD();
                Az2dct1 = Az2dct1.ntt();
                const c_poly = sampleInBall(p.tau, &sig.c_tilde);
                const c_hat = c_poly.ntt();
                for (0..p.k) |i| {
                    Az2dct1.ps[i] = Az2dct1.ps[i].mulHat(c_hat);
                }
                Az2dct1 = Az.sub(Az2dct1);
                Az2dct1 = Az2dct1.reduceLe2Q();
                Az2dct1 = Az2dct1.invNTT();
                Az2dct1 = Az2dct1.normalizeAssumingLe2Q();

                // 应用提示以恢复高位 w1'
                var w1_prime = Az2dct1.useHint(sig.hint, p.gamma2);
                var w1_packed: [polyW1PackedSize() * p.k]u8 = undefined;
                w1_prime.packW1(p.gamma1_bits, &w1_packed);

                const c_prime = crh(p.ctilde_size, .{ &mu, &w1_packed });

                if (!mem.eql(u8, &c_prime, &sig.c_tilde)) {
                    return error.SignatureVerificationFailed;
                }
            }

            /// 创建用于增量验证签名的 Verifier。
            pub fn verifier(self: Signature, public_key: PublicKey) !Verifier {
                return self.verifierWithContext(public_key, "");
            }

            /// 创建 Verifier,用于带上下文的增量签名验证。
            /// context 参数是可选的上下文字符串(最多 255 字节)。
            pub fn verifierWithContext(self: Signature, public_key: PublicKey, context: []const u8) ContextTooLongError!Verifier {
                return Verifier.init(self, public_key, context);
            }
        };

        /// Signer 用于对流式消息增量计算签名。
        /// 可通过 `signer()` 函数从 `SecretKey` 或 `KeyPair` 获取。
        pub const Signer = struct {
            h: sha3.Shake256, // 用于计算 μ = CRH(tr || msg)
            secret_key: *const SecretKey,
            rnd: [32]u8,

            /// 初始化新的 Signer。
            /// noise 参数可为 null,以生成确定性签名;
            /// 也可提供随机性以生成带随机防护的签名,建议用于抵御故障攻击。
            /// context 参数是可选的上下文字符串,最长 255 字节。
            pub fn init(secret_key: *const SecretKey, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer {
                if (context.len > 255) {
                    return error.ContextTooLong;
                }

                var h = sha3.Shake256.init(.{});
                h.update(&secret_key.tr);
                h.update(&[_]u8{0}); // 域分隔符:纯 ML-DSA 时为 0
                h.update(&[_]u8{@intCast(context.len)});
                if (context.len > 0) {
                    h.update(context);
                }

                return Signer{
                    .h = h,
                    .secret_key = secret_key,
                    .rnd = noise orelse @splat(0),
                };
            }

            /// 向正在签名的消息加入新数据。
            pub fn update(self: *Signer, data: []const u8) void {
                self.h.update(data);
            }

            /// 计算整个消息的签名。
            pub fn finalize(self: *Signer) Signature {
                var mu: [64]u8 = undefined;
                self.h.squeeze(&mu);

                const rho_prime = crh(64, .{ &self.secret_key.key, &self.rnd, &mu });

                var sig: Signature = undefined;
                var y_nonce: u16 = 0;

                // 拒绝采样循环(FIPS 204 算法 2,步骤 5–16)。
                var attempt: u32 = 0;
                while (true) {
                    attempt += 1;
                    if (attempt >= 576) { // (6/7)⁵⁷⁶ < 2⁻¹²⁸
                        @branchHint(.unlikely);
                        unreachable;
                    }

                    const y = PolyVecL.deriveUniformLeGamma1(p.gamma1_bits, &rho_prime, y_nonce);
                    y_nonce += @intCast(p.l);

                    const y_hat = y.ntt();
                    var w = self.secret_key.A.mulVec(y_hat);

                    w = w.normalize();
                    var w0: PolyVecK = undefined;
                    const w1 = w.decomposeVec(p.gamma2, &w0);
                    var w1_packed: [polyW1PackedSize() * p.k]u8 = undefined;
                    w1.packW1(p.gamma1_bits, &w1_packed);

                    sig.c_tilde = crh(p.ctilde_size, .{ &mu, &w1_packed });

                    const c_poly = sampleInBall(p.tau, &sig.c_tilde);
                    const c_hat = c_poly.ntt();

                    // 拒绝检查:确保掩码有效
                    var w0mcs2: PolyVecK = undefined;
                    for (0..p.k) |i| {
                        w0mcs2.ps[i] = c_hat.mulHat(self.secret_key.s2_hat.ps[i]);
                        w0mcs2.ps[i] = w0mcs2.ps[i].invNTT();
                    }
                    w0mcs2 = w0.sub(w0mcs2);
                    w0mcs2 = w0mcs2.normalize();

                    if (w0mcs2.exceeds(p.gamma2 - beta)) {
                        continue;
                    }

                    // 计算响应 z = y + c·s1
                    for (0..p.l) |i| {
                        sig.z.ps[i] = c_hat.mulHat(self.secret_key.s1_hat.ps[i]);
                        sig.z.ps[i] = sig.z.ps[i].invNTT();
                    }
                    sig.z = sig.z.add(y);
                    sig.z = sig.z.normalize();

                    if (sig.z.exceeds(gamma1 - beta)) {
                        continue;
                    }

                    var ct0: PolyVecK = undefined;
                    for (0..p.k) |i| {
                        ct0.ps[i] = c_hat.mulHat(self.secret_key.t0_hat.ps[i]);
                        ct0.ps[i] = ct0.ps[i].invNTT();
                    }
                    ct0 = ct0.reduceLe2Q();
                    ct0 = ct0.normalize();

                    if (ct0.exceeds(p.gamma2)) {
                        continue;
                    }

                    // 生成用于验证的提示
                    var w0mcs2pct0 = w0mcs2.add(ct0);
                    w0mcs2pct0 = w0mcs2pct0.reduceLe2Q();
                    w0mcs2pct0 = w0mcs2pct0.normalizeAssumingLe2Q();
                    const hint_result = PolyVecK.makeHintVec(w0mcs2pct0, w1, p.gamma2);
                    if (hint_result.pop > p.omega) {
                        continue;
                    }
                    sig.hint = hint_result.hint;

                    return sig;
                }
            }
        };

        /// Verifier 用于对流式消息增量验证签名。
        /// 可通过 `Signature` 的 `verifier()` 函数获取。
        pub const Verifier = struct {
            h: sha3.Shake256, // 用于计算 μ = CRH(tr || msg)
            signature: Signature,
            public_key: PublicKey,

            pub const InitError = EncodingError;
            pub const VerifyError = SignatureVerificationError;

            /// 初始化新的 Verifier。
            /// context 参数是可选的上下文字符串,最长 255 字节。
            pub fn init(signature: Signature, public_key: PublicKey, context: []const u8) ContextTooLongError!Verifier {
                if (context.len > 255) {
                    return error.ContextTooLong;
                }

                var h = sha3.Shake256.init(.{});
                h.update(&public_key.tr);
                h.update(&[_]u8{0}); // 域分隔符:纯 ML-DSA 时为 0
                h.update(&[_]u8{@intCast(context.len)}); // 上下文长度
                if (context.len > 0) {
                    h.update(context);
                }

                return Verifier{
                    .h = h,
                    .signature = signature,
                    .public_key = public_key,
                };
            }

            /// 向待验证消息添加新内容。
            pub fn update(self: *Verifier, data: []const u8) void {
                self.h.update(data);
            }

            /// 验证签名对整个消息有效。
            pub fn verify(self: *Verifier) SignatureVerificationError!void {
                var mu: [64]u8 = undefined;
                self.h.squeeze(&mu);

                const z_hat = self.signature.z.ntt();
                const Az = self.public_key.A.mulVecHat(z_hat);

                // 计算 w' ≈ Az - 2^d·c·t1(近似签名时使用的 w)
                var Az2dct1 = self.public_key.t1.mulBy2toD();
                Az2dct1 = Az2dct1.ntt();
                const c_poly = sampleInBall(p.tau, &self.signature.c_tilde);
                const c_hat = c_poly.ntt();
                for (0..p.k) |i| {
                    Az2dct1.ps[i] = Az2dct1.ps[i].mulHat(c_hat);
                }
                Az2dct1 = Az.sub(Az2dct1);
                Az2dct1 = Az2dct1.reduceLe2Q();
                Az2dct1 = Az2dct1.invNTT();
                Az2dct1 = Az2dct1.normalizeAssumingLe2Q();

                // 应用提示以恢复高位 w1'
                var w1_prime = Az2dct1.useHint(self.signature.hint, p.gamma2);
                var w1_packed: [polyW1PackedSize() * p.k]u8 = undefined;
                w1_prime.packW1(p.gamma1_bits, &w1_packed);

                const c_prime = crh(p.ctilde_size, .{ &mu, &w1_packed });

                if (!mem.eql(u8, &c_prime, &self.signature.c_tilde)) {
                    return error.SignatureVerificationFailed;
                }
            }
        };

        /// 由私钥及其对应公钥组成的密钥对。
        pub const KeyPair = struct {
            /// 创建密钥对所需种子的长度(字节)。
            pub const seed_length = Self.seed_length;

            /// 公钥分量。
            public_key: PublicKey,

            /// 秘密密钥分量。
            secret_key: SecretKey,

            /// 生成新的随机密钥对。
            pub fn generate(io: std.Io) KeyPair {
                var seed: [Self.seed_length]u8 = undefined;
                io.random(&seed);
                return generateDeterministic(seed) catch unreachable;
            }

            /// 根据种子确定性地生成密钥对。
            /// 用于测试或要求可重现性的场景。
            /// 种子应使用密码学安全的随机源生成。
            pub fn generateDeterministic(seed: [32]u8) !KeyPair {
                const keys = newKeyFromSeed(&seed);
                return .{
                    .public_key = keys.pk,
                    .secret_key = keys.sk,
                };
            }

            /// 从已有私钥派生公钥。
            /// 从私钥重新计算公钥的各个部分。
            pub fn fromSecretKey(sk: SecretKey) !KeyPair {
                var pk: PublicKey = undefined;
                pk.rho = sk.rho;
                pk.tr = sk.tr;
                pk.A = sk.A;

                const t = computeT(sk.A, sk.s1_hat, sk.s2);

                var t0: PolyVecK = undefined;
                pk.t1 = t.power2Round(&t0);
                pk.t1.packT1(&pk.t1_packed);

                return .{
                    .public_key = pk,
                    .secret_key = sk,
                };
            }

            /// 创建 Signer,用于增量签署消息。
            /// noise 参数可为 null,以生成确定性签名;
            /// 也可提供随机性生成对冲签名,建议用于抵抗故障攻击。
            pub fn signer(self: *const KeyPair, noise: ?[noise_length]u8) !Signer {
                return self.secret_key.signer(noise);
            }

            /// 创建 Signer,用于对带上下文的消息增量签名。
            /// noise 参数可为 null,以生成确定性签名;
            /// 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。
            /// context 参数为可选的上下文字符串(最多 255 字节)。
            pub fn signerWithContext(self: *const KeyPair, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer {
                return self.secret_key.signerWithContext(noise, context);
            }

            /// 使用此密钥对对消息签名。
            /// noise 参数可以为 null,以生成确定性签名;
            /// 也可提供随机性以生成对冲签名(建议用于抵御故障攻击)。
            pub fn sign(
                kp: KeyPair,
                msg: []const u8,
                noise: ?[noise_length]u8,
            ) !Signature {
                return kp.signWithContext(msg, noise, "");
            }

            /// 使用此密钥对,对带上下文的消息签名。
            /// noise 参数可为 null,以生成确定性签名;
            /// 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。
            /// context 参数为可选的上下文字符串(最多 255 字节)。
            pub fn signWithContext(
                kp: KeyPair,
                msg: []const u8,
                noise: ?[noise_length]u8,
                context: []const u8,
            ) ContextTooLongError!Signature {
                var st = try kp.signerWithContext(noise, context);
                st.update(msg);
                return st.finalize();
            }
        };
    };
}

test "modular arithmetic" {
    // 测试蒙哥马利约减
    const x: u64 = 12345678;
    const y = montReduceLe2Q(x);
    try testing.expect(y < 2 * Q);

    // 测试 modQ
    try testing.expectEqual(@as(u32, 0), modQ(Q));
    try testing.expectEqual(@as(u32, 1), modQ(Q + 1));
}

test "polynomial operations" {
    var p1 = Poly.zero;
    p1.cs[0] = 1;
    p1.cs[1] = 2;

    var p2 = Poly.zero;
    p2.cs[0] = 3;
    p2.cs[1] = 4;

    const p3 = p1.add(p2);
    try testing.expectEqual(@as(u32, 4), p3.cs[0]);
    try testing.expectEqual(@as(u32, 6), p3.cs[1]);
}

test "NTT and inverse NTT" {
    // 创建普通形式(非 Montgomery 形式)的测试多项式
    var p = Poly.zero;
    for (0..N) |i| {
        p.cs[i] = @intCast(i % Q);
    }

    // 先应用 NTT,再应用逆 NTT。
    // 根据 Dilithium 规范,NTT 后接 invNTT 相当于乘以 R。
    // 因此结果为 p * R,即 p 的蒙哥马利形式。
    var p_ntt = p.ntt();

    // 在 invNTT 前约减(与 Go 测试一致)
    p_ntt = p_ntt.reduceLe2Q();

    const p_restored = p_ntt.invNTT();

    // 约减并正规化
    const p_reduced = p_restored.reduceLe2Q();
    const p_norm = p_reduced.normalize();

    // 检查是否得到 p * R(等于 toMont(p))
    for (0..N) |i| {
        const original: u32 = @intCast(i % Q);
        const expected = toMont(original);
        const expected_norm = modQ(expected);
        try testing.expectEqual(expected_norm, p_norm.cs[i]);
    }
}

test "parameter set instantiation" {
    // 仅验证能否实例化全部三组参数
    const ml44 = MLDSA44;
    const ml65 = MLDSA65;
    const ml87 = MLDSA87;

    try testing.expectEqualStrings("ML-DSA-44", ml44.name);
    try testing.expectEqualStrings("ML-DSA-65", ml65.name);
    try testing.expectEqualStrings("ML-DSA-87", ml87.name);
}

test "compare zetas with Go implementation" {
    // Go 实现中的前 16 个 zeta 值(Montgomery 形式)。
    const go_zetas = [16]u32{
        4193792, 25847,   5771523, 7861508, 237124,  7602457, 7504169,
        466468,  1826347, 2353451, 8021166, 6288512, 3119733, 5495562,
        3111497, 2680103,
    };

    // 将计算出的 zetas 与 Go 的结果比较
    for (0..16) |i| {
        try testing.expectEqual(go_zetas[i], zetas[i]);
    }
}

test "NTT with simple polynomial" {
    // 使用非常简单的多项式测试:常规表示中仅一个系数设为 1
    var p = Poly.zero;
    p.cs[0] = 1;

    var p_ntt = p.ntt();

    // 在 invNTT 前约减(与 Go 测试一致)
    p_ntt = p_ntt.reduceLe2Q();

    const p_restored = p_ntt.invNTT();

    // 结果应为 Montgomery 表示中的 1 * R = toMont(1)
    const p_reduced = p_restored.reduceLe2Q();
    const p_norm = p_reduced.normalize();

    const expected = modQ(toMont(1));
    try testing.expectEqual(expected, p_norm.cs[0]);

    // 其余系数应为 0 * R = 0
    for (1..N) |i| {
        try testing.expectEqual(@as(u32, 0), p_norm.cs[i]);
    }
}

test "Montgomery reduction correctness" {
    // 测试 Montgomery 约减是否正常工作
    // montReduceLe2Q(a * b * R) = a * b mod q(其中 a、b 采用 Montgomery 表示)

    const x: u32 = 12345;
    const y: u32 = 67890;

    // 转换为蒙哥马利形式
    const x_mont = toMont(x);
    const y_mont = toMont(y);

    // 在蒙哥马利表示下相乘
    const product_mont = montReduceLe2Q(@as(u64, x_mont) * @as(u64, y_mont));

    // 从蒙哥马利形式转换回来
    const product = montReduceLe2Q(@as(u64, product_mont));

    // 直接乘法后对 q 取模
    const expected = modQ(@as(u32, @intCast((@as(u64, x) * @as(u64, y)) % Q)));

    try testing.expectEqual(expected, modQ(product));
}

// 移除了调试测试,因为它使输出产生干扰

test "compare inv_zetas with Go implementation" {
    // Go 实现中的前 16 个 inv_zetas
    const go_inv_zetas = [16]u32{
        6403635, 846154,  6979993, 4442679, 1362209, 48306,   4460757,
        554416,  3545687, 6767575, 976891,  8196974, 2286327, 420899,
        2235985, 2939036,
    };

    // 将计算得到的 inv_zetas 与 Go 的结果比较
    for (0..16) |i| {
        if (inv_zetas[i] != go_inv_zetas[i]) {
            std.debug.print("Mismatch at inv_zetas[{d}]: got {d}, expected {d}\n", .{ i, inv_zetas[i], go_inv_zetas[i] });
        }
        try testing.expectEqual(go_inv_zetas[i], inv_zetas[i]);
    }
}

test "power2Round correctness" {
    // 测试 power2Round 是否正确拆分数值。
    // 对于所有 a ∈ [0, Q),应有 a = a1*2^D + a0,
    // 其中 -2^(D-1) < a0 <= 2^(D-1)。

    // 测试若干特定值
    const test_values = [_]u32{ 0, 1, Q / 2, Q - 1, 12345, 8380416 };

    for (test_values) |a| {
        if (a >= Q) continue;

        const result = power2Round(a);
        const a0 = @as(i32, @bitCast(result.a0_plus_q -% Q));
        const a1 = result.a1;

        // 检查重构:a = a1*2^D + a0
        const reconstructed = @as(i32, @bitCast(a1 << D)) + a0;
        try testing.expectEqual(@as(i32, @bitCast(a)), reconstructed);

        // 检查 a0 边界:-2^(D-1) < a0 <= 2^(D-1)
        const bound: i32 = 1 << (D - 1);
        try testing.expect(a0 > -bound and a0 <= bound);
    }
}

test "decompose correctness for ML-DSA-65" {
    // 使用 gamma2 = 95232(ML-DSA-44)测试分解
    const gamma2 = 95232;
    const alpha = 2 * gamma2;

    const test_values = [_]u32{ 0, 1, Q / 2, Q - 1, 12345 };

    for (test_values) |a| {
        if (a >= Q) continue;

        const result = decompose(a, gamma2);
        const a0 = @as(i32, @bitCast(result.a0_plus_q -% Q));
        const a1 = result.a1;

        // 检查重构:a = a1*alpha + a0 (mod Q)。
        var reconstructed: i64 = @as(i64, @intCast(a1)) * @as(i64, @intCast(alpha)) + @as(i64, a0);
        reconstructed = @mod(reconstructed, @as(i64, Q));
        try testing.expectEqual(@as(i64, @intCast(a)), reconstructed);

        // 检查 a0 的边界(近似)
        const bound: i32 = @intCast(alpha / 2);
        try testing.expect(@abs(a0) <= bound);
    }
}

test "decompose correctness for ML-DSA-87" {
    // 测试 gamma2 = 261888 时的 decompose(ML-DSA-65 和 ML-DSA-87)
    const gamma2 = 261888;
    const alpha = 2 * gamma2;

    const test_values = [_]u32{ 0, 1, Q / 2, Q - 1, 12345 };

    for (test_values) |a| {
        if (a >= Q) continue;

        const result = decompose(a, gamma2);
        const a0 = @as(i32, @bitCast(result.a0_plus_q -% Q));
        const a1 = result.a1;

        // 检查重构:a = a1*alpha + a0 (mod Q)。
        var reconstructed: i64 = @as(i64, @intCast(a1)) * @as(i64, @intCast(alpha)) + @as(i64, a0);
        reconstructed = @mod(reconstructed, @as(i64, Q));
        try testing.expectEqual(@as(i64, @intCast(a)), reconstructed);

        // 检查 a0 的边界(近似)
        const bound: i32 = @intCast(alpha / 2);
        try testing.expect(@abs(a0) <= bound);
    }
}

test "polyDeriveUniform deterministic" {
    // 测试 polyDeriveUniform 产生确定性结果
    const seed: [32]u8 = .{0x01} ++ @as([31]u8, @splat(0x00));
    const nonce: u16 = 0;

    const p1 = polyDeriveUniform(&seed, nonce);
    const p2 = polyDeriveUniform(&seed, nonce);

    // 应当相同
    for (0..N) |i| {
        try testing.expectEqual(p1.cs[i], p2.cs[i]);
    }

    // 所有系数应位于 [0, Q)
    for (0..N) |i| {
        try testing.expect(p1.cs[i] < Q);
    }
}

test "polyDeriveUniform different nonces" {
    // 测试不同 nonce 会产生不同多项式
    const seed: [32]u8 = .{0x01} ++ @as([31]u8, @splat(0x00));

    const p1 = polyDeriveUniform(&seed, 0);
    const p2 = polyDeriveUniform(&seed, 1);

    // 应当不同
    var different = false;
    for (0..N) |i| {
        if (p1.cs[i] != p2.cs[i]) {
            different = true;
            break;
        }
    }
    try testing.expect(different);
}

test "expandS with eta=2" {
    // 测试 eta=2 采样
    const seed: [64]u8 = .{0x02} ++ @as([63]u8, @splat(0x00));
    const nonce: u16 = 0;

    const p = expandS(2, &seed, nonce);

    // 所有系数都应位于 [Q-eta, Q+eta]
    // 函数返回 Q + eta - t 形式的系数,其中 t 位于 [0, 2*eta]
    // 因此系数位于 [Q-eta, Q+eta]
    for (0..N) |i| {
        const c = p.cs[i];
        // 检查 c 是否位于 [Q-2, Q+2]
        try testing.expect(c >= Q - 2 and c <= Q + 2);
    }
}

test "expandS with eta=4" {
    // 测试 eta=4 采样
    const seed: [64]u8 = .{0x03} ++ @as([63]u8, @splat(0x00));
    const nonce: u16 = 0;

    const p = expandS(4, &seed, nonce);

    // 所有系数应位于 [Q-eta, Q+eta]
    for (0..N) |i| {
        const c = p.cs[i];
        // 检查界限(系数位于 Q ± eta 附近)。
        const diff = if (c >= Q) c - Q else Q - c;
        try testing.expect(diff <= 4);
    }
}

test "sampleInBall has correct weight" {
    // 测试 ball 多项式是否恰好具有 tau 个非零系数
    const tau = 39; // 来自 ML-DSA-44
    const seed: [32]u8 = .{0x03} ++ @as([31]u8, @splat(0x00));

    const p = sampleInBall(tau, &seed);

    // 统计非零系数
    var count: u32 = 0;
    for (0..N) |i| {
        if (p.cs[i] != 0) {
            count += 1;
            // 非零系数应为 1 或 Q-1
            try testing.expect(p.cs[i] == 1 or p.cs[i] == Q - 1);
        }
    }

    try testing.expectEqual(tau, count);
}

test "sampleInBall deterministic" {
    // 测试球采样具有确定性
    const tau = 49; // 来自 ML-DSA-65
    const seed: [32]u8 = .{0x05} ++ @as([31]u8, @splat(0x00));

    const p1 = sampleInBall(tau, &seed);
    const p2 = sampleInBall(tau, &seed);

    // 应当相同
    for (0..N) |i| {
        try testing.expectEqual(p1.cs[i], p2.cs[i]);
    }
}

test "polyPackLeqEta / polyUnpackLeqEta roundtrip for eta=2" {
    // 测试 eta=2 时的打包与解包
    const eta = 2;

    // 创建系数位于 [Q-eta, Q+eta] 内的测试多项式
    var p = Poly.zero;
    for (0..N) |i| {
        // 使用范围内的多个值
        const val = @as(u32, @intCast(i % 5)); // 0, 1, 2, 3, 4
        p.cs[i] = Q + eta - val;
    }

    // 打包
    var buf: [96]u8 = undefined; // eta=2:每个系数占 3 位,共 96 字节
    polyPackLeqEta(p, eta, &buf);

    // 解包
    const p2 = polyUnpackLeqEta(eta, &buf);

    // 应当相同
    for (0..N) |i| {
        try testing.expectEqual(p.cs[i], p2.cs[i]);
    }
}

test "polyPackLeqEta / polyUnpackLeqEta roundtrip for eta=4" {
    // 测试 eta=4 的打包与解包
    const eta = 4;

    // 创建系数位于 [Q-eta, Q+eta] 内的测试多项式
    var p = Poly.zero;
    for (0..N) |i| {
        // 使用范围内的多个值
        const val = @as(u32, @intCast(i % 9)); // 0, 1, 2, ..., 8
        p.cs[i] = Q + eta - val;
    }

    // 打包
    var buf: [128]u8 = undefined; // eta=4:每个系数 4 位 = 128 字节
    polyPackLeqEta(p, eta, &buf);

    // 解包
    const p2 = polyUnpackLeqEta(eta, &buf);

    // 应当相同
    for (0..N) |i| {
        try testing.expectEqual(p.cs[i], p2.cs[i]);
    }
}

test "polyPackT1 / polyUnpackT1 roundtrip" {
    // 创建系数 < 1024 的测试多项式
    var p = Poly.zero;
    for (0..N) |i| {
        p.cs[i] = @intCast(i % 1024);
    }

    // 打包
    var buf: [320]u8 = undefined; // (256 * 10) / 8 = 320 字节
    polyPackT1(p, &buf);

    // 解包
    const p2 = polyUnpackT1(&buf);

    // 应当相同
    for (0..N) |i| {
        try testing.expectEqual(p.cs[i], p2.cs[i]);
    }
}

test "polyPackT0 / polyUnpackT0 roundtrip" {
    // 创建系数位于 (Q-2^12, Q+2^12] 的测试多项式。
    // 这是范围 (-2^12, 2^12] 以 Q 附近无符号数表示的形式。
    const bound = 1 << 12; // 2^(D-1),其中 D=13
    var p = Poly.zero;
    for (0..N) |i| {
        // 遍历 T0 的有效范围。
        // 值应为 Q + offset,其中 offset 位于 (-bound, bound]。
        const cycle_val = @as(i32, @intCast(i % (2 * bound))); // 从 0 到 2*bound-1
        const offset = cycle_val - bound + 1; // 从 (-bound+1) 到 bound
        p.cs[i] = @as(u32, @intCast(@as(i32, Q) + offset));
    }

    // 打包
    var buf: [416]u8 = undefined; // (256 * 13) / 8 = 416 字节
    polyPackT0(p, &buf);

    // 解包
    const p2 = polyUnpackT0(&buf);

    // 应当相同
    for (0..N) |i| {
        try testing.expectEqual(p.cs[i], p2.cs[i]);
    }
}

test "polyPackLeGamma1 / polyUnpackLeGamma1 roundtrip gamma1_bits=17" {
    const gamma1_bits = 17;
    const gamma1: u32 = @as(u32, 1) << gamma1_bits;

    // 创建系数位于 (-gamma1, gamma1] 的测试多项式。
    // 归一化表示:[0, gamma1] ∪ (Q-gamma1, Q)。
    var p = Poly.zero;
    for (0..N) |i| {
        if (i % 2 == 0) {
            // 正值:[0, gamma1]
            p.cs[i] = @intCast((i / 2) % (gamma1 + 1));
        } else {
            // 负值:(Q-gamma1, Q)
            const neg_val: u32 = @intCast(((i / 2) % gamma1) + 1);
            p.cs[i] = Q - neg_val;
        }
    }

    // 打包
    var buf: [576]u8 = undefined; // (256 * 18) / 8 = 576 字节
    polyPackLeGamma1(p, gamma1_bits, &buf);

    // 解包
    const p2 = polyUnpackLeGamma1(gamma1_bits, &buf);

    // 应当相同
    for (0..N) |i| {
        try testing.expectEqual(p.cs[i], p2.cs[i]);
    }
}

test "polyPackLeGamma1 / polyUnpackLeGamma1 roundtrip gamma1_bits=19" {
    const gamma1_bits = 19;
    const gamma1: u32 = @as(u32, 1) << gamma1_bits;

    // 创建系数位于 (-gamma1, gamma1] 的测试多项式。
    var p = Poly.zero;
    for (0..N) |i| {
        if (i % 2 == 0) {
            // 正值:[0, gamma1]
            p.cs[i] = @intCast((i / 2) % (gamma1 + 1));
        } else {
            // 负值:(Q-gamma1, Q)
            const neg_val: u32 = @intCast(((i / 2) % gamma1) + 1);
            p.cs[i] = Q - neg_val;
        }
    }

    // 打包
    var buf: [640]u8 = undefined; // (256 * 20) / 8 = 640 字节
    polyPackLeGamma1(p, gamma1_bits, &buf);

    // 解包
    const p2 = polyUnpackLeGamma1(gamma1_bits, &buf);

    // 应当相同
    for (0..N) |i| {
        try testing.expectEqual(p.cs[i], p2.cs[i]);
    }
}

test "polyPackW1 for gamma1_bits=17" {
    const gamma1_bits = 17;

    // 创建具有小系数的测试多项式(w1 值 < 64)
    var p = Poly.zero;
    for (0..N) |i| {
        p.cs[i] = @intCast(i % 64); // 6 位值
    }

    // 打包
    var buf: [192]u8 = undefined; // (256 * 6) / 8 = 192 字节
    polyPackW1(p, gamma1_bits, &buf);

    // 验证基本性质。
    // 所有字节均应被使用。
    var non_zero = false;
    for (buf) |b| {
        if (b != 0) {
            non_zero = true;
            break;
        }
    }
    try testing.expect(non_zero);
}

test "polyPackW1 for gamma1_bits=19" {
    const gamma1_bits = 19;

    // 创建系数较小的测试多项式(w1 值 < 16)。
    var p = Poly.zero;
    for (0..N) |i| {
        p.cs[i] = @intCast(i % 16); // 4 位值
    }

    // 打包
    var buf: [128]u8 = undefined; // (256 * 4) / 8 = 128 字节
    polyPackW1(p, gamma1_bits, &buf);

    // 验证基本性质
    var non_zero = false;
    for (buf) |b| {
        if (b != 0) {
            non_zero = true;
            break;
        }
    }
    try testing.expect(non_zero);
}

test "makeHint and useHint correctness for gamma2=261888" {
    // 测试 ML-DSA-65 和 ML-DSA-87
    const gamma2: u32 = 261888;

    // 测试选取的一组值,以验证提示机制正常工作。
    const test_values = [_]u32{ 0, 100, 1000, 10000, 100000, 1000000, Q / 2, Q - 1 };

    for (test_values) |w| {
        // 分解 w 得到 w0 和 w1
        const decomp = decompose(w, gamma2);
        const w0_plus_q = decomp.a0_plus_q;
        const w1 = decomp.a1;

        // 使用 [0, gamma2] 内的不同小扰动 f 进行测试
        const perturbations = [_]u32{ 0, 1, 10, 100, 1000, gamma2 / 2, gamma2 };

        for (perturbations) |f| {
            // 测试 f(正扰动)
            const z0_pos = (w0_plus_q +% Q -% f) % Q;
            const hint_pos = makeHint(z0_pos, w1, gamma2);
            const w_perturbed_pos = (w +% Q -% f) % Q;
            const w1_recovered_pos = useHint(w_perturbed_pos, hint_pos, gamma2);
            try testing.expectEqual(w1, w1_recovered_pos);

            // 测试 -f(负向扰动)
            if (f > 0) {
                const z0_neg = (w0_plus_q +% f) % Q;
                const hint_neg = makeHint(z0_neg, w1, gamma2);
                const w_perturbed_neg = (w +% f) % Q;
                const w1_recovered_neg = useHint(w_perturbed_neg, hint_neg, gamma2);
                try testing.expectEqual(w1, w1_recovered_neg);
            }
        }
    }
}

test "makeHint and useHint correctness for gamma2=95232" {
    // ML-DSA-44 测试
    const gamma2: u32 = 95232;

    // 测试选取的一组值,以验证提示机制正常工作。
    const test_values = [_]u32{ 0, 100, 1000, 10000, 100000, 1000000, Q / 2, Q - 1 };

    for (test_values) |w| {
        // 分解 w 得到 w0 和 w1
        const decomp = decompose(w, gamma2);
        const w0_plus_q = decomp.a0_plus_q;
        const w1 = decomp.a1;

        // 使用 [0, gamma2] 内的不同小扰动 f 进行测试
        const perturbations = [_]u32{ 0, 1, 10, 100, 1000, gamma2 / 2, gamma2 };

        for (perturbations) |f| {
            // 测试 f(正扰动)
            const z0_pos = (w0_plus_q +% Q -% f) % Q;
            const hint_pos = makeHint(z0_pos, w1, gamma2);
            const w_perturbed_pos = (w +% Q -% f) % Q;
            const w1_recovered_pos = useHint(w_perturbed_pos, hint_pos, gamma2);
            try testing.expectEqual(w1, w1_recovered_pos);

            // 测试 -f(负向扰动)
            if (f > 0) {
                const z0_neg = (w0_plus_q +% f) % Q;
                const hint_neg = makeHint(z0_neg, w1, gamma2);
                const w_perturbed_neg = (w +% f) % Q;
                const w1_recovered_neg = useHint(w_perturbed_neg, hint_neg, gamma2);
                try testing.expectEqual(w1, w1_recovered_neg);
            }
        }
    }
}

test "polyMakeHint basic functionality" {
    const gamma2: u32 = 261888;

    // 创建测试多项式
    var p0 = Poly.zero;
    var p1 = Poly.zero;

    // 填入测试值
    for (0..N) |i| {
        p0.cs[i] = @intCast((i * 17) % Q);
        p1.cs[i] = @intCast((i * 3) % 16); // gamma2=261888 时高位至多为 15
    }

    // 生成提示
    const result = polyMakeHint(p0, p1, gamma2);
    const hint = result.hint;
    const count = result.count;

    // 验证提示值为二进制值
    for (0..N) |i| {
        try testing.expect(hint.cs[i] == 0 or hint.cs[i] == 1);
    }

    // 验证 count 与 hint 中 1 的数量相符
    var actual_count: u32 = 0;
    for (0..N) |i| {
        actual_count += hint.cs[i];
    }
    try testing.expectEqual(count, actual_count);
}

test "polyUseHint reconstruction" {
    const gamma2: u32 = 261888;

    // 创建测试多项式 q
    var q = Poly.zero;
    for (0..N) |i| {
        q.cs[i] = @intCast((i * 123) % Q);
    }

    // 分解 q 以获得高位和低位
    var q0_plus_q_array: [N]u32 = undefined;
    var q1_array: [N]u32 = undefined;
    for (0..N) |i| {
        const decomp = decompose(q.cs[i], gamma2);
        q0_plus_q_array[i] = decomp.a0_plus_q;
        q1_array[i] = decomp.a1;
    }

    const q0_plus_q = Poly{ .cs = q0_plus_q_array };
    const q1 = Poly{ .cs = q1_array };

    // 创建提示(此情况下,由于 q 和 q 相同,提示大多为 0)
    const hint_result = polyMakeHint(q0_plus_q, q1, gamma2);
    const hint = hint_result.hint;

    // 使用提示恢复高位
    const recovered = polyUseHint(q, hint, gamma2);

    // 恢复结果应与原始高位 q1 一致
    for (0..N) |i| {
        try testing.expectEqual(q1.cs[i], recovered.cs[i]);
    }
}

test "hint roundtrip with perturbation" {
    const gamma2: u32 = 261888;

    // 创建测试多项式 w
    var w = Poly.zero;
    for (0..N) |i| {
        w.cs[i] = @intCast((i * 7919) % Q);
    }

    // 分解 w 得到 w0 和 w1
    var w0_plus_q = Poly.zero;
    var w1 = Poly.zero;
    for (0..N) |i| {
        const decomp = decompose(w.cs[i], gamma2);
        w0_plus_q.cs[i] = decomp.a0_plus_q;
        w1.cs[i] = decomp.a1;
    }

    // 施加微小扰动
    var f = Poly.zero;
    for (0..N) |i| {
        // [-gamma2, gamma2] 中的微小扰动
        const f_val = @as(u32, @intCast(i % 1000));
        f.cs[i] = if (i % 2 == 0) f_val else Q -% f_val;
    }

    // 计算 w' = w - f 和 z0 = w0 - f
    var w_prime = Poly.zero;
    var z0 = Poly.zero;
    for (0..N) |i| {
        w_prime.cs[i] = (w.cs[i] +% Q -% f.cs[i]) % Q;
        z0.cs[i] = (w0_plus_q.cs[i] +% Q -% f.cs[i]) % Q;
    }

    // 生成提示
    const hint_result = polyMakeHint(z0, w1, gamma2);
    const hint = hint_result.hint;

    // 使用提示从 w_prime 中恢复 w1
    const w1_recovered = polyUseHint(w_prime, hint, gamma2);

    // 验证已恢复原始高位
    for (0..N) |i| {
        try testing.expectEqual(w1.cs[i], w1_recovered.cs[i]);
    }
}

// 用于密钥生成的参数化测试辅助函数

fn testKeyGenerationBasic(comptime MlDsa: type, seed: [32]u8) !void {
    const result = MlDsa.newKeyFromSeed(&seed);
    const pk = result.pk;
    const sk = result.sk;

    // 基本合理性检查
    try testing.expect(pk.rho.len == 32);
    try testing.expect(sk.rho.len == 32);
    try testing.expectEqualSlices(u8, &pk.rho, &sk.rho);

    // 验证 pk 与 sk 中的 tr 是否匹配
    try testing.expectEqualSlices(u8, &pk.tr, &sk.tr);

    // 测试公钥的 toBytes/fromBytes 往返转换
    const pk_bytes = pk.toBytes();
    const pk2 = try MlDsa.PublicKey.fromBytes(pk_bytes);
    try testing.expectEqualSlices(u8, &pk.rho, &pk2.rho);
    try testing.expectEqualSlices(u8, &pk.tr, &pk2.tr);

    // 测试私钥的 toBytes/fromBytes 往返转换
    const sk_bytes = sk.toBytes();
    const sk2 = try MlDsa.SecretKey.fromBytes(sk_bytes);
    try testing.expectEqualSlices(u8, &sk.rho, &sk2.rho);
    try testing.expectEqualSlices(u8, &sk.key, &sk2.key);
    try testing.expectEqualSlices(u8, &sk.tr, &sk2.tr);
}

test "Key generation basic - all variants" {
    inline for (.{
        .{ .variant = MLDSA44, .seed_byte = 0x44 },
        .{ .variant = MLDSA65, .seed_byte = 0x65 },
        .{ .variant = MLDSA87, .seed_byte = 0x87 },
    }) |config| {
        const seed: [32]u8 = @splat(config.seed_byte);
        try testKeyGenerationBasic(config.variant, seed);
    }
}

test "Key generation determinism" {
    const seed = [_]u8{ 0x12, 0x34, 0x56, 0x78 } ++ @as([28]u8, @splat(0xAB));

    // 从相同种子生成两对密钥
    const result1 = MLDSA44.newKeyFromSeed(&seed);
    const result2 = MLDSA44.newKeyFromSeed(&seed);

    // 它们应当相同
    const pk_bytes1 = result1.pk.toBytes();
    const pk_bytes2 = result2.pk.toBytes();
    try testing.expectEqualSlices(u8, &pk_bytes1, &pk_bytes2);

    const sk_bytes1 = result1.sk.toBytes();
    const sk_bytes2 = result2.sk.toBytes();
    try testing.expectEqualSlices(u8, &sk_bytes1, &sk_bytes2);
}

test "Private key can compute public key" {
    const seed: [32]u8 = @splat(0xFF);
    const result = MLDSA44.newKeyFromSeed(&seed);
    const pk = result.pk;
    const sk = result.sk;

    // 从私钥计算公钥
    const pk_from_sk = sk.public();

    // 打包两个公钥并比较
    const pk_bytes1 = pk.toBytes();
    const pk_bytes2 = pk_from_sk.toBytes();

    try testing.expectEqualSlices(u8, &pk_bytes1, &pk_bytes2);
}

// 用于签名和验证的参数化测试辅助函数
fn testSignAndVerify(comptime MlDsa: type, seed: [32]u8, message: []const u8) !void {
    const result = MlDsa.newKeyFromSeed(&seed);
    const kp = try MlDsa.KeyPair.fromSecretKey(result.sk);

    // 对消息签名
    const sig = try kp.sign(message, null);

    // 验证签名
    try sig.verify(message, kp.public_key);
}

test "Sign and verify - all variants" {
    inline for (.{
        .{ .variant = MLDSA44, .seed_byte = 0x44, .message = "Hello, ML-DSA-44!" },
        .{ .variant = MLDSA65, .seed_byte = 0x65, .message = "Hello, ML-DSA-65!" },
        .{ .variant = MLDSA87, .seed_byte = 0x87, .message = "Hello, ML-DSA-87!" },
    }) |config| {
        const seed: [32]u8 = @splat(config.seed_byte);
        try testSignAndVerify(config.variant, seed, config.message);
    }
}

test "Invalid signature rejection" {
    const seed: [32]u8 = @splat(0x99);
    const result = MLDSA44.newKeyFromSeed(&seed);
    const kp = try MLDSA44.KeyPair.fromSecretKey(result.sk);

    const message = "Original message";

    // 对消息签名
    const sig = try kp.sign(message, null);

    // 使用错误消息进行验证应失败
    const wrong_message = "Modified message";
    try testing.expectError(error.SignatureVerificationFailed, sig.verify(wrong_message, kp.public_key));

    // 修改签名后,验证应当失败
    var corrupted_sig_bytes = sig.toBytes();
    corrupted_sig_bytes[0] ^= 0xFF;
    const corrupted_sig = try MLDSA44.Signature.fromBytes(corrupted_sig_bytes);
    try testing.expectError(error.SignatureVerificationFailed, corrupted_sig.verify(message, kp.public_key));
}

test "Context string support" {
    const seed: [32]u8 = @splat(0xAA);
    const result = MLDSA44.newKeyFromSeed(&seed);
    const kp = try MLDSA44.KeyPair.fromSecretKey(result.sk);

    const message = "Test message";
    const context1 = "context1";
    const context2 = "context2";

    // 使用 context1 签名
    const sig1 = try kp.signWithContext(message, null, context1);

    // 使用正确上下文进行验证应成功
    try sig1.verifyWithContext(message, kp.public_key, context1);

    // 使用错误的上下文验证应当失败
    try testing.expectError(error.SignatureVerificationFailed, sig1.verifyWithContext(message, kp.public_key, context2));

    // 使用空上下文验证应失败
    try testing.expectError(error.SignatureVerificationFailed, sig1.verify(message, kp.public_key));

    // 使用空上下文签名
    const sig2 = try kp.sign(message, null);

    // 使用空上下文验证应当成功
    try sig2.verify(message, kp.public_key);

    // 使用非空上下文进行验证应失败
    try testing.expectError(error.SignatureVerificationFailed, sig2.verifyWithContext(message, kp.public_key, context1));

    // 测试最大上下文长度(255 字节)
    const max_context: [255]u8 = @splat(0xBB);
    const sig3 = try kp.signWithContext(message, null, &max_context);
    try sig3.verifyWithContext(message, kp.public_key, &max_context);

    // 测试上下文过长的情况(256 字节应失败)
    const too_long_context: [256]u8 = @splat(0xCC);
    try testing.expectError(error.ContextTooLong, kp.signWithContext(message, null, &too_long_context));
}

test "Context string with streaming API" {
    const seed: [32]u8 = @splat(0xDD);
    const result = MLDSA44.newKeyFromSeed(&seed);
    const kp = try MLDSA44.KeyPair.fromSecretKey(result.sk);

    const context = "streaming-context";
    const message_part1 = "Hello, ";
    const message_part2 = "World!";

    // 使用带上下文的流式 API 签名
    var signer = try kp.signerWithContext(null, context);
    signer.update(message_part1);
    signer.update(message_part2);
    const sig = signer.finalize();

    // 使用带上下文的流式 API 验证
    var verifier = try sig.verifierWithContext(kp.public_key, context);
    verifier.update(message_part1);
    verifier.update(message_part2);
    try verifier.verify();

    // 使用错误的上下文验证应当失败
    var verifier_wrong = try sig.verifierWithContext(kp.public_key, "wrong");
    verifier_wrong.update(message_part1);
    verifier_wrong.update(message_part2);
    try testing.expectError(error.SignatureVerificationFailed, verifier_wrong.verify());
}

test "Signature determinism (same rnd)" {
    const seed: [32]u8 = @splat(0x11);
    const result = MLDSA44.newKeyFromSeed(&seed);
    const sk = result.sk;

    const message = "Deterministic test";
    const rnd: [32]u8 = @splat(0x22);

    // 使用流式 API,以相同随机性签名两次
    var st1 = try sk.signer(rnd);
    st1.update(message);
    const sig1 = st1.finalize();

    var st2 = try sk.signer(rnd);
    st2.update(message);
    const sig2 = st2.finalize();

    // 签名应当相同
    try testing.expectEqualSlices(u8, &sig1.toBytes(), &sig2.toBytes());
}

test "Signature toBytes/fromBytes roundtrip" {
    const seed: [32]u8 = @splat(0x33);
    const result = MLDSA44.newKeyFromSeed(&seed);
    const kp = try MLDSA44.KeyPair.fromSecretKey(result.sk);

    const message = "toBytes/fromBytes test";

    // 对消息签名
    const sig = try kp.sign(message, null);
    const sig_bytes = sig.toBytes();

    // 解包后重新打包
    const sig_reparsed = try MLDSA44.Signature.fromBytes(sig_bytes);

    const repacked = sig_reparsed.toBytes();

    // 应与原始值匹配
    try testing.expectEqualSlices(u8, &sig_bytes, &repacked);
}

test "Empty message signing" {
    const seed: [32]u8 = @splat(0x44);
    const result = MLDSA44.newKeyFromSeed(&seed);
    const kp = try MLDSA44.KeyPair.fromSecretKey(result.sk);

    const message = "";

    // 签名空消息
    const sig = try kp.sign(message, null);

    // 验证应成功
    try sig.verify(message, kp.public_key);
}

test "Long message signing" {
    const seed: [32]u8 = @splat(0x55);
    const result = MLDSA44.newKeyFromSeed(&seed);
    const kp = try MLDSA44.KeyPair.fromSecretKey(result.sk);

    // 创建长消息(1KB)
    const long_message: [1024]u8 = @splat(0xAB);

    // 签署长消息
    const sig = try kp.sign(&long_message, null);

    // 验证应成功
    try sig.verify(&long_message, kp.public_key);
}

// 将十六进制字符串解码为字节的辅助函数
fn hexToBytes(comptime hex: []const u8, out: []u8) !void {
    if (hex.len != out.len * 2) return error.InvalidLength;

    var i: usize = 0;
    while (i < out.len) : (i += 1) {
        const hi = try std.fmt.charToDigit(hex[i * 2], 16);
        const lo = try std.fmt.charToDigit(hex[i * 2 + 1], 16);
        out[i] = (hi << 4) | lo;
    }
}

test "ML-DSA-44 KAT test vector 0" {
    // 来自 NIST ML-DSA KAT 的测试向量(count = 0)。
    // xi 是密钥生成的种子(算法 1,第 1 行)。
    const xi_hex = "f696484048ec21f96cf50a56d0759c448f3779752f0383d37449690694cf7a68";
    const pk_hex_start = "bd4e96f9a038ab5e36214fe69c0b1cb835ef9d7c8417e76aecd152f5cddebec8";
    const msg_hex = "6dbbc4375136df3b07f7c70e639e223e";

    // 解析 xi(用于密钥生成的 32 字节种子)
    var xi: [32]u8 = undefined;
    try hexToBytes(xi_hex, &xi);

    // 从 xi 生成密钥
    const result = MLDSA44.newKeyFromSeed(&xi);
    const pk = result.pk;
    const sk = result.sk;

    // 验证公钥以预期字节开头
    const pk_bytes = pk.toBytes();

    var expected_pk_start: [32]u8 = undefined;
    try hexToBytes(pk_hex_start, &expected_pk_start);

    // 检查公钥的前 32 字节是否匹配
    try testing.expectEqualSlices(u8, &expected_pk_start, pk_bytes[0..32]);

    // 解析消息
    var msg: [16]u8 = undefined;
    try hexToBytes(msg_hex, &msg);

    // 对消息签名(采用固定随机值的确定性模式)。
    const kp = try MLDSA44.KeyPair.fromSecretKey(sk);
    const sig = try kp.sign(&msg, null);

    // 验证签名
    try sig.verify(&msg, kp.public_key);
}

test "ML-DSA-65 KAT test vector 0" {
    // 来自 NIST ML-DSA KAT 的测试向量(count = 0)。
    // xi 是密钥生成的种子(算法 1,第 1 行)。
    const xi_hex = "f696484048ec21f96cf50a56d0759c448f3779752f0383d37449690694cf7a68";
    const pk_hex_start = "e50d03fff3b3a70961abbb92a390008dec1283f603f50cdbaaa3d00bd659bc76";
    const msg_hex = "6dbbc4375136df3b07f7c70e639e223e";

    // 解析 xi(用于密钥生成的 32 字节种子)
    var xi: [32]u8 = undefined;
    try hexToBytes(xi_hex, &xi);

    // 从 xi 生成密钥
    const result = MLDSA65.newKeyFromSeed(&xi);
    const pk = result.pk;
    const sk = result.sk;

    // 验证公钥以预期字节开头
    const pk_bytes = pk.toBytes();

    var expected_pk_start: [32]u8 = undefined;
    try hexToBytes(pk_hex_start, &expected_pk_start);

    // 检查公钥的前 32 字节是否匹配
    try testing.expectEqualSlices(u8, &expected_pk_start, pk_bytes[0..32]);

    // 解析消息
    var msg: [16]u8 = undefined;
    try hexToBytes(msg_hex, &msg);

    // 对消息签名
    const kp = try MLDSA65.KeyPair.fromSecretKey(sk);
    const sig = try kp.sign(&msg, null);

    // 验证签名
    try sig.verify(&msg, kp.public_key);
}

test "ML-DSA-87 KAT test vector 0" {
    // 来自 NIST ML-DSA KAT 的测试向量(count = 0)。
    // xi 是密钥生成的种子(算法 1,第 1 行)。
    const xi_hex = "f696484048ec21f96cf50a56d0759c448f3779752f0383d37449690694cf7a68";
    const pk_hex_start = "bc89b367d4288f47c71a74679d0fcffbe041de41b5da2f5fc66d8e28c5899494";
    const msg_hex = "6dbbc4375136df3b07f7c70e639e223e";

    // 解析 xi(用于密钥生成的 32 字节种子)
    var xi: [32]u8 = undefined;
    try hexToBytes(xi_hex, &xi);

    // 从 xi 生成密钥
    const result = MLDSA87.newKeyFromSeed(&xi);
    const pk = result.pk;
    const sk = result.sk;

    // 验证公钥以预期字节开头
    const pk_bytes = pk.toBytes();

    var expected_pk_start: [32]u8 = undefined;
    try hexToBytes(pk_hex_start, &expected_pk_start);

    // 检查公钥的前 32 字节是否匹配
    try testing.expectEqualSlices(u8, &expected_pk_start, pk_bytes[0..32]);

    // 解析消息
    var msg: [16]u8 = undefined;
    try hexToBytes(msg_hex, &msg);

    // 对消息签名
    const kp = try MLDSA87.KeyPair.fromSecretKey(sk);
    const sig = try kp.sign(&msg, null);

    // 验证签名
    try sig.verify(&msg, kp.public_key);
}

test "KeyPair API - generate and sign" {
    const io = std.testing.io;
    // 使用随机生成测试新的 KeyPair API。
    const kp = MLDSA44.KeyPair.generate(io);
    const msg = "Test message for KeyPair API";

    // 使用确定性模式签名(无噪声)
    const sig = try kp.sign(msg, null);

    // 使用 Signature.verify API 进行验证
    try sig.verify(msg, kp.public_key);
}

test "KeyPair API - generateDeterministic" {
    // 测试确定性密钥生成
    const seed: [32]u8 = @splat(42);
    const kp1 = try MLDSA44.KeyPair.generateDeterministic(seed);
    const kp2 = try MLDSA44.KeyPair.generateDeterministic(seed);

    // 相同种子应生成相同密钥
    const pk1_bytes = kp1.public_key.toBytes();
    const pk2_bytes = kp2.public_key.toBytes();
    try testing.expectEqualSlices(u8, &pk1_bytes, &pk2_bytes);
}

test "KeyPair API - fromSecretKey" {
    const io = std.testing.io;
    // 生成密钥对
    const kp1 = MLDSA44.KeyPair.generate(io);

    // 从秘密密钥派生公钥
    const kp2 = try MLDSA44.KeyPair.fromSecretKey(kp1.secret_key);

    // 公钥应匹配
    const pk1_bytes = kp1.public_key.toBytes();
    const pk2_bytes = kp2.public_key.toBytes();
    try testing.expectEqualSlices(u8, &pk1_bytes, &pk2_bytes);
}

test "Signature verification with noise" {
    const io = std.testing.io;
    // 测试带随机性的签名(对冲签名)。
    const kp = MLDSA65.KeyPair.generate(io);
    const msg = "Message to be signed with randomness";

    // 生成一些噪声
    const noise = [_]u8{ 1, 2, 3, 4, 5 } ++ @as([27]u8, @splat(0));

    // 带噪声签名
    const sig = try kp.sign(msg, noise);

    // 验证仍应有效
    try sig.verify(msg, kp.public_key);
}

test "Signature verification failure" {
    const io = std.testing.io;
    // 测试是否拒绝无效签名
    const kp = MLDSA44.KeyPair.generate(io);
    const msg = "Original message";
    const sig = try kp.sign(msg, null);

    // 使用错误消息进行验证应失败
    const wrong_msg = "Different message";
    try testing.expectError(error.SignatureVerificationFailed, sig.verify(wrong_msg, kp.public_key));
}

test "Streaming API - sign and verify" {
    const seed: [32]u8 = @splat(0x55);
    const kp = try MLDSA44.KeyPair.generateDeterministic(seed);

    const msg = "Test message for streaming API";

    // 使用流式 API 签名
    var signer = try kp.signer(null);
    signer.update(msg);
    const sig = signer.finalize();

    // 使用流式 API 验证
    var verifier = try sig.verifier(kp.public_key);
    verifier.update(msg);
    try verifier.verify();
}

test "Streaming API - chunked message" {
    const seed: [32]u8 = @splat(0x66);
    const kp = try MLDSA44.KeyPair.generateDeterministic(seed);

    // 分块创建消息
    const chunk1 = "Hello, ";
    const chunk2 = "streaming ";
    const chunk3 = "world!";
    const full_msg = chunk1 ++ chunk2 ++ chunk3;

    // 分块签名
    var signer = try kp.signer(null);
    signer.update(chunk1);
    signer.update(chunk2);
    signer.update(chunk3);
    const sig_chunked = signer.finalize();

    // 使用完整消息签名以进行比较
    var signer2 = try kp.signer(null);
    signer2.update(full_msg);
    const sig_full = signer2.finalize();

    // 签名应当相同
    try testing.expectEqualSlices(u8, &sig_chunked.toBytes(), &sig_full.toBytes());

    // 分块验证
    const sig = sig_chunked;
    var verifier = try sig.verifier(kp.public_key);
    verifier.update(chunk1);
    verifier.update(chunk2);
    verifier.update(chunk3);
    try verifier.verify();
}

test "Streaming API - large message" {
    const seed: [32]u8 = @splat(0x77);
    const kp = try MLDSA44.KeyPair.generateDeterministic(seed);

    // 创建大消息(1MB)
    const chunk_size = 4096;
    const num_chunks = 256;
    var chunk: [chunk_size]u8 = undefined;
    for (0..chunk_size) |i| {
        chunk[i] = @intCast(i % 256);
    }

    // 流式签名
    var signer = try kp.signer(null);
    for (0..num_chunks) |_| {
        signer.update(&chunk);
    }
    const sig = signer.finalize();

    // 验证流式处理
    var verifier = try sig.verifier(kp.public_key);
    for (0..num_chunks) |_| {
        verifier.update(&chunk);
    }
    try verifier.verify();
}

test "Streaming API - all parameter sets" {
    const test_msg = "Streaming test for all ML-DSA parameter sets";

    // ML-DSA-44
    {
        const seed: [32]u8 = @splat(0x44);
        const kp = try MLDSA44.KeyPair.generateDeterministic(seed);
        var signer = try kp.signer(null);
        signer.update(test_msg);
        const sig = signer.finalize();
        var verifier = try sig.verifier(kp.public_key);
        verifier.update(test_msg);
        try verifier.verify();
    }

    // ML-DSA-65
    {
        const seed: [32]u8 = @splat(0x65);
        const kp = try MLDSA65.KeyPair.generateDeterministic(seed);
        var signer = try kp.signer(null);
        signer.update(test_msg);
        const sig = signer.finalize();
        var verifier = try sig.verifier(kp.public_key);
        verifier.update(test_msg);
        try verifier.verify();
    }

    // ML-DSA-87 算法
    {
        const seed: [32]u8 = @splat(0x87);
        const kp = try MLDSA87.KeyPair.generateDeterministic(seed);
        var signer = try kp.signer(null);
        signer.update(test_msg);
        const sig = signer.finalize();
        var verifier = try sig.verifier(kp.public_key);
        verifier.update(test_msg);
        try verifier.verify();
    }
}

/// 扩展欧几里得算法。
/// 仅用于编译期值;重视正确性,不重视性能。
fn extendedEuclidean(comptime T: type, comptime a_: T, comptime b_: T) struct { gcd: T, x: T, y: T } {
    var a = a_;
    var b = b_;
    var x0: T = 1;
    var x1: T = 0;
    var y0: T = 0;
    var y1: T = 1;

    while (b != 0) {
        const q = @divTrunc(a, b);
        const temp_a = a;
        a = b;
        b = temp_a - q * b;

        const temp_x = x0;
        x0 = x1;
        x1 = temp_x - q * x1;

        const temp_y = y0;
        y0 = y1;
        y1 = temp_y - q * y1;
    }

    return .{ .gcd = a, .x = x0, .y = y0 };
}

/// 模逆:计算 a^(-1) mod p
/// 要求 gcd(a,p) = 1。结果规范化到范围 [0, p)。
fn modularInverse(comptime T: type, comptime a: T, comptime p: T) T {
    // 使用有符号类型计算 EEA
    const type_info = @typeInfo(T);
    const SignedT = if (type_info == .int and type_info.int.signedness == .unsigned)
        @Int(.signed, type_info.int.bits)
    else
        T;

    const a_signed = @as(SignedT, @intCast(a));
    const p_signed = @as(SignedT, @intCast(p));

    const r = extendedEuclidean(SignedT, a_signed, p_signed);
    assert(r.gcd == 1);

    // 将结果规范化至 [0, p)
    var result = r.x;
    while (result < 0) {
        result += p_signed;
    }

    return @intCast(result);
}

/// 模幂:使用平方乘算法计算 a^s mod p。
fn modularPow(comptime T: type, comptime a: T, s: T, comptime p: T) T {
    const type_info = @typeInfo(T);
    const bits = type_info.int.bits;
    const WideT = @Int(.unsigned, bits * 2);

    var ret: T = 1;
    var base: T = a;
    var exp = s;

    while (exp > 0) {
        if (exp & 1 == 1) {
            ret = @intCast((@as(WideT, ret) * @as(WideT, base)) % p);
        }
        base = @intCast((@as(WideT, base) * @as(WideT, base)) % p);
        exp >>= 1;
    }

    return ret;
}

/// 根据单个位值创建全一或全零掩码。
/// 若 bit == 1,则返回全一(0xFF...FF);若 bit == 0,则返回全零。
fn bitMask(comptime T: type, bit: T) T {
    const type_info = @typeInfo(T);
    if (type_info != .int or type_info.int.signedness != .unsigned) {
        @compileError("bitMask requires an unsigned integer type");
    }
    return -%bit;
}

/// 由有符号整数的符号位创建掩码。
/// x < 0 时返回全 1(0xFF...FF),x >= 0 时返回全 0。
fn signMask(comptime T: type, x: T) @Int(.unsigned, @typeInfo(T).int.bits) {
    const type_info = @typeInfo(T);
    if (type_info != .int) {
        @compileError("signMask requires an integer type");
    }

    const bits = type_info.int.bits;
    const SignedT = @Int(.signed, bits);

    // 必要时转换为有符号类型,通过算术右移传播符号位
    const x_signed: SignedT = if (type_info.int.signedness == .signed) x else @bitCast(x);
    const shifted = x_signed >> (bits - 1);
    return @bitCast(shifted);
}

/// 蒙哥马利约减:对于输入 x,返回满足 y ≡ x*R^(-1) (mod q) 的 y。
/// 此通用实现由模数 q、其逆元 qInv、
/// 蒙哥马利常量 R 及结果边界参数化。
///
/// 对于 ML-DSA:R = 2^32,返回 y < 2q。
/// 对于 ML-KEM:R = 2^16,返回范围为 (-q, q) 的 y。
fn montgomeryReduce(
    comptime InT: type,
    comptime OutT: type,
    comptime q: comptime_int,
    comptime qInv: comptime_int,
    comptime r_bits: comptime_int,
    x: InT,
) OutT {
    const mask = (@as(InT, 1) << r_bits) - 1;
    const m_full = (x *% qInv) & mask;
    const m: OutT = @truncate(m_full);

    const yR = x -% @as(InT, m) * @as(InT, q);
    const y_shifted = @as(@Int(.unsigned, @typeInfo(InT).Int.bits), @bitCast(yR)) >> r_bits;
    return @bitCast(@as(@Int(.unsigned, @typeInfo(OutT).Int.bits), @truncate(y_shifted)));
}

/// 使用 SHAKE-128 和拒绝采样进行均匀采样。
/// 通过拒绝采样,从 [0, q) 中均匀采样多项式系数。
///
/// 参数:
/// - PolyType:要返回的多项式类型
/// - q:模数
/// - bits_per_coef:每个系数的位数,12 或 23
/// - n:系数数量
/// - seed:随机种子
/// - domain_sep:域分离字节,追加到种子之后
fn sampleUniformRejection(
    comptime PolyType: type,
    comptime q: comptime_int,
    comptime bits_per_coef: comptime_int,
    comptime n: comptime_int,
    seed: []const u8,
    domain_sep: []const u8,
) PolyType {
    var h = sha3.Shake128.init(.{});
    h.update(seed);
    h.update(domain_sep);

    const buf_len = sha3.Shake128.block_length; // 168 字节
    var buf: [buf_len]u8 = undefined;

    var ret: PolyType = undefined;
    var coef_idx: usize = 0;

    if (bits_per_coef == 12) {
        // ML-KEM 路径:每 3 字节打包 2 个系数(各 12 位)
        outer: while (true) {
            h.squeeze(&buf);

            var j: usize = 0;
            while (j < buf_len) : (j += 3) {
                const b0 = @as(u16, buf[j]);
                const b1 = @as(u16, buf[j + 1]);
                const b2 = @as(u16, buf[j + 2]);

                const ts: [2]u16 = .{
                    b0 | ((b1 & 0xf) << 8),
                    (b1 >> 4) | (b2 << 4),
                };

                inline for (ts) |t| {
                    if (t < q) {
                        ret.cs[coef_idx] = @intCast(t);
                        coef_idx += 1;
                        if (coef_idx == n) break :outer;
                    }
                }
            }
        }
    } else if (bits_per_coef == 23) {
        // ML-DSA 路径:每 3 字节存储 1 个系数(23 位)
        while (coef_idx < n) {
            h.squeeze(&buf);

            var j: usize = 0;
            while (j < buf_len and coef_idx < n) : (j += 3) {
                const t = (@as(u32, buf[j]) |
                    (@as(u32, buf[j + 1]) << 8) |
                    (@as(u32, buf[j + 2]) << 16)) & 0x7fffff;

                if (t < q) {
                    ret.cs[coef_idx] = @intCast(t);
                    coef_idx += 1;
                }
            }
        }
    } else {
        @compileError("bits_per_coef must be 12 or 23");
    }

    return ret;
}

test "bitMask and signMask helpers" {
    try testing.expectEqual(@as(u32, 0x00000000), bitMask(u32, 0));
    try testing.expectEqual(@as(u32, 0xFFFFFFFF), bitMask(u32, 1));
    try testing.expectEqual(@as(u8, 0x00), bitMask(u8, 0));
    try testing.expectEqual(@as(u8, 0xFF), bitMask(u8, 1));
    try testing.expectEqual(@as(u64, 0x0000000000000000), bitMask(u64, 0));
    try testing.expectEqual(@as(u64, 0xFFFFFFFFFFFFFFFF), bitMask(u64, 1));

    try testing.expectEqual(@as(u32, 0xFFFFFFFF), signMask(i32, -1));
    try testing.expectEqual(@as(u32, 0xFFFFFFFF), signMask(i32, -100));
    try testing.expectEqual(@as(u32, 0x00000000), signMask(i32, 0));
    try testing.expectEqual(@as(u32, 0x00000000), signMask(i32, 1));
    try testing.expectEqual(@as(u32, 0x00000000), signMask(i32, 100));

    try testing.expectEqual(@as(u32, 0xFFFFFFFF), signMask(u32, 0x80000000)); // 最高有效位已设置
    try testing.expectEqual(@as(u32, 0x00000000), signMask(u32, 0x7FFFFFFF)); // 最高有效位清零
}