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 位安全性)
stdbuiltintestingassertcryptoerrorsmathmemsha3ContextTooLongErrorEncodingErrorSignatureVerificationErrorMLDSA44MLDSA65MLDSA87NQQ_BITSDRQ_INVR_OVER_256ZETAParamsPolyPolyVecMatdotHatle2QmodQle2qModQmontReduceLe2QzetascomputeZetasinv_zetascomputeInvZetastoMontpower2RounddecomposemakeHintuseHintpolyMakeHintpolyUseHintpolyPackLeqEtapolyUnpackLeqEtapolyPackT1polyUnpackT1polyPackT0polyUnpackT0centeredToPositivepolyPackLeGamma1polyUnpackLeGamma1polyPackW1polyDeriveUniformexpandSsampleInBallexpandMaskMLDSAImpltestKeyGenerationBasictestSignAndVerifyhexToBytesextendedEuclideanmodularInversemodularPowbitMasksignMaskmontgomeryReducesampleUniformRejection
std.crypto.ml_dsa.assert
别名
别名目标 std.debug.assert
std.crypto.ml_dsa.bitMask
函数
根据单个位值创建全一或全零掩码。 若 bit == 1,则返回全一(0xFF...FF);若 bit == 0,则返回全零。
fn bitMask(comptime T: type, bit: T) T
参数
T: type
bit: T
std.crypto.ml_dsa.builtin
常量
std.crypto.ml_dsa.centeredToPositive
函数
将系数从中心化表示转换为非负表示。 将值从 [0,γ₁] ∪ (Q-γ₁, Q) 变换到 [0, 2γ₁)。
fn centeredToPositive(val: u32, comptime gamma1: u32) u32
参数
val: u32
gamma1: u32
std.crypto.ml_dsa.computeInvZetas
函数
fn computeInvZetas() [N]u32
std.crypto.ml_dsa.computeZetas
函数
fn computeZetas() [N]u32
std.crypto.ml_dsa.ContextTooLongError
别名
std.crypto.ml_dsa.crypto
别名
别名目标 std.crypto
std.crypto.ml_dsa.D
常量
u32
std.crypto.ml_dsa.decompose
类型函数
将 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
函数
fn dotHat(comptime len: u8, a: PolyVec(len), b: PolyVec(len)) Poly
参数
std.crypto.ml_dsa.EncodingError
别名
std.crypto.ml_dsa.errors
别名
别名目标 std.crypto.errors
std.crypto.ml_dsa.expandMask
函数
采样多项式,其系数在 (-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
函数
使用给定种子和 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
类型函数
扩展欧几里得算法。 仅用于编译期值;重视正确性,不重视性能。
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
函数
fn hexToBytes(comptime hex: []const u8, out: []u8) !void
参数
hex: []const u8
out: []u8
std.crypto.ml_dsa.inv_zetas
常量
std.crypto.ml_dsa.le2Q
函数
fn le2Q(x: u32) u32
参数
x: u32
std.crypto.ml_dsa.le2qModQ
函数
fn le2qModQ(x: u32) u32
参数
x: u32
std.crypto.ml_dsa.makeHint
函数
创建提示位,帮助在小幅扰动后恢复高位。 给定:
- 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
类型函数
fn Mat(comptime k: u8, comptime l: u8) type
参数
k: u8
l: u8
字段
rows: [k]PolyVec(l)
std.crypto.ml_dsa.Mat.derive
函数
使用 SHAKE-128 从种子 rho 展开矩阵 A。 这是 FIPS 204 中的 ExpandA 函数。
fn derive(rho: *const [32]u8) Self
参数
rho: *const [32]u8
std.crypto.ml_dsa.Mat.mulVec
函数
在 NTT 域中将矩阵与向量相乘,并以普通域返回结果。 接受 NTT 形式的向量,返回普通形式的乘积。
fn mulVec(self: Self, v_hat: VecL) VecK
参数
std.crypto.ml_dsa.Mat.mulVecHat
函数
在 NTT 域中计算矩阵与向量的乘积,并返回 NTT 域中的结果。 接受 NTT 形式的向量,返回 NTT 形式的乘积。
fn mulVecHat(self: Self, v_hat: VecL) VecK
参数
std.crypto.ml_dsa.Mat.Self
别名
std.crypto.ml_dsa.Mat.VecK
类型
std.crypto.ml_dsa.Mat.VecL
类型
std.crypto.ml_dsa.math
别名
别名目标 std.math
std.crypto.ml_dsa.mem
别名
别名目标 std.mem
std.crypto.ml_dsa.MLDSA44
类型
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
类型
NIST FIPS 204 规定的 ML-DSA-65, 即基于模格的数字签名算法的 65 参数集。
这是一种后量子签名方案,提供 NIST 安全类别 3, 大致相当于 SHA-384 或 AES-192 的安全性。
密钥大小:
- 公钥:1952 字节
- 私钥:4032 字节
- 签名:3309 字节
此参数集以更大的密钥和签名 换取比 ML-DSA-44 更高的安全性。
std.crypto.ml_dsa.MLDSA87
类型
NIST FIPS 204 规定的 ML-DSA-87,即基于模格的数字签名算法的 87 参数集。
这是一种后量子签名方案,提供 NIST 安全类别 5,大致相当于 SHA-512 或 AES-256 的安全性。
密钥大小:
- 公钥:2592 字节
- 私钥:4896 字节
- 签名:4627 字节
此参数集在三种 ML-DSA 变体中提供最高安全级别,适用于需要最高安全保证的应用。
std.crypto.ml_dsa.MLDSAImpl
类型函数
fn MLDSAImpl(comptime p: Params) type
参数
p: Params
paramsnamegamma1betaalphaSelfPolyVecLPolyVecKMatKxLseed_lengthnoise_lengthpublic_key_bytesprivate_key_bytessignature_bytespolyLeqEtaPackedSizepolyLeGamma1PackedSizepolyT1PackedSizepolyT0PackedSizepolyW1PackedSizecrhcomputeTPublicKeySecretKeynewKeyFromSeedSignatureSignerVerifierKeyPair
std.crypto.ml_dsa.MLDSAImpl.alpha
常量
u32
std.crypto.ml_dsa.MLDSAImpl.beta
常量
u32
std.crypto.ml_dsa.MLDSAImpl.computeT
函数
计算 t = As1 + s2 的辅助函数。 用于密钥生成和公钥重建。
fn computeT(A: MatKxL, s1_hat: PolyVecL, s2: PolyVecK) PolyVecK
参数
std.crypto.ml_dsa.MLDSAImpl.crh
函数
使用 SHAKE-256 计算 CRH(抗碰撞哈希)的辅助函数。 统一封装哈希操作中重复出现的 init-update-squeeze 模式。
fn crh(comptime outsize: usize, inputs: anytype) [outsize]u8
参数
outsize: usize
std.crypto.ml_dsa.MLDSAImpl.gamma1
常量
u32
std.crypto.ml_dsa.MLDSAImpl.KeyPair
容器
由私钥及其对应公钥组成的密钥对。
字段
std.crypto.ml_dsa.MLDSAImpl.KeyPair.fromSecretKey
函数
从已有私钥派生公钥。 从私钥重新计算公钥的各个部分。
pub fn fromSecretKey(sk: SecretKey) !KeyPair
参数
sk: SecretKey
std.crypto.ml_dsa.MLDSAImpl.KeyPair.generate
函数
生成新的随机密钥对。
pub fn generate(io: std.Io) KeyPair
参数
std.crypto.ml_dsa.MLDSAImpl.KeyPair.generateDeterministic
函数
根据种子确定性地生成密钥对。 用于测试或要求可重现性的场景。 种子应使用密码学安全的随机源生成。
pub fn generateDeterministic(seed: [32]u8) !KeyPair
参数
seed: [32]u8
std.crypto.ml_dsa.MLDSAImpl.KeyPair.seed_length
别名
创建密钥对所需种子的长度(字节)。
std.crypto.ml_dsa.MLDSAImpl.KeyPair.sign
函数
使用此密钥对对消息签名。 noise 参数可以为 null,以生成确定性签名; 也可提供随机性以生成对冲签名(建议用于抵御故障攻击)。
pub fn sign( kp: KeyPair, msg: []const u8, noise: ?[noise_length]u8, ) !Signature
参数
std.crypto.ml_dsa.MLDSAImpl.KeyPair.signer
函数
创建 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
函数
创建 Signer,用于对带上下文的消息增量签名。 noise 参数可为 null,以生成确定性签名; 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。 context 参数为可选的上下文字符串(最多 255 字节)。
pub fn signerWithContext(self: *const KeyPair, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer
参数
错误
- ContextTooLong ContextTooLongError
std.crypto.ml_dsa.MLDSAImpl.KeyPair.signWithContext
函数
使用此密钥对,对带上下文的消息签名。 noise 参数可为 null,以生成确定性签名; 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。 context 参数为可选的上下文字符串(最多 255 字节)。
pub fn signWithContext( kp: KeyPair, msg: []const u8, noise: ?[noise_length]u8, context: []const u8, ) ContextTooLongError!Signature
参数
错误
- ContextTooLong ContextTooLongError
std.crypto.ml_dsa.MLDSAImpl.MatKxL
类型
std.crypto.ml_dsa.MLDSAImpl.name
常量
std.crypto.ml_dsa.MLDSAImpl.newKeyFromSeed
类型函数
由种子生成新密钥对(确定性)
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
常量
用于非确定性签名的可选随机字节长度(单位为字节)。
std.crypto.ml_dsa.MLDSAImpl.params
常量
std.crypto.ml_dsa.MLDSAImpl.polyLeGamma1PackedSize
函数
fn polyLeGamma1PackedSize() usize
std.crypto.ml_dsa.MLDSAImpl.polyLeqEtaPackedSize
函数
fn polyLeqEtaPackedSize() usize
std.crypto.ml_dsa.MLDSAImpl.polyT0PackedSize
函数
fn polyT0PackedSize() usize
std.crypto.ml_dsa.MLDSAImpl.polyT1PackedSize
函数
fn polyT1PackedSize() usize
std.crypto.ml_dsa.MLDSAImpl.PolyVecK
类型
std.crypto.ml_dsa.MLDSAImpl.PolyVecL
类型
std.crypto.ml_dsa.MLDSAImpl.polyW1PackedSize
函数
fn polyW1PackedSize() usize
std.crypto.ml_dsa.MLDSAImpl.private_key_bytes
常量
编码后秘密密钥的字节大小。
usize
std.crypto.ml_dsa.MLDSAImpl.public_key_bytes
常量
已编码公钥的大小,单位为字节。
usize
std.crypto.ml_dsa.MLDSAImpl.PublicKey
容器
ML-DSA 公钥
字段
std.crypto.ml_dsa.MLDSAImpl.PublicKey.encoded_length
常量
编码后的公钥大小,单位为字节
usize
std.crypto.ml_dsa.MLDSAImpl.PublicKey.fromBytes
函数
从字节解码公钥
pub fn fromBytes(bytes: [encoded_length]u8) !PublicKey
参数
bytes: [encoded_length]u8
std.crypto.ml_dsa.MLDSAImpl.PublicKey.toBytes
函数
将公钥编码为字节
pub fn toBytes(self: PublicKey) [encoded_length]u8
参数
self: PublicKey
std.crypto.ml_dsa.MLDSAImpl.SecretKey
容器
ML-DSA 秘密密钥
字段
std.crypto.ml_dsa.MLDSAImpl.SecretKey.encoded_length
常量
已编码私钥的大小,单位为字节
usize
std.crypto.ml_dsa.MLDSAImpl.SecretKey.fromBytes
函数
从字节解码秘密密钥
pub fn fromBytes(bytes: [encoded_length]u8) !SecretKey
参数
bytes: [encoded_length]u8
std.crypto.ml_dsa.MLDSAImpl.SecretKey.public
函数
从此私钥计算公钥
pub fn public(self: *const SecretKey) PublicKey
参数
self: *const SecretKey
std.crypto.ml_dsa.MLDSAImpl.SecretKey.signer
函数
创建 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
函数
创建 Signer,用于对带上下文的消息增量签名。 noise 参数可为 null,以生成确定性签名; 也可提供随机性以生成对冲签名(建议用于抵抗故障攻击)。 context 参数为可选的上下文字符串(最多 255 字节)。
pub fn signerWithContext(self: *const SecretKey, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer
参数
错误
- ContextTooLong ContextTooLongError
std.crypto.ml_dsa.MLDSAImpl.SecretKey.toBytes
函数
将秘密密钥编码为字节
pub fn toBytes(self: SecretKey) [encoded_length]u8
参数
self: SecretKey
std.crypto.ml_dsa.MLDSAImpl.seed_length
常量
用于确定性密钥生成的种子长度(32 字节)。
usize
std.crypto.ml_dsa.MLDSAImpl.Self
别名
std.crypto.ml_dsa.MLDSAImpl.Signature
容器
ML-DSA 签名
字段
std.crypto.ml_dsa.MLDSAImpl.signature_bytes
常量
已编码签名的大小,单位为字节。
usize
std.crypto.ml_dsa.MLDSAImpl.Signature.encoded_length
常量
编码后签名的字节大小
usize
std.crypto.ml_dsa.MLDSAImpl.Signature.fromBytes
函数
从字节解码签名
pub fn fromBytes(bytes: [encoded_length]u8) EncodingError!Signature
参数
bytes: [encoded_length]u8
错误
- InvalidEncoding EncodingError
std.crypto.ml_dsa.MLDSAImpl.Signature.toBytes
函数
将签名编码为字节
pub fn toBytes(self: Signature) [encoded_length]u8
参数
self: Signature
std.crypto.ml_dsa.MLDSAImpl.Signature.verifier
函数
创建用于增量验证签名的 Verifier。
pub fn verifier(self: Signature, public_key: PublicKey) !Verifier
参数
std.crypto.ml_dsa.MLDSAImpl.Signature.verifierWithContext
函数
创建 Verifier,用于带上下文的增量签名验证。 context 参数是可选的上下文字符串(最多 255 字节)。
pub fn verifierWithContext(self: Signature, public_key: PublicKey, context: []const u8) ContextTooLongError!Verifier
参数
错误
- ContextTooLong ContextTooLongError
std.crypto.ml_dsa.MLDSAImpl.Signature.verify
函数
针对消息和公钥验证此签名。 签名无效则返回错误。
pub fn verify( sig: Signature, msg: []const u8, public_key: PublicKey, ) VerifyError!void
参数
错误
- InvalidEncoding EncodingError
- SignatureVerificationFailed SignatureVerificationError
std.crypto.ml_dsa.MLDSAImpl.Signature.VerifyError
错误集合
错误
- InvalidEncoding EncodingError
- SignatureVerificationFailed SignatureVerificationError
std.crypto.ml_dsa.MLDSAImpl.Signature.verifyWithContext
函数
根据消息、公钥及上下文验证此签名。 若签名无效,则返回错误。 context 参数为可选上下文字符串,最长 255 字节。
pub fn verifyWithContext( sig: Signature, msg: []const u8, public_key: PublicKey, context: []const u8, ) VerifyError!void
参数
错误
- InvalidEncoding EncodingError
- SignatureVerificationFailed SignatureVerificationError
std.crypto.ml_dsa.MLDSAImpl.Signer
容器
字段
std.crypto.ml_dsa.MLDSAImpl.Signer.finalize
函数
计算整个消息的签名。
pub fn finalize(self: *Signer) Signature
参数
self: *Signer
std.crypto.ml_dsa.MLDSAImpl.Signer.init
函数
初始化新的 Signer。 noise 参数可为 null,以生成确定性签名; 也可提供随机性以生成带随机防护的签名,建议用于抵御故障攻击。 context 参数是可选的上下文字符串,最长 255 字节。
pub fn init(secret_key: *const SecretKey, noise: ?[noise_length]u8, context: []const u8) ContextTooLongError!Signer
参数
错误
- ContextTooLong ContextTooLongError
std.crypto.ml_dsa.MLDSAImpl.Signer.update
函数
向正在签名的消息加入新数据。
pub fn update(self: *Signer, data: []const u8) void
参数
self: *Signer
data: []const u8
std.crypto.ml_dsa.MLDSAImpl.Verifier
容器
Verifier 用于对流式消息增量验证签名。
可通过 Signature 的 verifier() 函数获取。
字段
std.crypto.ml_dsa.MLDSAImpl.Verifier.init
函数
初始化新的 Verifier。 context 参数是可选的上下文字符串,最长 255 字节。
pub fn init(signature: Signature, public_key: PublicKey, context: []const u8) ContextTooLongError!Verifier
参数
错误
- ContextTooLong ContextTooLongError
std.crypto.ml_dsa.MLDSAImpl.Verifier.InitError
别名
std.crypto.ml_dsa.MLDSAImpl.Verifier.update
函数
向待验证消息添加新内容。
pub fn update(self: *Verifier, data: []const u8) void
参数
self: *Verifier
data: []const u8
std.crypto.ml_dsa.MLDSAImpl.Verifier.verify
函数
验证签名对整个消息有效。
pub fn verify(self: *Verifier) SignatureVerificationError!void
参数
self: *Verifier
错误
- SignatureVerificationFailed SignatureVerificationError
std.crypto.ml_dsa.MLDSAImpl.Verifier.VerifyError
别名
std.crypto.ml_dsa.modQ
函数
fn modQ(x: u32) u32
参数
x: u32
std.crypto.ml_dsa.modularInverse
函数
模逆:计算 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
函数
模幂:使用平方乘算法计算 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
函数
蒙哥马利约减:对于输入 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
函数
fn montReduceLe2Q(x: u64) u32
参数
x: u64
std.crypto.ml_dsa.N
常量
usize
std.crypto.ml_dsa.Params
容器
字段
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
容器
字段
cs: [N]u32
std.crypto.ml_dsa.Poly.add
函数
fn add(a: Poly, b: Poly) Poly
参数
std.crypto.ml_dsa.Poly.exceeds
函数
fn exceeds(p: Poly, bound: u32) bool
参数
p: Poly
bound: u32
std.crypto.ml_dsa.Poly.invNTT
函数
fn invNTT(p: Poly) Poly
参数
p: Poly
std.crypto.ml_dsa.Poly.invNTTInPlace
函数
fn invNTTInPlace(p: *Poly) void
参数
p: *Poly
std.crypto.ml_dsa.Poly.mulHat
函数
fn mulHat(a: Poly, b: Poly) Poly
参数
std.crypto.ml_dsa.Poly.normalize
函数
fn normalize(p: Poly) Poly
参数
p: Poly
std.crypto.ml_dsa.Poly.normalizeAssumingLe2Q
函数
fn normalizeAssumingLe2Q(p: Poly) Poly
参数
p: Poly
std.crypto.ml_dsa.Poly.ntt
函数
fn ntt(p: Poly) Poly
参数
p: Poly
std.crypto.ml_dsa.Poly.nttInPlace
函数
fn nttInPlace(p: *Poly) void
参数
p: *Poly
std.crypto.ml_dsa.Poly.power2RoundPoly
类型函数
对所有系数应用 Power2Round 返回 t0 和 t1 两个多项式
fn power2RoundPoly(p: Poly) struct { t0: Poly, t1: Poly }
参数
p: Poly
std.crypto.ml_dsa.Poly.reduceLe2Q
函数
fn reduceLe2Q(p: Poly) Poly
参数
p: Poly
std.crypto.ml_dsa.Poly.sub
函数
fn sub(a: Poly, b: Poly) Poly
参数
std.crypto.ml_dsa.Poly.zero
常量
Poly
std.crypto.ml_dsa.polyDeriveUniform
函数
fn polyDeriveUniform(seed: *const [32]u8, nonce: u16) Poly
参数
seed: *const [32]u8
nonce: u16
std.crypto.ml_dsa.polyMakeHint
类型函数
为扰动后高位与原始高位的差异创建提示多项式。 返回设置为 1 的提示位数量,即置位计数。
在生成签名时使用,以创建帮助验证方在不访问秘密的情况下恢复高位的提示。
fn polyMakeHint(p0: Poly, p1: Poly, comptime gamma2: u32) struct { hint: Poly, count: u32 }
参数
std.crypto.ml_dsa.polyPackLeGamma1
函数
将系数位于 (-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
参数
std.crypto.ml_dsa.polyPackLeqEta
函数
将系数位于 [Q-eta, Q+eta] 的多项式打包为字节。 eta=2 时:每个系数打包为 3 位(共 96 字节)。 eta=4 时:每个系数打包为 4 位(共 128 字节)。 假定系数未归一化,但位于 [q-η, q+η]。
fn polyPackLeqEta(p: Poly, comptime eta: u8, buf: []u8) void
参数
std.crypto.ml_dsa.polyPackT0
函数
将系数位于 (-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
函数
将系数 < 1024(T1)的多项式打包为字节。 每个系数占 10 位:4 个系数打包为 5 字节。 假定系数已归一化。
fn polyPackT1(p: Poly, buf: []u8) void
参数
p: Poly
buf: []u8
std.crypto.ml_dsa.polyPackW1
函数
打包用于验证的 W1 多项式。 gamma1_bits=17 时:每个系数打包为 6 位(4 个系数共 3 字节)。 gamma1_bits=19 时:每个系数打包为 4 位(2 个系数共 1 字节)。 假定系数已归一化。
fn polyPackW1(p: Poly, comptime gamma1_bits: u8, buf: []u8) void
参数
std.crypto.ml_dsa.polyUnpackLeGamma1
函数
从字节解包系数位于 (-gamma1, gamma1] 的多项式。 输出系数将被规范化。
fn polyUnpackLeGamma1(comptime gamma1_bits: u8, buf: []const u8) Poly
参数
gamma1_bits: u8
buf: []const u8
std.crypto.ml_dsa.polyUnpackLeqEta
函数
从字节解包系数位于 [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
函数
从字节解包系数位于 (-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
函数
从字节中解包系数 < 1024 的多项式(T1)。 输出系数将归一化。
fn polyUnpackT1(buf: []const u8) Poly
参数
buf: []const u8
std.crypto.ml_dsa.polyUseHint
函数
应用提示,从扰动后的多项式重建高位。
在签名验证期间,使用签名中提供的提示 恢复高位。
fn polyUseHint(q: Poly, hint: Poly, comptime gamma2: u32) Poly
参数
std.crypto.ml_dsa.PolyVec
类型函数
fn PolyVec(comptime len: u8) type
参数
len: u8
字段
ps: [len]Poly
SelfzeromapmapBinarymapBinaryPolyaddsubnttinvNTTnormalizereduceLe2QnormalizeAssumingLe2Qexceedspower2RoundpackWithunpackWithpackT1unpackT1packT0unpackT0packLeqEtaunpackLeqEtapackLeGamma1unpackLeGamma1packW1decomposeVecmakeHintVecuseHintmulBy2toDderiveUniformLeGamma1packHintunpackHint
std.crypto.ml_dsa.PolyVec.add
函数
fn add(a: Self, b: Self) Self
参数
std.crypto.ml_dsa.PolyVec.decomposeVec
函数
将向量中的每个多项式分解为高位和低位
fn decomposeVec(v: Self, comptime gamma2: u32, w0_out: *Self) Self
参数
std.crypto.ml_dsa.PolyVec.deriveUniformLeGamma1
函数
采样系数均匀分布于 (-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
函数
fn exceeds(v: Self, bound: u32) bool
参数
v: Self
bound: u32
std.crypto.ml_dsa.PolyVec.invNTT
函数
fn invNTT(v: Self) Self
参数
v: Self
std.crypto.ml_dsa.PolyVec.makeHintVec
类型函数
为向量创建提示,返回提示中置位的数量。
fn makeHintVec(w0mcs2pct0: Self, w1: Self, comptime gamma2: u32) struct { hint: Self, pop: u32 }
参数
std.crypto.ml_dsa.PolyVec.map
函数
对向量中的每个多项式执行一元运算
fn map(v: Self, comptime op: fn (Poly) Poly) Self
参数
std.crypto.ml_dsa.PolyVec.mapBinary
函数
对两个向量逐对应用二元运算。
fn mapBinary(a: Self, b: Self, comptime op: fn (Poly, Poly) Poly) Self
参数
std.crypto.ml_dsa.PolyVec.mapBinaryPoly
函数
对向量与标量多项式应用二元运算。
fn mapBinaryPoly(v: Self, scalar: Poly, comptime op: fn (Poly, Poly) Poly) Self
参数
std.crypto.ml_dsa.PolyVec.mulBy2toD
函数
将向量乘以 2^D(左移)
fn mulBy2toD(v: Self) Self
参数
v: Self
std.crypto.ml_dsa.PolyVec.normalize
函数
fn normalize(v: Self) Self
参数
v: Self
std.crypto.ml_dsa.PolyVec.normalizeAssumingLe2Q
函数
fn normalizeAssumingLe2Q(v: Self) Self
参数
v: Self
std.crypto.ml_dsa.PolyVec.ntt
函数
fn ntt(v: Self) Self
参数
v: Self
std.crypto.ml_dsa.PolyVec.packHint
函数
将提示打包为字节 格式:对于每个多项式,找出 hint[i]=1 的位置,并编码这些位置
fn packHint(v: Self, comptime omega: u16, buf: []u8) bool
参数
std.crypto.ml_dsa.PolyVec.packLeGamma1
函数
打包系数 < gamma1 的多项式向量
fn packLeGamma1(v: Self, comptime gamma1_bits: u8, buf: []u8) void
参数
std.crypto.ml_dsa.PolyVec.packLeGamma1.pack
函数
fn pack(p: Poly, b: []u8) void
参数
p: Poly
b: []u8
std.crypto.ml_dsa.PolyVec.packLeqEta
函数
打包系数位于 [-eta, eta] 内的向量
fn packLeqEta(v: Self, comptime eta: u8, buf: []u8) void
参数
std.crypto.ml_dsa.PolyVec.packLeqEta.pack
函数
fn pack(p: Poly, b: []u8) void
参数
p: Poly
b: []u8
std.crypto.ml_dsa.PolyVec.packT0
函数
将 T0 向量打包为字节
fn packT0(v: Self, buf: []u8) void
参数
v: Self
buf: []u8
std.crypto.ml_dsa.PolyVec.packT1
函数
将 T1 向量打包为字节
fn packT1(v: Self, buf: []u8) void
参数
v: Self
buf: []u8
std.crypto.ml_dsa.PolyVec.packW1
函数
为签名验证打包高位 w1
fn packW1(v: Self, comptime gamma1_bits: u8, buf: []u8) void
参数
std.crypto.ml_dsa.PolyVec.packW1.pack
函数
fn pack(p: Poly, b: []u8) void
参数
p: Poly
b: []u8
std.crypto.ml_dsa.PolyVec.packWith
函数
通用向量打包函数
fn packWith( v: Self, buf: []u8, comptime poly_size: usize, comptime pack_fn: fn (Poly, []u8) void, ) void
参数
std.crypto.ml_dsa.PolyVec.power2Round
函数
对向量中的每个多项式应用 Power2Round 返回 t0 和 t1 两个向量
fn power2Round(v: Self, t0_out: *Self) Self
参数
std.crypto.ml_dsa.PolyVec.reduceLe2Q
函数
fn reduceLe2Q(v: Self) Self
参数
v: Self
std.crypto.ml_dsa.PolyVec.Self
别名
std.crypto.ml_dsa.PolyVec.sub
函数
fn sub(a: Self, b: Self) Self
参数
std.crypto.ml_dsa.PolyVec.unpackHint
函数
从字节解包提示
fn unpackHint(comptime omega: u16, buf: []const u8) ?Self
参数
omega: u16
buf: []const u8
std.crypto.ml_dsa.PolyVec.unpackLeGamma1
函数
解包系数 < gamma1 的多项式向量
fn unpackLeGamma1(comptime gamma1_bits: u8, buf: []const u8) Self
参数
gamma1_bits: u8
buf: []const u8
std.crypto.ml_dsa.PolyVec.unpackLeGamma1.unpack
函数
fn unpack(b: []const u8) Poly
参数
b: []const u8
std.crypto.ml_dsa.PolyVec.unpackLeqEta
函数
解包系数位于 [-eta, eta] 的向量。
fn unpackLeqEta(comptime eta: u8, buf: []const u8) Self
参数
eta: u8
buf: []const u8
std.crypto.ml_dsa.PolyVec.unpackLeqEta.unpack
函数
fn unpack(b: []const u8) Poly
参数
b: []const u8
std.crypto.ml_dsa.PolyVec.unpackT0
函数
从字节解包 T0 向量
fn unpackT0(buf: []const u8) Self
参数
buf: []const u8
std.crypto.ml_dsa.PolyVec.unpackT1
函数
从字节解包 T1 向量
fn unpackT1(bytes: []const u8) Self
参数
bytes: []const u8
std.crypto.ml_dsa.PolyVec.unpackWith
函数
向量的通用解包函数
fn unpackWith( comptime poly_size: usize, comptime unpack_fn: fn ([]const u8) Poly, buf: []const u8, ) Self
参数
std.crypto.ml_dsa.PolyVec.useHint
函数
应用提示以恢复高位
fn useHint(v: Self, hint: Self, comptime gamma2: u32) Self
参数
std.crypto.ml_dsa.PolyVec.zero
常量
Self
std.crypto.ml_dsa.power2Round
类型函数
将 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
常量
u32
std.crypto.ml_dsa.Q_BITS
常量
u32
std.crypto.ml_dsa.Q_INV
常量
u32
std.crypto.ml_dsa.R
常量
u64
std.crypto.ml_dsa.R_OVER_256
常量
u32
std.crypto.ml_dsa.sampleInBall
函数
使用 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
函数
使用 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
别名
别名目标 std.crypto.hash.sha3
std.crypto.ml_dsa.SignatureVerificationError
别名
std.crypto.ml_dsa.signMask
函数
由有符号整数的符号位创建掩码。 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
别名
别名目标 std
std.crypto.ml_dsa.testing
别名
别名目标 std.testing
std.crypto.ml_dsa.testKeyGenerationBasic
函数
fn testKeyGenerationBasic(comptime MlDsa: type, seed: [32]u8) !void
参数
MlDsa: type
seed: [32]u8
std.crypto.ml_dsa.testSignAndVerify
函数
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
函数
fn toMont(x: u32) u32
参数
x: u32
std.crypto.ml_dsa.useHint
函数
利用提示从扰动值重建高位。 给定:
- 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
常量
u32
std.crypto.ml_dsa.zetas
常量
源码
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)); // 最高有效位清零
}