/src/openssl/crypto/ml_dsa/ml_dsa_local.h

Source
/*
 * Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.
 *
 * Licensed under the Apache License 2.0 (the "License").  You may not use
 * this file except in compliance with the License.  You can obtain a copy
 * in the file LICENSE in the source distribution or at
 * https://www.openssl.org/source/license.html
 */

#ifndef OSSL_CRYPTO_ML_DSA_LOCAL_H
#define OSSL_CRYPTO_ML_DSA_LOCAL_H

#include "crypto/ml_dsa.h"
#include "internal/constant_time.h"
#include "internal/packet.h"

/* The following constants are shared by ML-DSA-44, ML-DSA-65 & ML-DSA-87 */
#define ML_DSA_Q 8380417 /* The modulus is 23 bits (2^23 - 2^13 + 1) */
#define ML_DSA_Q_MINUS1_DIV2 ((ML_DSA_Q - 1) / 2)

#define ML_DSA_Q_BITS 23
#define ML_DSA_Q_INV 58728449 /* q^-1 satisfies: q^-1 * q = 1 mod 2^32 */
#define ML_DSA_Q_NEG_INV 4236238847 /* Inverse of -q modulo 2^32 */
#define ML_DSA_DEGREE_INV_MONTGOMERY 41978 /* Inverse of 256 mod q, in Montgomery form. */

#define ML_DSA_D_BITS 13 /* The number of bits dropped from the public vector t */
#define ML_DSA_NUM_POLY_COEFFICIENTS 256 /* The number of coefficients in the polynomials */
#define ML_DSA_RHO_BYTES 32 /* p = Public Random Seed */
#define ML_DSA_PRIV_SEED_BYTES 64 /* p' = Private random seed */
#define ML_DSA_K_BYTES 32 /* K = Private random seed for signing */
#define ML_DSA_TR_BYTES 64 /* Size of the Hash of the public key used for signing */
#define ML_DSA_RHO_PRIME_BYTES 64 /* private random seed size */

/*
 * There is special case code related to encoding/decoding that tests the
 * for the following values.
 */
/*
 * The possible value for eta - If a new value is added, then all code
 * that accesses ML_DSA_ETA_4 would need to be modified.
 */
#define ML_DSA_ETA_4 4
#define ML_DSA_ETA_2 2
/*
 * The possible values of gamma1 - If a new value is added, then all code
 * that accesses ML_DSA_GAMMA1_TWO_POWER_19 would need to be modified.
 */
#define ML_DSA_GAMMA1_TWO_POWER_19 (1 << 19)
#define ML_DSA_GAMMA1_TWO_POWER_17 (1 << 17)
/*
 * The possible values for gamma2 - If a new value is added, then all code
 * that accesses ML_DSA_GAMMA2_Q_MINUS1_DIV32 would need to be modified.
 */
#define ML_DSA_GAMMA2_Q_MINUS1_DIV32 ((ML_DSA_Q - 1) / 32)
#define ML_DSA_GAMMA2_Q_MINUS1_DIV88 ((ML_DSA_Q - 1) / 88)

typedef struct poly_st POLY;
typedef struct vector_st VECTOR;
typedef struct matrix_st MATRIX;
typedef struct ml_dsa_sig_st ML_DSA_SIG;

int ossl_ml_dsa_matrix_expand_A(EVP_MD_CTX *g_ctx, const EVP_MD *md,
    const uint8_t *rho, MATRIX *out);
int ossl_ml_dsa_vector_expand_S(EVP_MD_CTX *h_ctx, const EVP_MD *md, int eta,
    const uint8_t *seed, VECTOR *s1, VECTOR *s2);
void ossl_ml_dsa_matrix_mult_vector(const MATRIX *matrix_kl, const VECTOR *vl,
    VECTOR *vk);
int ossl_ml_dsa_poly_expand_mask(POLY *out, const uint8_t *seed, size_t seed_len,
    uint32_t gamma1,
    EVP_MD_CTX *h_ctx, const EVP_MD *md);
int ossl_ml_dsa_poly_sample_in_ball(POLY *out_c, const uint8_t *seed, int seed_len,
    EVP_MD_CTX *h_ctx, const EVP_MD *md,
    uint32_t tau);

