1 =pod 2 3 =head1 NAME 4 5 EVP_SIGNATURE-ML-DSA, 6 EVP_SIGNATURE-ML-DSA-44, EVP_SIGNATURE-ML-DSA-65, EVP_SIGNATURE-ML-DSA-87 7 - The EVP_PKEY B<ML-DSA> signature implementations 8 9 =head1 DESCRIPTION 10 11 The B<ML-DSA-44>, B<ML-DSA-65> and B<ML-DSA-87> EVP_PKEY implementations 12 support key generation, and one-shot sign and verify using the ML-DSA 13 signature schemes described in L<FIPS 204|https://csrc.nist.gov/pubs/fips/204/final>. 14 15 The different algorithms names correspond to the parameter sets defined in 16 L<FIPS 204|https://csrc.nist.gov/pubs/fips/204/final> Section 4 Table 1. 17 (The signatures range in size from ~2.5K to ~4.5K depending on the type chosen). 18 There are 3 different security categories also depending on the type. 19 20 L<EVP_SIGNATURE_fetch(3)> can be used to explicitly fetch one of the 3 21 algorithms which can then be used with L<EVP_PKEY_sign_message_init(3)>, 22 L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify_message_init(3)>, and 23 L<EVP_PKEY_verify(3)> to perform one-shot message signing or signature verification. 24 25 The normal signing process (called Pure ML-DSA Signature Generation) 26 encodes the message internally as 0x00 || len(ctx) || ctx || message. 27 where B<ctx> is some optional value of size 0x00..0xFF. This process is 28 defined in L<FIPS 204|https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2 29 step 10 and Algorithm 3 step 5. 30 OpenSSL also allows the message to not be encoded which is required for 31 testing. OpenSSL does not support Pre Hash ML-DSA Signature Generation, but this 32 may be done by the user by doing Pre hash encoding externally and then choosing 33 the option to not encode the message. 34 35 =head2 ML-DSA Signature Parameters 36 37 The following parameter can be used for both signing and verification. 38 it may be set by passing an OSSL_PARAM array to L<EVP_PKEY_sign_message_init(3)> 39 or L<EVP_PKEY_verify_message_init(3)> 40 41 =over 4 42 43 =item "context-string" (B<OSSL_SIGNATURE_PARAM_CONTEXT_STRING>) <octet string> 44 45 A string of octets with length at most 255. By default it is the empty string. 46 47 =back 48 49 The following parameters can be used when signing: 50 They can be set by passing an OSSL_PARAM array to L<EVP_PKEY_sign_init_ex2(3)>. 51 52 =over 4 53 54 =item "message-encoding" (B<OSSL_SIGNATURE_PARAM_MESSAGE_ENCODING>) <integer> 55 56 The default value of 1 uses 'Pure ML-DSA Signature Generation' as described 57 above. Setting it to 0 does not encode the message, which is used for testing. 58 The message encoding steps are defined in 59 L<FIPS 204|https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2 step 10 and 60 Algorithm 3 step 5. 61 62 =item "test-entropy" (B<OSSL_SIGNATURE_PARAM_TEST_ENTROPY>) <octet string> 63 64 Used for testing to pass an optional deterministic per message random value. 65 If set the size must be 32 bytes. 66 67 =item "deterministic" (B<OSSL_SIGNATURE_PARAM_DETERMINISTIC>) <integer> 68 69 The default value of 0 causes the per message randomness to be randomly 70 generated using a DRBG. Setting this to 1 causes the per message randomness 71 to be set to 32 bytes of zeros. This value is ignored if "test-entropy" is set. 72 73 =item "mu" (B<OSSL_SIGNATURE_PARAM_MU>) <integer> 74 75 The default value of 0 causes sign and verify operations to process a raw message. 76 Setting this to 1 causes those operations to assume the input is the C<mu> value 77 from L<FIPS 204|https://csrc.nist.gov/pubs/fips/204/final> Algorithm 7 step 6 and 78 Algorithm 8 step 7. 79 80 Note that the message encoding steps from 81 L<FIPS 204|https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2 step 10 and 82 Algorithm 3 step 5 are omitted when this setting is 1. 83 84 =back 85 86 See L<EVP_PKEY-ML-DSA(7)> for information related to B<ML-DSA> keys. 87 88 =head1 NOTES 89 90 For backwards compatibility reasons EVP_DigestSignInit_ex(), EVP_DigestSign(), 91 EVP_DigestVerifyInit_ex() and EVP_DigestVerify() may also be used, but the digest 92 passed in I<mdname> must be NULL. 93 94 =head1 EXAMPLES 95 96 To sign a message using an ML-DSA EVP_PKEY structure: 97 98 void do_sign(EVP_PKEY *key, unsigned char *msg, size_t msg_len) 99 { 100 size_t sig_len; 101 unsigned char *sig = NULL; 102 const OSSL_PARAM params[] = { 103 OSSL_PARAM_octet_string("context-string", (unsigned char *)"A context string", 16), 104 OSSL_PARAM_END 105 }; 106 EVP_PKEY_CTX *sctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL); 107 EVP_SIGNATURE *sig_alg = EVP_SIGNATURE_fetch(NULL, "ML-DSA-65", NULL); 108 109 EVP_PKEY_sign_message_init(sctx, sig_alg, params); 110 /* Calculate the required size for the signature by passing a NULL buffer. */ 111 EVP_PKEY_sign(sctx, NULL, &sig_len, msg, msg_len); 112 sig = OPENSSL_zalloc(sig_len); 113 EVP_PKEY_sign(sctx, sig, &sig_len, msg, msg_len); 114 ... 115 OPENSSL_free(sig); 116 EVP_SIGNATURE_free(sig_alg); 117 EVP_PKEY_CTX_free(sctx); 118 } 119 120 =head1 SEE ALSO 121 122 L<EVP_PKEY-ML-DSA(7)> 123 L<provider-signature(7)>, 124 L<EVP_PKEY_sign(3)>, 125 L<EVP_PKEY_verify(3)>, 126 L<FIPS 204|https://csrc.nist.gov/pubs/fips/204/final> 127 128 =head1 HISTORY 129 130 This functionality was added in OpenSSL 3.5. 131 132 =head1 COPYRIGHT 133 134 Copyright 2025-2026 The OpenSSL Project Authors. All Rights Reserved. 135 136 Licensed under the Apache License 2.0 (the "License"). You may not use 137 this file except in compliance with the License. You can obtain a copy 138 in the file LICENSE in the source distribution or at 139 L<https://www.openssl.org/source/license.html>. 140 141 =cut 142
Indexes created Sat Oct 10 00:27:21 UTC 2026