/*

 * Copyright 2024-2026 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;

typedef int(ML_DSA_MATRIX_EXPAND_A_FN)(EVP_MD_CTX *g_ctx, const EVP_MD *md,

    const uint8_t *rho, MATRIX *out);

typedef int(ML_DSA_VECTOR_EXPAND_S_FN)(EVP_MD_CTX *h_ctx, const EVP_MD *md,

    int eta, const uint8_t *seed, VECTOR *s1, VECTOR *s2);

typedef void(ML_DSA_VECTOR_EXPAND_MASK_FN)(VECTOR *out,

    const uint8_t rho_prime[ML_DSA_RHO_PRIME_BYTES], uint32_t kappa, uint32_t gamma1,

    EVP_MD_CTX *h_ctx, const EVP_MD *md);

typedef struct ossl_ml_dsa_sample_ops_st {

    ML_DSA_MATRIX_EXPAND_A_FN *matrix_expand_A;

    ML_DSA_VECTOR_EXPAND_S_FN *vector_expand_S;

    ML_DSA_VECTOR_EXPAND_MASK_FN *vector_expand_mask;

} OSSL_ML_DSA_SAMPLE_OPS;

const OSSL_ML_DSA_SAMPLE_OPS *ossl_ml_dsa_sample_ops(void);

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);

/* Optimization for s390x */

/*

 * The forward declarations below must be visible in every TU that includes

 * this header while compiling for s390x with the VX object enabled —

 * specifically in ml_dsa_ntt.c (the dispatcher) and in ml_dsa_ntt_vec128.c

 * (the implementation).  OPENSSL_ML_DSA_S390X is injected by the build

 * system for all asm-enabled s390x targets; it is sufficient on its own —

 * no additional __s390x__ predefined-macro check is needed because the

 * define is never emitted for non-s390x targets.

 */

#if defined(OPENSSL_ML_DSA_S390X)

#include "arch/s390x_arch.h"

void ossl_ml_dsa_poly_ntt_scalar(POLY *p);

void ossl_ml_dsa_poly_ntt_vec128(POLY *p);

void ossl_ml_dsa_poly_ntt_inverse_vec128(POLY *p);

void ossl_poly_ntt_mult_scalar_vec128(const POLY *lhs, const POLY *rhs, POLY *out);

#endif

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);

}

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

/*

 * @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);

}

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

/*

 * @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);

}

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

/*

 * @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);

}

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

/*

 * @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);

}

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

#endif /* OSSL_CRYPTO_ML_DSA_LOCAL_H */