Debian Codegraph @

upstream/debian-unstable/man7/EVP_SIGNATURE-SLH-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-SLH-DSA 7SSL"
58 .TH EVP_SIGNATURE-SLH-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\-SLH\-DSA,
65 EVP_SIGNATURE\-SLH\-DSA\-SHA2\-128s, EVP_SIGNATURE\-SLH\-DSA\-SHA2\-128f,
66 EVP_SIGNATURE\-SLH\-DSA\-SHA2\-192s, EVP_SIGNATURE\-SLH\-DSA\-SHA2\-192f,
67 EVP_SIGNATURE\-SLH\-DSA\-SHA2\-256s, EVP_SIGNATURE\-SLH\-DSA\-SHA2\-256f,
68 EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-128s, EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-128f,
69 EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-192s, EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-192f,
70 EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-256s, EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-256f
71 \&\- The EVP_PKEY SLH\-DSA signature implementations
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 The \fBSLH\-DSA\-SHA2\-128s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-128f\fR,
75 \&\fBSLH\-DSA\-SHA2\-192s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-192f\fR,
76 \&\fBSLH\-DSA\-SHA2\-256s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-256f\fR,
77 \&\fBSLH\-DSA\-SHAKE\-128s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-128f\fR,
78 \&\fBSLH\-DSA\-SHAKE\-192s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-192f\fR,
79 \&\fBSLH\-DSA\-SHAKE\-256s\fR and \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-256f\fR EVP_PKEY implementations
80 supports key generation, one-shot sign and verify using the SLH-DSA
81 signature schemes described in FIPS 205.
82 .PP
83 The different algorithms names correspond to the parameter sets defined in
84 FIPS 205 Section 11 Table 2.
85 \&\f(CW\*(C`s\*(C'\fR types have smaller signature sizes, and the \f(CW\*(C`f\*(C'\fR variants are faster,
86 (The signatures range from ~8K to ~50K depending on the type chosen). There are
87 3 different security categories also depending on the type.
88 .PP
89 \&\fBEVP_SIGNATURE_fetch\fR\|(3) can be used to explicitly fetch one of the 12
90 algorithms which can then be used with \fBEVP_PKEY_sign_message_init\fR\|(3),
91 \&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify_message_init\fR\|(3), and
92 \&\fBEVP_PKEY_verify\fR\|(3) to perform one-shot message signing or verification.
93 .PP
94 The normal signing process (called Pure SLH-DSA Signature Generation)
95 encodes the message internally as 0x00 || len(ctx) || ctx || message.
96 where \fBctx\fR is some optional value of size 0x00..0xFF.
97 OpenSSL also allows the message to not be encoded which is required for
98 testing. OpenSSL does not support Pre Hash SLH-DSA Signature Generation, but this
99 may be done by the user by doing Pre hash encoding externally and then choosing
100 the option to not encode the message.
101 .SS "SLH-DSA Signature Parameters"
102 .IX Subsection "SLH-DSA Signature Parameters"
103 The \f(CW\*(C`context\-string\*(C'\fR parameter, described below, can be used for both signing
104 and verification.
105 It may be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_init_ex2\fR\|(3) or
106 \&\fBEVP_PKEY_verify_init_ex2\fR\|(3)
107 .IP """context-string"" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) <octet string>" 4
108 .IX Item """context-string"" (OSSL_SIGNATURE_PARAM_CONTEXT_STRING) <octet string>"
109 A string of octets with length at most 255. By default it is the empty string.
110 .PP
111 The following parameters can be used when signing:
112 They can be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_init_ex2\fR\|(3).
113 .IP """message-encoding"" (\fBOSSL_SIGNATURE_PARAM_MESSAGE_ENCODING\fR) <integer>" 4
114 .IX Item """message-encoding"" (OSSL_SIGNATURE_PARAM_MESSAGE_ENCODING) <integer>"
115 The default value of 1 uses 'Pure SLH-DSA Signature Generation' as described
116 above. Setting it to 0 does not encode the message, which is used for testing,
117 but can also be used for 'Pre Hash SLH-DSA Signature Generation'.
118 .IP """test-entropy"" (\fBOSSL_SIGNATURE_PARAM_TEST_ENTROPY <octet string\fR" 4
119 .IX Item """test-entropy"" (OSSL_SIGNATURE_PARAM_TEST_ENTROPY <octet string"
120 Used for testing to pass a optional random value.
121 .IP """deterministic"" (\fBOSSL_SIGNATURE_PARAM_DETERMINISTIC\fR) <integer>" 4
122 .IX Item """deterministic"" (OSSL_SIGNATURE_PARAM_DETERMINISTIC) <integer>"
123 The default value of 0 generates a random value (using a DRBG) this is used when
124 processing the message. Setting this to 1 causes the private key seed to be used
125 instead. This value is ignored if "test-entropy" is set.
126 .PP
127 See \fBEVP_PKEY\-SLH\-DSA\fR\|(7) for information related to \fBSLH-DSA\fR keys.
128 .SH NOTES
129 .IX Header "NOTES"
130 For backwards compatibility reasons \fBEVP_DigestSignInit_ex()\fR, \fBEVP_DigestSign()\fR,
131 \&\fBEVP_DigestVerifyInit_ex()\fR and \fBEVP_DigestVerify()\fR may also be used, but the digest
132 passed in \fImdname\fR must be NULL.
133 .SH EXAMPLES
134 .IX Header "EXAMPLES"
135 To sign a message using an SLH-DSA EVP_PKEY structure:
136 .PP
137 .Vb 10
138 \& void do_sign(EVP_PKEY *key, unsigned char *msg, size_t msg_len)
139 \& {
140 \& size_t sig_len;
141 \& unsigned char *sig = NULL;
142 \& const OSSL_PARAM params[] = {
143 \& OSSL_PARAM_octet_string("context\-string", (unsigned char *)"A context string", 33),
144 \& OSSL_PARAM_END
145 \& };
146 \& EVP_PKEY_CTX *sctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL);
147 \& EVP_SIGNATURE *sig_alg = EVP_SIGNATURE_fetch(NULL, "SLH\-DSA\-SHA2\-128s", NULL);
148 \&
149 \& EVP_PKEY_sign_message_init(sctx, sig_alg, params);
150 \& /* Calculate the required size for the signature by passing a NULL buffer. */
151 \& EVP_PKEY_sign(sctx, NULL, &sig_len, msg, msg_len);
152 \& sig = OPENSSL_zalloc(sig_len);
153 \& EVP_PKEY_sign(sctx, sig, &sig_len, msg, msg_len);
154 \& ...
155 \& OPENSSL_free(sig);
156 \& EVP_SIGNATURE_free(sig_alg);
157 \& EVP_PKEY_CTX_free(sctx);
158 \& }
159 .Ve
160 .SH "SEE ALSO"
161 .IX Header "SEE ALSO"
162 \&\fBEVP_PKEY\-SLH\-DSA\fR\|(7)
163 \&\fBprovider\-signature\fR\|(7),
164 \&\fBEVP_PKEY_sign\fR\|(3),
165 \&\fBEVP_PKEY_verify\fR\|(3),
166 .SH HISTORY
167 .IX Header "HISTORY"
168 This functionality was added in OpenSSL 3.5.
169 .SH COPYRIGHT
170 .IX Header "COPYRIGHT"
171 Copyright 2024\-2026 The OpenSSL Project Authors. All Rights Reserved.
172 .PP
173 Licensed under the Apache License 2.0 (the "License"). You may not use
174 this file except in compliance with the License. You can obtain a copy
175 in the file LICENSE in the source distribution or at
176 <https://www.openssl.org/source/license.html>.