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