void ossl_ml_dsa_poly_ntt(POLY *s);
void ossl_ml_dsa_poly_ntt_inverse(POLY *s);
void ossl_ml_dsa_poly_ntt_mult(const POLY *lhs, const POLY *rhs, POLY *out);

void ossl_ml_dsa_key_compress_power2_round(uint32_t r, uint32_t *r1, uint32_t *r0);
uint32_t ossl_ml_dsa_key_compress_high_bits(uint32_t r, uint32_t gamma2);
void ossl_ml_dsa_key_compress_decompose(uint32_t r, uint32_t gamma2,
    uint32_t *r1, int32_t *r0);
void ossl_ml_dsa_key_compress_decompose(uint32_t r, uint32_t gamma2,
    uint32_t *r1, int32_t *r0);
int32_t ossl_ml_dsa_key_compress_low_bits(uint32_t r, uint32_t gamma2);
int32_t ossl_ml_dsa_key_compress_make_hint(uint32_t ct0, uint32_t cs2,
    uint32_t gamma2, uint32_t w);
uint32_t ossl_ml_dsa_key_compress_use_hint(uint32_t hint, uint32_t r,
    uint32_t gamma2);

int ossl_ml_dsa_pk_encode(ML_DSA_KEY *key);
int ossl_ml_dsa_sk_encode(ML_DSA_KEY *key);

int ossl_ml_dsa_sig_encode(const ML_DSA_SIG *sig, const ML_DSA_PARAMS *params,
    uint8_t *out);
int ossl_ml_dsa_sig_decode(ML_DSA_SIG *sig, const uint8_t *in, size_t in_len,
    const ML_DSA_PARAMS *params);
int ossl_ml_dsa_w1_encode(const VECTOR *w1, uint32_t gamma2,
    uint8_t *out, size_t out_len);
int ossl_ml_dsa_poly_decode_expand_mask(POLY *out,
    const uint8_t *in, size_t in_len,
    uint32_t gamma1);

/*-
 * @brief Reduces 0 <= x < 2*q, mod q.
 * i.e. return x < q ? x : x - q;
 *
 * Subtract |q| if the input is larger, without exposing a side-channel,
 * avoiding the "clangover" attack.  See |constish_time_true| for a discussion
 * on why the value barrier is by default omitted.
 *
 * @returns the difference in the range 0..q-1
 */
static ossl_inline ossl_unused __owur uint32_t reduce_once(uint32_t x)
{
    const uint32_t subtracted = x - ML_DSA_Q;
    uint32_t mask = constish_time_true(subtracted >> 31);

    return (mask & x) | (~mask & subtracted);
}

/*
 * @brief Calculates the positive value of (a-b) mod q in constant time.
 *
 * a - b mod q gives a value in the range -(q-1)..(q-1)
 * By adding q we get a range of 1..(2q-1).
 * Reducing this once then gives the range 0..q-1
 *
 * @param a The minuend assumed to be in the range 0..q-1
 * @param b The subtracthend assumed to be in the range 0..q-1.
 * @returns The value (q + a - b) mod q
 */
static ossl_inline ossl_unused uint32_t mod_sub(uint32_t a, uint32_t b)
{
    return reduce_once(ML_DSA_Q + a - b);
}

/*
 * @brief Returns the absolute value in constant time.
 * i.e.  return is_negative(x) ? -x : x;
 */
static ossl_inline ossl_unused uint32_t abs_signed(uint32_t x)
{
    uint32_t mask = 0u - (x >> 31);

    return constant_time_select_32(mask, 0u - x, x);
}

/*
 * @brief Returns the absolute value modulo q in constant time
 * i.e return x <= (q-1)/2 ? x : q - x;
 */
static ossl_inline ossl_unused uint32_t abs_mod_prime(uint32_t x)
{
    uint32_t mask = x - ML_DSA_Q_MINUS1_DIV2;

    mask = 0u - (mask >> 31);
    return constant_time_select_32(mask, x, ML_DSA_Q - x);
}

/*
 * @brief Returns the maximum of two values in constant time.
 * i.e return x < y ? y : x;
 */
