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 /* Internal ML_DSA functions for other submodules, not for application use */ 11 12 #ifndef OSSL_CRYPTO_ML_DSA_H 13 # define OSSL_CRYPTO_ML_DSA_H 14 15 # pragma once 16 # include <openssl/e_os2.h> 17 # include <openssl/types.h> 18 # include "crypto/types.h" 19 20 # define ML_DSA_MAX_CONTEXT_STRING_LEN 255 21 # define ML_DSA_SEED_BYTES 32 22 23 # define ML_DSA_ENTROPY_LEN 32 24 25 # define ML_DSA_MU_BYTES 64 /* Size of the Hash for the message representative */ 26 27 /* See FIPS 204 Section 4 Table 1 & Table 2 */ 28 # define ML_DSA_44_PRIV_LEN 2560 29 # define ML_DSA_44_PUB_LEN 1312 30 # define ML_DSA_44_SIG_LEN 2420 31 32 /* See FIPS 204 Section 4 Table 1 & Table 2 */ 33 # define ML_DSA_65_PRIV_LEN 4032 34 # define ML_DSA_65_PUB_LEN 1952 35 # define ML_DSA_65_SIG_LEN 3309 36 37 /* See FIPS 204 Section 4 Table 1 & Table 2 */ 38 # define ML_DSA_87_PRIV_LEN 4896 39 # define ML_DSA_87_PUB_LEN 2592 40 # define ML_DSA_87_SIG_LEN 4627 41 42 /* Key and signature size maxima taken from values above */ 43 # define MAX_ML_DSA_PRIV_LEN ML_DSA_87_PRIV_LEN 44 # define MAX_ML_DSA_PUB_LEN ML_DSA_87_PUB_LEN 45 # define MAX_ML_DSA_SIG_LEN ML_DSA_87_SIG_LEN 46 47 # define ML_DSA_KEY_PREFER_SEED (1 << 0) 48 # define ML_DSA_KEY_RETAIN_SEED (1 << 1) 49 /* Default provider flags */ 50 # define ML_DSA_KEY_PROV_FLAGS_DEFAULT \ 51 (ML_DSA_KEY_PREFER_SEED | ML_DSA_KEY_RETAIN_SEED) 52 53 /* 54 * Refer to FIPS 204 Section 4 Parameter sets. 55 * Fields that are shared between all algorithms (such as q & d) have been omitted. 56 */ 57 typedef struct ml_dsa_params_st { 58 const char *alg; 59 int evp_type; 60 int tau; /* Number of +/-1's in polynomial c */ 61 int bit_strength; /* The collision strength (lambda) */ 62 int gamma1; /* coefficient range of y */ 63 int gamma2; /* low-order rounding range */ 64 size_t k, l; /* matrix dimensions of 'A' */ 65 int eta; /* Private key range */ 66 int beta; /* tau * eta */ 67 int omega; /* Number of 1's in the hint 'h' */ 68 int security_category; /* Category is related to Security strength */ 69 size_t sk_len; /* private key size */ 70 size_t pk_len; /* public key size */ 71 size_t sig_len; /* signature size */ 72 } ML_DSA_PARAMS; 73 74 /* NOTE - any changes to this struct may require updates to ossl_ml_dsa_dup() */ 75 typedef struct ml_dsa_key_st ML_DSA_KEY; 76 77 const ML_DSA_PARAMS *ossl_ml_dsa_params_get(int evp_type); 78 const ML_DSA_PARAMS *ossl_ml_dsa_key_params(const ML_DSA_KEY *key); 79 __owur ML_DSA_KEY *ossl_ml_dsa_key_new(OSSL_LIB_CTX *libctx, const char *propq, 80 int evp_type); 81 /* Factory reset for keys that fail initialisation */ 82 void ossl_ml_dsa_key_reset(ML_DSA_KEY *key); 83 __owur int ossl_ml_dsa_key_pub_alloc(ML_DSA_KEY *key); 84 __owur int ossl_ml_dsa_key_priv_alloc(ML_DSA_KEY *key); 85 void ossl_ml_dsa_key_free(ML_DSA_KEY *key); 86 __owur ML_DSA_KEY *ossl_ml_dsa_key_dup(const ML_DSA_KEY *src, int selection); 87 __owur int ossl_ml_dsa_key_equal(const ML_DSA_KEY *key1, const ML_DSA_KEY *key2, 88 int selection); 89 __owur int ossl_ml_dsa_key_has(const ML_DSA_KEY *key, int selection); 90 __owur int ossl_ml_dsa_key_pairwise_check(const ML_DSA_KEY *key); 91 __owur int ossl_ml_dsa_generate_key(ML_DSA_KEY *out); 92 __owur const uint8_t *ossl_ml_dsa_key_get_pub(const ML_DSA_KEY *key); 93 __owur size_t ossl_ml_dsa_key_get_pub_len(const ML_DSA_KEY *key); 94 __owur const uint8_t *ossl_ml_dsa_key_get_priv(const ML_DSA_KEY *key); 95 __owur size_t ossl_ml_dsa_key_get_priv_len(const ML_DSA_KEY *key); 96 __owur const uint8_t *ossl_ml_dsa_key_get_seed(const ML_DSA_KEY *key); 97 __owur int ossl_ml_dsa_key_get_prov_flags(const ML_DSA_KEY *key); 98 int ossl_ml_dsa_set_prekey(ML_DSA_KEY *key, int flags_set, int flags_clr, 99 const uint8_t *seed, size_t seed_len, 100 const uint8_t *sk, size_t sk_len); 101 __owur size_t ossl_ml_dsa_key_get_collision_strength_bits(const ML_DSA_KEY *key); 102 __owur int ossl_ml_dsa_key_get_security_category(const ML_DSA_KEY *key); 103 __owur size_t ossl_ml_dsa_key_get_sig_len(const ML_DSA_KEY *key); 104 __owur int ossl_ml_dsa_key_matches(const ML_DSA_KEY *key, int evp_type); 105 __owur const char *ossl_ml_dsa_key_get_name(const ML_DSA_KEY *key); 106 OSSL_LIB_CTX *ossl_ml_dsa_key_get0_libctx(const ML_DSA_KEY *key); 107 108 __owur int ossl_ml_dsa_key_public_from_private(ML_DSA_KEY *key); 109 __owur int ossl_ml_dsa_pk_decode(ML_DSA_KEY *key, const uint8_t *in, size_t in_len); 110 __owur int ossl_ml_dsa_sk_decode(ML_DSA_KEY *key, const uint8_t *in, size_t in_len); 111 112 EVP_MD_CTX *ossl_ml_dsa_mu_init(const ML_DSA_KEY *key, int encode, 113 const uint8_t *ctx, size_t ctx_len); 114 __owur int ossl_ml_dsa_mu_update(EVP_MD_CTX *md_ctx, const uint8_t *msg, size_t msg_len); 115 __owur int ossl_ml_dsa_mu_finalize(EVP_MD_CTX *md_ctx, uint8_t *mu, size_t mu_len); 116 117 __owur int ossl_ml_dsa_sign(const ML_DSA_KEY *priv, int msg_is_mu, 118 const uint8_t *msg, size_t msg_len, 119 const uint8_t *context, size_t context_len, 120 const uint8_t *rand, size_t rand_len, int encode, 121 unsigned char *sig, size_t *siglen, size_t sigsize); 122 __owur int ossl_ml_dsa_verify(const ML_DSA_KEY *pub, int msg_is_mu, 123 const uint8_t *msg, size_t msg_len, 124 const uint8_t *context, size_t context_len, 125 int encode, const uint8_t *sig, size_t sig_len); 126 127 #endif /* OSSL_CRYPTO_SLH_DSA_H */ 128