1 files changed, 180 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-ML-DSA.7 b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-ML-DSA.7
new file mode 100644
index 000000000000..51b46b446b59
--- /dev/null
+++ b/secure/lib/libcrypto/man/man7/EVP_SIGNATURE-ML-DSA.7
@@ -0,0 +1,180 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "EVP_SIGNATURE-ML-DSA 7ossl"
+.TH EVP_SIGNATURE-ML-DSA 7ossl 2025-09-30 3.5.4 OpenSSL
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+EVP_SIGNATURE\-ML\-DSA,
+EVP_SIGNATURE\-ML\-DSA\-44, EVP_SIGNATURE\-ML\-DSA\-65, EVP_SIGNATURE\-ML\-DSA\-87,
+\&\- EVP_SIGNATURE ML\-DSA support
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR and \fBML\-DSA\-87\fR EVP_PKEY implementations
+support key generation, and one-shot sign and verify using the ML-DSA
+signature schemes described in FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final>.
+.PP
+The different algorithms names correspond to the parameter sets defined in
+FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Section 4 Table 1.
+(The signatures range in size from ~2.5K to ~4.5K depending on the type chosen).
+There are 3 different security categories also depending on the type.
+.PP
+\&\fBEVP_SIGNATURE_fetch\fR\|(3) can be used to explicitely fetch one of the 3
+algorithms which can then be used with \fBEVP_PKEY_sign_message_init\fR\|(3),
+\&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify_message_init\fR\|(3), and
+\&\fBEVP_PKEY_verify\fR\|(3) to perform one-shot message signing or signature verification.
+.PP
+The normal signing process (called Pure ML-DSA Signature Generation)
+encodes the message internally as 0x00 || len(ctx) || ctx || message.
+where \fBctx\fR is some optional value of size 0x00..0xFF.  This process is
+defined in FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2
+step 10 and Algorithm 3 step 5.
+OpenSSL also allows the message to not be encoded which is required for
+testing. OpenSSL does not support Pre Hash ML-DSA Signature Generation, but this
+may be done by the user by doing Pre hash encoding externally and then choosing
+the option to not encode the message.
+.SS "ML-DSA Signature Parameters"
+.IX Subsection "ML-DSA Signature Parameters"
+The following parameter can be used for both signing and verification.
+it may be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_message_init\fR\|(3)
+or \fBEVP_PKEY_verify_message_init\fR\|(3)
+.IP """context-string"" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) <octet string>" 4
+.IX Item """context-string"" (OSSL_SIGNATURE_PARAM_CONTEXT_STRING) <octet string>"
+A string of octets with length at most 255. By default it is the empty string.
+.PP
+The following parameters can be used when signing:
+They can be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_init_ex2\fR\|(3).
+.IP """message-encoding"" (\fBOSSL_SIGNATURE_PARAM_MESSAGE_ENCODING\fR) <integer>" 4
+.IX Item """message-encoding"" (OSSL_SIGNATURE_PARAM_MESSAGE_ENCODING) <integer>"
+The default value of 1 uses 'Pure ML-DSA Signature Generation' as described
+above. Setting it to 0 does not encode the message, which is used for testing.
+The message encoding steps are defined in
+FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2 step 10 and
+Algorithm 3 step 5.
+.IP """test-entropy"" (\fBOSSL_SIGNATURE_PARAM_TEST_ENTROPY\fR) <octet string>" 4
+.IX Item """test-entropy"" (OSSL_SIGNATURE_PARAM_TEST_ENTROPY) <octet string>"
+Used for testing to pass an optional deterministic per message random value.
+If set the size must be 32 bytes.
+.IP """deterministic"" (\fBOSSL_SIGNATURE_PARAM_DETERMINISTIC\fR) <integer>" 4
+.IX Item """deterministic"" (OSSL_SIGNATURE_PARAM_DETERMINISTIC) <integer>"
+The default value of 0 causes the per message randomness to be randomly
+generated using a DRBG. Setting this to 1 causes the per message randomness
+to be set to 32 bytes of zeros. This value is ignored if "test-entropy" is set.
+.IP """mu"" (\fBOSSL_SIGNATURE_PARAM_MU\fR) <integer>" 4
+.IX Item """mu"" (OSSL_SIGNATURE_PARAM_MU) <integer>"
+The default value of 0 causes sign and verify operations to process a raw message.
+Setting this to 1 causes those operations to assume the input is the \f(CW\*(C`mu\*(C'\fR value
+from FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Algorithm 7 step 6 and
+Algorithm 8 step 7.
+.Sp
+Note that the message encoding steps from
+FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2 step 10 and
+Algorithm 3 step 5 are omitted when this setting is 1.
+.PP
+See \fBEVP_PKEY\-ML\-DSA\fR\|(7) for information related to \fBML-DSA\fR keys.
+.SH NOTES
+.IX Header "NOTES"
+For backwards compatability reasons \fBEVP_DigestSignInit_ex()\fR, \fBEVP_DigestSign()\fR,
+\&\fBEVP_DigestVerifyInit_ex()\fR and \fBEVP_DigestVerify()\fR may also be used, but the digest
+passed in \fImdname\fR must be NULL.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+To sign a message using an ML-DSA EVP_PKEY structure:
+.PP
+.Vb 10
+\&    void do_sign(EVP_PKEY *key, unsigned char *msg, size_t msg_len)
+\&    {
+\&        size_t sig_len;
+\&        unsigned char *sig = NULL;
+\&        const OSSL_PARAM params[] = {
+\&            OSSL_PARAM_octet_string("context\-string", (unsigned char *)"A context string", 16),
+\&            OSSL_PARAM_END
+\&        };
+\&        EVP_PKEY_CTX *sctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL);
+\&        EVP_SIGNATURE *sig_alg = EVP_SIGNATURE_fetch(NULL, "ML\-DSA\-65", NULL);
+\&
+\&        EVP_PKEY_sign_message_init(sctx, sig_alg, params);
+\&        /* Calculate the required size for the signature by passing a NULL buffer. */
+\&        EVP_PKEY_sign(sctx, NULL, &sig_len, msg, msg_len);
+\&        sig = OPENSSL_zalloc(sig_len);
+\&        EVP_PKEY_sign(sctx, sig, &sig_len, msg, msg_len);
+\&        ...
+\&        OPENSSL_free(sig);
+\&        EVP_SIGNATURE_free(sig_alg);
+\&        EVP_PKEY_CTX_free(sctx);
+\&    }
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBEVP_PKEY\-ML\-DSA\fR\|(7)
+\&\fBprovider\-signature\fR\|(7),
+\&\fBEVP_PKEY_sign\fR\|(3),
+\&\fBEVP_PKEY_verify\fR\|(3),
+FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final>
+.SH HISTORY
+.IX Header "HISTORY"
+This functionality was added in OpenSSL 3.5.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
+.PP
+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>.