static ossl_inline ossl_unused uint32_t maximum(uint32_t x, uint32_t y)
{
    uint32_t mask = x - y;
    mask = 0u - (mask >> 31);
    return constant_time_select_int(mask, y, x);
}

#endif /* OSSL_CRYPTO_ML_DSA_LOCAL_H */

Coverage Report

Created: 2026-04-28 06:29

Line	Count	Source
1		/*
2		* Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.
3		*
4		* Licensed under the Apache License 2.0 (the "License"). You may not use
5		* this file except in compliance with the License. You can obtain a copy
6		* in the file LICENSE in the source distribution or at
7		* https://www.openssl.org/source/license.html
8		*/
9
10		#ifndef OSSL_CRYPTO_ML_DSA_LOCAL_H
11		#define OSSL_CRYPTO_ML_DSA_LOCAL_H
12
13		#include "crypto/ml_dsa.h"
14		#include "internal/constant_time.h"
15		#include "internal/packet.h"
16
17		/* The following constants are shared by ML-DSA-44, ML-DSA-65 & ML-DSA-87 */
18	0	#define ML_DSA_Q 8380417 /* The modulus is 23 bits (2^23 - 2^13 + 1) */
19	0	#define ML_DSA_Q_MINUS1_DIV2 ((ML_DSA_Q - 1) / 2)
20
21		#define ML_DSA_Q_BITS 23
22		#define ML_DSA_Q_INV 58728449 /* q^-1 satisfies: q^-1 * q = 1 mod 2^32 */
23	0	#define ML_DSA_Q_NEG_INV 4236238847 /* Inverse of -q modulo 2^32 */
24		#define ML_DSA_DEGREE_INV_MONTGOMERY 41978 /* Inverse of 256 mod q, in Montgomery form. */
25
26	0	#define ML_DSA_D_BITS 13 /* The number of bits dropped from the public vector t */
27		#define ML_DSA_NUM_POLY_COEFFICIENTS 256 /* The number of coefficients in the polynomials */
28	0	#define ML_DSA_RHO_BYTES 32 /* p = Public Random Seed */
29	0	#define ML_DSA_PRIV_SEED_BYTES 64 /* p' = Private random seed */
30		#define ML_DSA_K_BYTES 32 /* K = Private random seed for signing */
31		#define ML_DSA_TR_BYTES 64 /* Size of the Hash of the public key used for signing */
32	0	#define ML_DSA_RHO_PRIME_BYTES 64 /* private random seed size */
33
34		/*
35		* There is special case code related to encoding/decoding that tests the
36		* for the following values.
37		*/
38		/*
39		* The possible value for eta - If a new value is added, then all code
40		* that accesses ML_DSA_ETA_4 would need to be modified.
41		*/
42	0	#define ML_DSA_ETA_4 4
43		#define ML_DSA_ETA_2 2
44		/*
45		* The possible values of gamma1 - If a new value is added, then all code
46		* that accesses ML_DSA_GAMMA1_TWO_POWER_19 would need to be modified.
47		*/
48	0	#define ML_DSA_GAMMA1_TWO_POWER_19 (1 << 19)
49		#define ML_DSA_GAMMA1_TWO_POWER_17 (1 << 17)
50		/*
51		* The possible values for gamma2 - If a new value is added, then all code
52		* that accesses ML_DSA_GAMMA2_Q_MINUS1_DIV32 would need to be modified.
53		*/
54	0	#define ML_DSA_GAMMA2_Q_MINUS1_DIV32 ((ML_DSA_Q - 1) / 32)
55	0	#define ML_DSA_GAMMA2_Q_MINUS1_DIV88 ((ML_DSA_Q - 1) / 88)
56
57		typedef struct poly_st POLY;
58		typedef struct vector_st VECTOR;
59		typedef struct matrix_st MATRIX;
60		typedef struct ml_dsa_sig_st ML_DSA_SIG;
61
62		int ossl_ml_dsa_matrix_expand_A(EVP_MD_CTX g_ctx, const EVP_MD md,
63		const uint8_t rho, MATRIX out);
64		int ossl_ml_dsa_vector_expand_S(EVP_MD_CTX h_ctx, const EVP_MD md, int eta,
65		const uint8_t seed, VECTOR s1, VECTOR *s2);
66		void ossl_ml_dsa_matrix_mult_vector(const MATRIX matrix_kl, const VECTOR vl,
67		VECTOR *vk);
68		int ossl_ml_dsa_poly_expand_mask(POLY out, const uint8_t seed, size_t seed_len,
69		uint32_t gamma1,
70		EVP_MD_CTX h_ctx, const EVP_MD md);
71		int ossl_ml_dsa_poly_sample_in_ball(POLY out_c, const uint8_t seed, int seed_len,
72		EVP_MD_CTX h_ctx, const EVP_MD md,
73		uint32_t tau);
74
75		void ossl_ml_dsa_poly_ntt(POLY *s);
76		void ossl_ml_dsa_poly_ntt_inverse(POLY *s);
77		void ossl_ml_dsa_poly_ntt_mult(const POLY lhs, const POLY rhs, POLY *out);
78
79		void ossl_ml_dsa_key_compress_power2_round(uint32_t r, uint32_t r1, uint32_t r0);
80		uint32_t ossl_ml_dsa_key_compress_high_bits(uint32_t r, uint32_t gamma2);
81		void ossl_ml_dsa_key_compress_decompose(uint32_t r, uint32_t gamma2,
82		uint32_t r1, int32_t r0);
83		void ossl_ml_dsa_key_compress_decompose(uint32_t r, uint32_t gamma2,
84		uint32_t r1, int32_t r0);
85		int32_t ossl_ml_dsa_key_compress_low_bits(uint32_t r, uint32_t gamma2);
86		int32_t ossl_ml_dsa_key_compress_make_hint(uint32_t ct0, uint32_t cs2,
87		uint32_t gamma2, uint32_t w);
88		uint32_t ossl_ml_dsa_key_compress_use_hint(uint32_t hint, uint32_t r,
89		uint32_t gamma2);
90
91		int ossl_ml_dsa_pk_encode(ML_DSA_KEY *key);
92		int ossl_ml_dsa_sk_encode(ML_DSA_KEY *key);
93
94		int ossl_ml_dsa_sig_encode(const ML_DSA_SIG sig, const ML_DSA_PARAMS params,
95		uint8_t *out);
96		int ossl_ml_dsa_sig_decode(ML_DSA_SIG sig, const uint8_t in, size_t in_len,
97		const ML_DSA_PARAMS *params);
98		int ossl_ml_dsa_w1_encode(const VECTOR *w1, uint32_t gamma2,
99		uint8_t *out, size_t out_len);
100		int ossl_ml_dsa_poly_decode_expand_mask(POLY *out,
101		const uint8_t *in, size_t in_len,
102		uint32_t gamma1);
103
104		/*-
105		* @brief Reduces 0 <= x < 2*q, mod q.
106		* i.e. return x < q ? x : x - q;
107		*
108		* Subtract \|q\| if the input is larger, without exposing a side-channel,
109		* avoiding the "clangover" attack. See \|constish_time_true\| for a discussion
110		* on why the value barrier is by default omitted.
111		*
112		* @returns the difference in the range 0..q-1
113		*/
114		static ossl_inline ossl_unused __owur uint32_t reduce_once(uint32_t x)
115	0	{
116	0	const uint32_t subtracted = x - ML_DSA_Q;
117	0	uint32_t mask = constish_time_true(subtracted >> 31);
118
119	0	return (mask & x) \| (~mask & subtracted);
120	0	} Unexecuted instantiation: ml_dsa_encoders.c:reduce_once Unexecuted instantiation: ml_dsa_key.c:reduce_once Unexecuted instantiation: ml_dsa_key_compress.c:reduce_once Unexecuted instantiation: ml_dsa_matrix.c:reduce_once Unexecuted instantiation: ml_dsa_ntt.c:reduce_once Unexecuted instantiation: ml_dsa_params.c:reduce_once Unexecuted instantiation: ml_dsa_sample.c:reduce_once Unexecuted instantiation: ml_dsa_sign.c:reduce_once
121
122		/*
123		* @brief Calculates the positive value of (a-b) mod q in constant time.
124		*
125		* a - b mod q gives a value in the range -(q-1)..(q-1)
126		* By adding q we get a range of 1..(2q-1).
127		* Reducing this once then gives the range 0..q-1
128		*
129		* @param a The minuend assumed to be in the range 0..q-1
130		* @param b The subtracthend assumed to be in the range 0..q-1.
131		* @returns The value (q + a - b) mod q
132		*/
133		static ossl_inline ossl_unused uint32_t mod_sub(uint32_t a, uint32_t b)
134	0	{
135	0	return reduce_once(ML_DSA_Q + a - b);
136	0	} Unexecuted instantiation: ml_dsa_encoders.c:mod_sub Unexecuted instantiation: ml_dsa_key.c:mod_sub Unexecuted instantiation: ml_dsa_key_compress.c:mod_sub Unexecuted instantiation: ml_dsa_matrix.c:mod_sub Unexecuted instantiation: ml_dsa_ntt.c:mod_sub Unexecuted instantiation: ml_dsa_params.c:mod_sub Unexecuted instantiation: ml_dsa_sample.c:mod_sub Unexecuted instantiation: ml_dsa_sign.c:mod_sub
137
138		/*
139		* @brief Returns the absolute value in constant time.
140		* i.e. return is_negative(x) ? -x : x;
141		*/
142		static ossl_inline ossl_unused uint32_t abs_signed(uint32_t x)
143	0	{
144	0	uint32_t mask = 0u - (x >> 31);
145
146	0	return constant_time_select_32(mask, 0u - x, x);
147	0	} Unexecuted instantiation: ml_dsa_encoders.c:abs_signed Unexecuted instantiation: ml_dsa_key.c:abs_signed Unexecuted instantiation: ml_dsa_key_compress.c:abs_signed Unexecuted instantiation: ml_dsa_matrix.c:abs_signed Unexecuted instantiation: ml_dsa_ntt.c:abs_signed Unexecuted instantiation: ml_dsa_params.c:abs_signed Unexecuted instantiation: ml_dsa_sample.c:abs_signed Unexecuted instantiation: ml_dsa_sign.c:abs_signed
148
149		/*
150		* @brief Returns the absolute value modulo q in constant time
151		* i.e return x <= (q-1)/2 ? x : q - x;
152		*/
153		static ossl_inline ossl_unused uint32_t abs_mod_prime(uint32_t x)
154	0	{
155	0	uint32_t mask = x - ML_DSA_Q_MINUS1_DIV2;
156
157	0	mask = 0u - (mask >> 31);
158	0	return constant_time_select_32(mask, x, ML_DSA_Q - x);
159	0	} Unexecuted instantiation: ml_dsa_encoders.c:abs_mod_prime Unexecuted instantiation: ml_dsa_key.c:abs_mod_prime Unexecuted instantiation: ml_dsa_key_compress.c:abs_mod_prime Unexecuted instantiation: ml_dsa_matrix.c:abs_mod_prime Unexecuted instantiation: ml_dsa_ntt.c:abs_mod_prime Unexecuted instantiation: ml_dsa_params.c:abs_mod_prime Unexecuted instantiation: ml_dsa_sample.c:abs_mod_prime Unexecuted instantiation: ml_dsa_sign.c:abs_mod_prime
160
161		/*
162		* @brief Returns the maximum of two values in constant time.
163		* i.e return x < y ? y : x;
164		*/
165		static ossl_inline ossl_unused uint32_t maximum(uint32_t x, uint32_t y)
166	0	{
167	0	uint32_t mask = x - y;
168	0	mask = 0u - (mask >> 31);
169	0	return constant_time_select_int(mask, y, x);
170	0	} Unexecuted instantiation: ml_dsa_encoders.c:maximum Unexecuted instantiation: ml_dsa_key.c:maximum Unexecuted instantiation: ml_dsa_key_compress.c:maximum Unexecuted instantiation: ml_dsa_matrix.c:maximum Unexecuted instantiation: ml_dsa_ntt.c:maximum Unexecuted instantiation: ml_dsa_params.c:maximum Unexecuted instantiation: ml_dsa_sample.c:maximum Unexecuted instantiation: ml_dsa_sign.c:maximum
171
172		#endif /* OSSL_CRYPTO_ML_DSA_LOCAL_H */