Debian Codegraph @

upstream/debian-unstable/man7/EVP_SIGNATURE-ML-DSA.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_SIGNATURE-ML-DSA 7SSL"
58 .TH EVP_SIGNATURE-ML-DSA 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_SIGNATURE\-ML\-DSA,
65 EVP_SIGNATURE\-ML\-DSA\-44, EVP_SIGNATURE\-ML\-DSA\-65, EVP_SIGNATURE\-ML\-DSA\-87
66 \&\- The EVP_PKEY ML\-DSA signature implementations
67 .SH DESCRIPTION
68 .IX Header "DESCRIPTION"
69 The \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR and \fBML\-DSA\-87\fR EVP_PKEY implementations
70 support key generation, and one-shot sign and verify using the ML-DSA
71 signature schemes described in FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final>.
72 .PP
73 The different algorithms names correspond to the parameter sets defined in
74 FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Section 4 Table 1.
75 (The signatures range in size from ~2.5K to ~4.5K depending on the type chosen).
76 There are 3 different security categories also depending on the type.
77 .PP
78 \&\fBEVP_SIGNATURE_fetch\fR\|(3) can be used to explicitly fetch one of the 3
79 algorithms which can then be used with \fBEVP_PKEY_sign_message_init\fR\|(3),
80 \&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify_message_init\fR\|(3), and
81 \&\fBEVP_PKEY_verify\fR\|(3) to perform one-shot message signing or signature verification.
82 .PP
83 The normal signing process (called Pure ML-DSA Signature Generation)
84 encodes the message internally as 0x00 || len(ctx) || ctx || message.
85 where \fBctx\fR is some optional value of size 0x00..0xFF. This process is
86 defined in FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2
87 step 10 and Algorithm 3 step 5.
88 OpenSSL also allows the message to not be encoded which is required for
89 testing. OpenSSL does not support Pre Hash ML-DSA Signature Generation, but this
90 may be done by the user by doing Pre hash encoding externally and then choosing
91 the option to not encode the message.
92 .SS "ML-DSA Signature Parameters"
93 .IX Subsection "ML-DSA Signature Parameters"
94 The following parameter can be used for both signing and verification.
95 it may be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_message_init\fR\|(3)
96 or \fBEVP_PKEY_verify_message_init\fR\|(3)
97 .IP """context-string"" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) <octet string>" 4
98 .IX Item """context-string"" (OSSL_SIGNATURE_PARAM_CONTEXT_STRING) <octet string>"
99 A string of octets with length at most 255. By default it is the empty string.
100 .PP
101 The following parameters can be used when signing:
102 They can be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_init_ex2\fR\|(3).
103 .IP """message-encoding"" (\fBOSSL_SIGNATURE_PARAM_MESSAGE_ENCODING\fR) <integer>" 4
104 .IX Item """message-encoding"" (OSSL_SIGNATURE_PARAM_MESSAGE_ENCODING) <integer>"
105 The default value of 1 uses 'Pure ML-DSA Signature Generation' as described
106 above. Setting it to 0 does not encode the message, which is used for testing.
107 The message encoding steps are defined in
108 FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2 step 10 and
109 Algorithm 3 step 5.
110 .IP """test-entropy"" (\fBOSSL_SIGNATURE_PARAM_TEST_ENTROPY\fR) <octet string>" 4
111 .IX Item """test-entropy"" (OSSL_SIGNATURE_PARAM_TEST_ENTROPY) <octet string>"
112 Used for testing to pass an optional deterministic per message random value.
113 If set the size must be 32 bytes.
114 .IP """deterministic"" (\fBOSSL_SIGNATURE_PARAM_DETERMINISTIC\fR) <integer>" 4
115 .IX Item """deterministic"" (OSSL_SIGNATURE_PARAM_DETERMINISTIC) <integer>"
116 The default value of 0 causes the per message randomness to be randomly
117 generated using a DRBG. Setting this to 1 causes the per message randomness
118 to be set to 32 bytes of zeros. This value is ignored if "test-entropy" is set.
119 .IP """mu"" (\fBOSSL_SIGNATURE_PARAM_MU\fR) <integer>" 4
120 .IX Item """mu"" (OSSL_SIGNATURE_PARAM_MU) <integer>"
121 The default value of 0 causes sign and verify operations to process a raw message.
122 Setting this to 1 causes those operations to assume the input is the \f(CW\*(C`mu\*(C'\fR value
123 from FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Algorithm 7 step 6 and
124 Algorithm 8 step 7.
125 .Sp
126 Note that the message encoding steps from
127 FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final> Algorithm 2 step 10 and
128 Algorithm 3 step 5 are omitted when this setting is 1.
129 .PP
130 See \fBEVP_PKEY\-ML\-DSA\fR\|(7) for information related to \fBML-DSA\fR keys.
131 .SH NOTES
132 .IX Header "NOTES"
133 For backwards compatibility reasons \fBEVP_DigestSignInit_ex()\fR, \fBEVP_DigestSign()\fR,
134 \&\fBEVP_DigestVerifyInit_ex()\fR and \fBEVP_DigestVerify()\fR may also be used, but the digest
135 passed in \fImdname\fR must be NULL.
136 .SH EXAMPLES
137 .IX Header "EXAMPLES"
138 To sign a message using an ML-DSA EVP_PKEY structure:
139 .PP
140 .Vb 10
141 \& void do_sign(EVP_PKEY *key, unsigned char *msg, size_t msg_len)
142 \& {
143 \& size_t sig_len;
144 \& unsigned char *sig = NULL;
145 \& const OSSL_PARAM params[] = {
146 \& OSSL_PARAM_octet_string("context\-string", (unsigned char *)"A context string", 16),
147 \& OSSL_PARAM_END
148 \& };
149 \& EVP_PKEY_CTX *sctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL);
150 \& EVP_SIGNATURE *sig_alg = EVP_SIGNATURE_fetch(NULL, "ML\-DSA\-65", NULL);
151 \&
152 \& EVP_PKEY_sign_message_init(sctx, sig_alg, params);
153 \& /* Calculate the required size for the signature by passing a NULL buffer. */
154 \& EVP_PKEY_sign(sctx, NULL, &sig_len, msg, msg_len);
155 \& sig = OPENSSL_zalloc(sig_len);
156 \& EVP_PKEY_sign(sctx, sig, &sig_len, msg, msg_len);
157 \& ...
158 \& OPENSSL_free(sig);
159 \& EVP_SIGNATURE_free(sig_alg);
160 \& EVP_PKEY_CTX_free(sctx);
161 \& }
162 .Ve
163 .SH "SEE ALSO"
164 .IX Header "SEE ALSO"
165 \&\fBEVP_PKEY\-ML\-DSA\fR\|(7)
166 \&\fBprovider\-signature\fR\|(7),
167 \&\fBEVP_PKEY_sign\fR\|(3),
168 \&\fBEVP_PKEY_verify\fR\|(3),
169 FIPS 204 <https://csrc.nist.gov/pubs/fips/204/final>
170 .SH HISTORY
171 .IX Header "HISTORY"
172 This functionality was added in OpenSSL 3.5.
173 .SH COPYRIGHT
174 .IX Header "COPYRIGHT"
175 Copyright 2025\-2026 The OpenSSL Project Authors. All Rights Reserved.
176 .PP
177 Licensed under the Apache License 2.0 (the "License"). You may not use
178 this file except in compliance with the License. You can obtain a copy
179 in the file LICENSE in the source distribution or at
180 <https://www.openssl.org/source/license.html>.