Debian Codegraph @

upstream/debian-unstable/man7/provider-signature.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 "PROVIDER-SIGNATURE 7SSL"
58 .TH PROVIDER-SIGNATURE 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 provider\-signature \- The signature library <\-> provider functions
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& #include <openssl/core_dispatch.h>
69 \& #include <openssl/core_names.h>
70 \&
71 \& /*
72 \& * None of these are actual functions, but are displayed like this for
73 \& * the function signatures for functions that are offered as function
74 \& * pointers in OSSL_DISPATCH arrays.
75 \& */
76 \&
77 \& /* Context management */
78 \& void *OSSL_FUNC_signature_newctx(void *provctx, const char *propq);
79 \& void OSSL_FUNC_signature_freectx(void *ctx);
80 \& void *OSSL_FUNC_signature_dupctx(void *ctx);
81 \&
82 \& /* Get the key types that a signature algorithm supports */
83 \& const char **OSSL_FUNC_signature_query_key_types(void);
84 \&
85 \& /* Signing */
86 \& int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey,
87 \& const OSSL_PARAM params[]);
88 \& int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen,
89 \& size_t sigsize, const unsigned char *tbs, size_t tbslen);
90 \& int OSSL_FUNC_signature_sign_message_init(void *ctx, void *provkey,
91 \& const OSSL_PARAM params[]);
92 \& int OSSL_FUNC_signature_sign_message_update(void *ctx, const unsigned char *in,
93 \& size_t inlen);
94 \& int OSSL_FUNC_signature_sign_message_final(void *ctx, unsigned char *sig,
95 \& size_t *siglen, size_t sigsize);
96 \&
97 \& /* Verifying */
98 \& int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey,
99 \& const OSSL_PARAM params[]);
100 \& int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen,
101 \& const unsigned char *tbs, size_t tbslen);
102 \& int OSSL_FUNC_signature_verify_message_init(void *ctx, void *provkey,
103 \& const OSSL_PARAM params[]);
104 \& int OSSL_FUNC_signature_verify_message_update(void *ctx, const unsigned char *in,
105 \& size_t inlen);
106 \& /*
107 \& * OSSL_FUNC_signature_verify_message_final requires that the signature to be
108 \& * verified is specified via a "signature" OSSL_PARAM, which is given with a
109 \& * previous call of OSSL_FUNC_signature_set_ctx_params().
110 \& */
111 \& int OSSL_FUNC_signature_verify_message_final(void *ctx);
112 \&
113 \& /* Verify Recover */
114 \& int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey,
115 \& const OSSL_PARAM params[]);
116 \& int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout,
117 \& size_t *routlen, size_t routsize,
118 \& const unsigned char *sig, size_t siglen);
119 \&
120 \& /* Digest Sign */
121 \& int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname,
122 \& void *provkey,
123 \& const OSSL_PARAM params[]);
124 \& int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data,
125 \& size_t datalen);
126 \& int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig,
127 \& size_t *siglen, size_t sigsize);
128 \& int OSSL_FUNC_signature_digest_sign(void *ctx,
129 \& unsigned char *sig, size_t *siglen,
130 \& size_t sigsize, const unsigned char *tbs,
131 \& size_t tbslen);
132 \&
133 \& /* Digest Verify */
134 \& int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname,
135 \& void *provkey,
136 \& const OSSL_PARAM params[]);
137 \& int OSSL_FUNC_signature_digest_verify_update(void *ctx,
138 \& const unsigned char *data,
139 \& size_t datalen);
140 \& int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig,
141 \& size_t siglen);
142 \& int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig,
143 \& size_t siglen, const unsigned char *tbs,
144 \& size_t tbslen);
145 \&
146 \& /* Signature parameters */
147 \& int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]);
148 \& const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void *ctx,
149 \& void *provctx);
150 \& int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
151 \& const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void *ctx,
152 \& void *provctx);
153 \& /* MD parameters */
154 \& int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]);
155 \& const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx);
156 \& int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]);
157 \& const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx);
158 .Ve
159 .SH DESCRIPTION
160 .IX Header "DESCRIPTION"
161 This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7)
162 for further information.
163 .PP
164 The signature (OSSL_OP_SIGNATURE) operation enables providers to implement
165 signature algorithms and make them available to applications via the API
166 functions \fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify\fR\|(3),
167 and \fBEVP_PKEY_verify_recover\fR\|(3) (as well as other related functions).
168 .PP
169 All "functions" mentioned here are passed as function pointers between
170 \&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via
171 \&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider's
172 \&\fBprovider_query_operation()\fR function
173 (see "Provider Functions" in \fBprovider\-base\fR\|(7)).
174 .PP
175 All these "functions" have a corresponding function type definition
176 named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the
177 function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named
178 \&\fBOSSL_FUNC_{name}\fR.
179 For example, the "function" \fBOSSL_FUNC_signature_newctx()\fR has these:
180 .PP
181 .Vb 3
182 \& typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx, const char *propq);
183 \& static ossl_inline OSSL_FUNC_signature_newctx_fn
184 \& OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf);
185 .Ve
186 .PP
187 \&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as
188 macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
189 .PP
190 .Vb 3
191 \& OSSL_FUNC_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX
192 \& OSSL_FUNC_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX
193 \& OSSL_FUNC_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX
194 \&
195 \& OSSL_FUNC_signature_query_key_types OSSL_FUNC_SIGNATURE_QUERY_KEY_TYPES
196 \&
197 \& OSSL_FUNC_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT
198 \& OSSL_FUNC_signature_sign OSSL_FUNC_SIGNATURE_SIGN
199 \& OSSL_FUNC_signature_sign_message_init OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_INIT
200 \& OSSL_FUNC_signature_sign_message_update OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_UPDATE
201 \& OSSL_FUNC_signature_sign_message_final OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_FINAL
202 \&
203 \& OSSL_FUNC_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT
204 \& OSSL_FUNC_signature_verify OSSL_FUNC_SIGNATURE_VERIFY
205 \& OSSL_FUNC_signature_verify_message_init OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_INIT
206 \& OSSL_FUNC_signature_verify_message_update OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_UPDATE
207 \& OSSL_FUNC_signature_verify_message_final OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_FINAL
208 \&
209 \& OSSL_FUNC_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
210 \& OSSL_FUNC_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER
211 \&
212 \& OSSL_FUNC_signature_digest_sign_init OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT
213 \& OSSL_FUNC_signature_digest_sign_update OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE
214 \& OSSL_FUNC_signature_digest_sign_final OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL
215 \& OSSL_FUNC_signature_digest_sign OSSL_FUNC_SIGNATURE_DIGEST_SIGN
216 \&
217 \& OSSL_FUNC_signature_digest_verify_init OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT
218 \& OSSL_FUNC_signature_digest_verify_update OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE
219 \& OSSL_FUNC_signature_digest_verify_final OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL
220 \& OSSL_FUNC_signature_digest_verify OSSL_FUNC_SIGNATURE_DIGEST_VERIFY
221 \&
222 \& OSSL_FUNC_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS
223 \& OSSL_FUNC_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS
224 \& OSSL_FUNC_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS
225 \& OSSL_FUNC_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS
226 \&
227 \& OSSL_FUNC_signature_get_ctx_md_params OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS
228 \& OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS
229 \& OSSL_FUNC_signature_set_ctx_md_params OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS
230 \& OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS
231 .Ve
232 .PP
233 A signature algorithm implementation may not implement all of these functions.
234 In order to be a consistent set of functions we must have at least a set of
235 context functions (OSSL_FUNC_signature_newctx and OSSL_FUNC_signature_freectx) as well as a
236 set of "signature" functions, i.e. at least one of:
237 .IP "OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign" 4
238 .IX Item "OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign"
239 Used via \fBEVP_PKEY_sign_init\fR\|(3) and \fBEVP_PKEY_sign\fR\|(3).
240 These functions operate on pre-digested data (the "to be signed" or TBS value).
241 .IP "OSSL_FUNC_signature_sign_message_init and OSSL_FUNC_signature_sign" 4
242 .IX Item "OSSL_FUNC_signature_sign_message_init and OSSL_FUNC_signature_sign"
243 Used via \fBEVP_PKEY_sign_message_init\fR\|(3) and \fBEVP_PKEY_sign\fR\|(3) when signing a complete message.
244 The implementation internally handles message digesting.
245 .IP "OSSL_FUNC_signature_sign_message_init, OSSL_FUNC_signature_sign_message_update and OSSL_FUNC_signature_sign_message_final" 4
246 .IX Item "OSSL_FUNC_signature_sign_message_init, OSSL_FUNC_signature_sign_message_update and OSSL_FUNC_signature_sign_message_final"
247 Streaming variant of message signing, used via \fBEVP_PKEY_sign_message_init\fR\|(3),
248 \&\fBEVP_PKEY_sign_message_update\fR\|(3), and \fBEVP_PKEY_sign_message_final\fR\|(3).
249 .IP "OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify" 4
250 .IX Item "OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify"
251 Used via \fBEVP_PKEY_verify_init\fR\|(3) and \fBEVP_PKEY_verify\fR\|(3).
252 These functions operate on pre-digested data.
253 .IP "OSSL_FUNC_signature_verify_message_init and OSSL_FUNC_signature_verify" 4
254 .IX Item "OSSL_FUNC_signature_verify_message_init and OSSL_FUNC_signature_verify"
255 Used via \fBEVP_PKEY_verify_message_init\fR\|(3) and \fBEVP_PKEY_verify\fR\|(3) when verifying a complete message.
256 The implementation internally handles message digesting.
257 .IP "OSSL_FUNC_signature_verify_message_init, OSSL_FUNC_signature_verify_message_update and OSSL_FUNC_signature_verify_message_final" 4
258 .IX Item "OSSL_FUNC_signature_verify_message_init, OSSL_FUNC_signature_verify_message_update and OSSL_FUNC_signature_verify_message_final"
259 Streaming variant of message verification, used via \fBEVP_PKEY_verify_message_init\fR\|(3),
260 \&\fBEVP_PKEY_verify_message_update\fR\|(3), and \fBEVP_PKEY_verify_message_final\fR\|(3).
261 .IP "OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover" 4
262 .IX Item "OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover"
263 Used via \fBEVP_PKEY_verify_recover_init\fR\|(3) and \fBEVP_PKEY_verify_recover\fR\|(3).
264 Applicable only to signature schemes that support signature recovery (such as RSA).
265 .IP "OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final" 4
266 .IX Item "OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final"
267 Streaming digest-sign variant, used via \fBEVP_DigestSignInit\fR\|(3),
268 \&\fBEVP_DigestSignUpdate\fR\|(3), and \fBEVP_DigestSignFinal\fR\|(3).
269 .IP "OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final" 4
270 .IX Item "OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final"
271 Streaming digest-verify variant, used via \fBEVP_DigestVerifyInit\fR\|(3),
272 \&\fBEVP_DigestVerifyUpdate\fR\|(3), and \fBEVP_DigestVerifyFinal\fR\|(3).
273 .IP "OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign" 4
274 .IX Item "OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign"
275 One-shot digest-sign variant, used via \fBEVP_DigestSign\fR\|(3).
276 .IP "OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify" 4
277 .IX Item "OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify"
278 One-shot digest-verify variant, used via \fBEVP_DigestVerify\fR\|(3).
279 .PP
280 \&\fBImportant Note for TLS Support:\fR For a provider signature implementation to
281 be usable within \fIlibssl\fR for TLS connections, it \fBmust\fR implement the
282 digest-sign and digest-verify functions
283 (OSSL_FUNC_signature_digest_sign_init/update/final or the one-shot variant, and
284 OSSL_FUNC_signature_digest_verify_init/update/final or the one-shot variant).
285 The TLS handshake code in \fIlibssl\fR specifically requires these digest functions
286 and will not use implementations that only provide the basic sign/verify functions
287 (OSSL_FUNC_signature_sign_init/sign or OSSL_FUNC_signature_verify_init/verify).
288 .PP
289 The choice of which function set to implement depends on your use case:
290 .IP \(bu 4
291 For general-purpose signature operations and TLS support: implement the
292 digest-sign and digest-verify functions.
293 .IP \(bu 4
294 For operations on pre-digested data only: implement the basic sign and verify
295 functions.
296 .IP \(bu 4
297 For signature schemes with recovery capability: additionally implement the
298 verify-recover functions.
299 .PP
300 The \fBOSSL_FUNC_signature_set_ctx_params()\fR and
301 \&\fBOSSL_FUNC_signature_settable_ctx_params()\fR functions are optional,
302 but if one of them is provided then the other one must also be provided.
303 The same applies to the \fBOSSL_FUNC_signature_get_ctx_params()\fR and
304 \&\fBOSSL_FUNC_signature_gettable_ctx_params()\fR functions,
305 as well as the "md_params" functions.
306 .PP
307 The \fBOSSL_FUNC_signature_dupctx()\fR function is optional.
308 It is not yet used by OpenSSL.
309 .PP
310 The \fBOSSL_FUNC_signature_query_key_types()\fR function is optional.
311 When present, it should return a NULL-terminated array of strings
312 indicating the key types supported by the provider for signature operations.
313 Otherwise the signature algorithm name must match the given key
314 or match the default signature algorithm name of the key,
315 both checked using \fBEVP_SIGNATURE_is_a\fR\|(3).
316 .PP
317 A signature algorithm must also implement some mechanism for generating,
318 loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
319 See \fBprovider\-keymgmt\fR\|(7) for further details.
320 .SS "Context Management Functions"
321 .IX Subsection "Context Management Functions"
322 \&\fBOSSL_FUNC_signature_newctx()\fR should create and return a pointer to a provider side
323 structure for holding context information during a signature operation.
324 A pointer to this context will be passed back in a number of the other signature
325 operation function calls.
326 The parameter \fIprovctx\fR is the provider context generated during provider
327 initialisation (see \fBprovider\fR\|(7)). The \fIpropq\fR parameter is a property query
328 string that may be (optionally) used by the provider during any "fetches" that
329 it may perform (if it performs any).
330 .PP
331 \&\fBOSSL_FUNC_signature_freectx()\fR is passed a pointer to the provider side signature
332 context in the \fIctx\fR parameter.
333 This function should free any resources associated with that context.
334 .PP
335 \&\fBOSSL_FUNC_signature_dupctx()\fR should duplicate the provider side signature context in
336 the \fIctx\fR parameter and return the duplicate copy.
337 .SS "Signing Functions"
338 .IX Subsection "Signing Functions"
339 \&\fBOSSL_FUNC_signature_sign_init()\fR initialises a context for signing given a provider side
340 signature context in the \fIctx\fR parameter, and a pointer to a provider key object
341 in the \fIprovkey\fR parameter.
342 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
343 using \fBOSSL_FUNC_signature_set_ctx_params()\fR.
344 The key object should have been previously generated, loaded or imported into
345 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
346 \&\fBprovider\-keymgmt\fR\|(7)).
347 .PP
348 \&\fBOSSL_FUNC_signature_sign()\fR performs the actual signing itself.
349 A previously initialised signature context is passed in the \fIctx\fR
350 parameter.
351 The data to be signed is pointed to be the \fItbs\fR parameter which is \fItbslen\fR
352 bytes long.
353 Unless \fIsig\fR is NULL, the signature should be written to the location pointed
354 to by the \fIsig\fR parameter and it should not exceed \fIsigsize\fR bytes in length.
355 The length of the signature should be written to \fI*siglen\fR.
356 If \fIsig\fR is NULL then the maximum length of the signature should be written to
357 \&\fI*siglen\fR.
358 .SS "Message Signing Functions"
359 .IX Subsection "Message Signing Functions"
360 These functions are suitable for providers that implement algorithms that
361 accumulate a full message and sign the result of that accumulation, such as
362 RSA\-SHA256.
363 .PP
364 \&\fBOSSL_FUNC_signature_sign_message_init()\fR initialises a context for signing a
365 message given a provider side signature context in the \fIctx\fR parameter, and a
366 pointer to a provider key object in the \fIprovkey\fR parameter.
367 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
368 using \fBOSSL_FUNC_signature_set_ctx_params()\fR.
369 The key object should have been previously generated, loaded or imported into
370 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
371 \&\fBprovider\-keymgmt\fR\|(7)).
372 .PP
373 \&\fBOSSL_FUNC_signature_sign_message_update()\fR gathers the data pointed at by
374 \&\fIin\fR, which is \fIinlen\fR bytes long.
375 .PP
376 \&\fBOSSL_FUNC_signature_sign_message_final()\fR performs the actual signing on the
377 data that was gathered with \fBOSSL_FUNC_signature_sign_message_update()\fR.
378 .PP
379 \&\fBOSSL_FUNC_signature_sign()\fR can be used for one-shot signature calls. In that
380 case, \fItbs\fR is expected to be the whole message to be signed, \fItbslen\fR bytes
381 long.
382 .PP
383 For both \fBOSSL_FUNC_signature_sign_message_final()\fR and \fBOSSL_FUNC_signature_sign()\fR,
384 if \fIsig\fR is not NULL, the signature should be written to the location pointed
385 to by \fIsig\fR, and it should not exceed \fIsigsize\fR bytes in length.
386 The length of the signature should be written to \fI*siglen\fR.
387 If \fIsig\fR is NULL then the maximum length of the signature should be written to
388 \&\fI*siglen\fR.
389 .SS "Verify Functions"
390 .IX Subsection "Verify Functions"
391 \&\fBOSSL_FUNC_signature_verify_init()\fR initialises a context for verifying a signature given
392 a provider side signature context in the \fIctx\fR parameter, and a pointer to a
393 provider key object in the \fIprovkey\fR parameter.
394 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
395 using \fBOSSL_FUNC_signature_set_ctx_params()\fR.
396 The key object should have been previously generated, loaded or imported into
397 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
398 \&\fBprovider\-keymgmt\fR\|(7)).
399 .PP
400 \&\fBOSSL_FUNC_signature_verify()\fR performs the actual verification itself.
401 A previously initialised signature context is passed in the \fIctx\fR parameter.
402 The data that the signature covers is pointed to be the \fItbs\fR parameter which
403 is \fItbslen\fR bytes long.
404 The signature is pointed to by the \fIsig\fR parameter which is \fIsiglen\fR bytes
405 long.
406 .SS "Message Verify Functions"
407 .IX Subsection "Message Verify Functions"
408 These functions are suitable for providers that implement algorithms that
409 accumulate a full message and verify a signature on the result of that
410 accumulation, such as RSA\-SHA256.
411 .PP
412 \&\fBOSSL_FUNC_signature_verify_message_init()\fR initialises a context for verifying
413 a signature on a message given a provider side signature context in the \fIctx\fR
414 parameter, and a pointer to a provider key object in the \fIprovkey\fR parameter.
415 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
416 using \fBOSSL_FUNC_signature_set_ctx_params()\fR.
417 The key object should have been previously generated, loaded or imported into
418 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
419 \&\fBprovider\-keymgmt\fR\|(7)).
420 .PP
421 \&\fBOSSL_FUNC_signature_verify_message_update()\fR gathers the data pointed at by
422 \&\fIin\fR, which is \fIinlen\fR bytes long.
423 .PP
424 \&\fBOSSL_FUNC_signature_verify_message_final()\fR performs the actual verification on
425 the data that was gathered with \fBOSSL_FUNC_signature_verify_message_update()\fR.
426 The signature itself must have been passed through the "signature"
427 (\fBOSSL_SIGNATURE_PARAM_SIGNATURE\fR) Signature parameter
428 before this function is called.
429 .PP
430 \&\fBOSSL_FUNC_signature_verify()\fR can be used for one-shot verification calls. In
431 that case, \fItbs\fR is expected to be the whole message to be verified on,
432 \&\fItbslen\fR bytes long.
433 .SS "Verify Recover Functions"
434 .IX Subsection "Verify Recover Functions"
435 \&\fBOSSL_FUNC_signature_verify_recover_init()\fR initialises a context for recovering the
436 signed data given a provider side signature context in the \fIctx\fR parameter, and
437 a pointer to a provider key object in the \fIprovkey\fR parameter.
438 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
439 using \fBOSSL_FUNC_signature_set_ctx_params()\fR.
440 The key object should have been previously generated, loaded or imported into
441 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
442 \&\fBprovider\-keymgmt\fR\|(7)).
443 .PP
444 \&\fBOSSL_FUNC_signature_verify_recover()\fR performs the actual verify recover itself.
445 A previously initialised signature context is passed in the \fIctx\fR parameter.
446 The signature is pointed to by the \fIsig\fR parameter which is \fIsiglen\fR bytes
447 long.
448 Unless \fIrout\fR is NULL, the recovered data should be written to the location
449 pointed to by \fIrout\fR which should not exceed \fIroutsize\fR bytes in length.
450 The length of the recovered data should be written to \fI*routlen\fR.
451 If \fIrout\fR is NULL then the maximum size of the output buffer is written to
452 the \fIroutlen\fR parameter.
453 .SS "Digest Sign Functions"
454 .IX Subsection "Digest Sign Functions"
455 \&\fBOSSL_FUNC_signature_digest_sign_init()\fR initialises a context for signing given a
456 provider side signature context in the \fIctx\fR parameter, and a pointer to a
457 provider key object in the \fIprovkey\fR parameter.
458 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
459 using \fBOSSL_FUNC_signature_set_ctx_params()\fR and
460 \&\fBOSSL_FUNC_signature_set_ctx_md_params()\fR.
461 The key object should have been
462 previously generated, loaded or imported into the provider using the
463 key management (OSSL_OP_KEYMGMT) operation (see \fBprovider\-keymgmt\fR\|(7)).
464 The name of the digest to be used will be in the \fImdname\fR parameter.
465 .PP
466 \&\fBOSSL_FUNC_signature_digest_sign_update()\fR provides data to be signed in the \fIdata\fR
467 parameter which should be of length \fIdatalen\fR. A previously initialised
468 signature context is passed in the \fIctx\fR parameter. This function may be called
469 multiple times to cumulatively add data to be signed.
470 .PP
471 \&\fBOSSL_FUNC_signature_digest_sign_final()\fR finalises a signature operation previously
472 started through \fBOSSL_FUNC_signature_digest_sign_init()\fR and
473 \&\fBOSSL_FUNC_signature_digest_sign_update()\fR calls. Once finalised no more data will be
474 added through \fBOSSL_FUNC_signature_digest_sign_update()\fR. A previously initialised
475 signature context is passed in the \fIctx\fR parameter. Unless \fIsig\fR is NULL, the
476 signature should be written to the location pointed to by the \fIsig\fR parameter
477 and it should not exceed \fIsigsize\fR bytes in length. The length of the signature
478 should be written to \fI*siglen\fR. If \fIsig\fR is NULL then the maximum length of
479 the signature should be written to \fI*siglen\fR.
480 .PP
481 \&\fBOSSL_FUNC_signature_digest_sign()\fR implements a "one shot" digest sign operation
482 previously started through \fBOSSL_FUNC_signature_digest_sign_init()\fR. A previously
483 initialised signature context is passed in the \fIctx\fR parameter. The data to be
484 signed is in \fItbs\fR which should be \fItbslen\fR bytes long. Unless \fIsig\fR is NULL,
485 the signature should be written to the location pointed to by the \fIsig\fR
486 parameter and it should not exceed \fIsigsize\fR bytes in length. The length of the
487 signature should be written to \fI*siglen\fR. If \fIsig\fR is NULL then the maximum
488 length of the signature should be written to \fI*siglen\fR.
489 .SS "Digest Verify Functions"
490 .IX Subsection "Digest Verify Functions"
491 \&\fBOSSL_FUNC_signature_digest_verify_init()\fR initialises a context for verifying given a
492 provider side verification context in the \fIctx\fR parameter, and a pointer to a
493 provider key object in the \fIprovkey\fR parameter.
494 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
495 \&\fBOSSL_FUNC_signature_set_ctx_params()\fR and
496 \&\fBOSSL_FUNC_signature_set_ctx_md_params()\fR.
497 The key object should have been
498 previously generated, loaded or imported into the provider using the
499 key management (OSSL_OP_KEYMGMT) operation (see \fBprovider\-keymgmt\fR\|(7)).
500 The name of the digest to be used will be in the \fImdname\fR parameter.
501 .PP
502 \&\fBOSSL_FUNC_signature_digest_verify_update()\fR provides data to be verified in the \fIdata\fR
503 parameter which should be of length \fIdatalen\fR. A previously initialised
504 verification context is passed in the \fIctx\fR parameter. This function may be
505 called multiple times to cumulatively add data to be verified.
506 .PP
507 \&\fBOSSL_FUNC_signature_digest_verify_final()\fR finalises a verification operation previously
508 started through \fBOSSL_FUNC_signature_digest_verify_init()\fR and
509 \&\fBOSSL_FUNC_signature_digest_verify_update()\fR calls. Once finalised no more data will be
510 added through \fBOSSL_FUNC_signature_digest_verify_update()\fR. A previously initialised
511 verification context is passed in the \fIctx\fR parameter. The signature to be
512 verified is in \fIsig\fR which is \fIsiglen\fR bytes long.
513 .PP
514 \&\fBOSSL_FUNC_signature_digest_verify()\fR implements a "one shot" digest verify operation
515 previously started through \fBOSSL_FUNC_signature_digest_verify_init()\fR. A previously
516 initialised verification context is passed in the \fIctx\fR parameter. The data to be
517 verified is in \fItbs\fR which should be \fItbslen\fR bytes long. The signature to be
518 verified is in \fIsig\fR which is \fIsiglen\fR bytes long.
519 .SS "Signature parameters"
520 .IX Subsection "Signature parameters"
521 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by
522 the \fBOSSL_FUNC_signature_get_ctx_params()\fR and \fBOSSL_FUNC_signature_set_ctx_params()\fR functions.
523 .PP
524 \&\fBOSSL_FUNC_signature_get_ctx_params()\fR gets signature parameters associated with the
525 given provider side signature context \fIctx\fR and stored them in \fIparams\fR.
526 Passing NULL for \fIparams\fR should return true.
527 .PP
528 \&\fBOSSL_FUNC_signature_set_ctx_params()\fR sets the signature parameters associated with the
529 given provider side signature context \fIctx\fR to \fIparams\fR.
530 Any parameter settings are additional to any that were previously set.
531 Passing NULL for \fIparams\fR should return true.
532 .PP
533 Common parameters currently recognised by built-in signature algorithms are as
534 follows.
535 .IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) <UTF8 string>" 4
536 .IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>"
537 Get or sets the name of the digest algorithm used for the input to the
538 signature functions. It is required in order to calculate the "algorithm-id".
539 .IP """properties"" (\fBOSSL_SIGNATURE_PARAM_PROPERTIES\fR) <UTF8 string>" 4
540 .IX Item """properties"" (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>"
541 Sets the name of the property query associated with the "digest" algorithm.
542 NULL is used if this optional value is not set.
543 .PP
544 Note that when implementing a signature algorithm that gathers a full message,
545 like RSA\-SHA256, the "digest" and "properties" parameters should not be used.
546 For such implementations, it's acceptable to simply ignore them if they happen
547 to be passed in a call to \fBOSSL_FUNC_signature_set_ctx_params()\fR. For such
548 implementations, however, it is not acceptable to have them in the \fBOSSL_PARAM\fR
549 array that's returned by \fBOSSL_FUNC_signature_settable_ctx_params()\fR.
550 .IP """signature"" (\fBOSSL_SIGNATURE_PARAM_SIGNATURE\fR) <octet string>" 4
551 .IX Item """signature"" (OSSL_SIGNATURE_PARAM_SIGNATURE) <octet string>"
552 Sets the signature to verify, specifically when
553 \&\fBOSSL_FUNC_signature_verify_message_final()\fR is used.
554 .IP """digest-size"" (\fBOSSL_SIGNATURE_PARAM_DIGEST_SIZE\fR) <unsigned integer>" 4
555 .IX Item """digest-size"" (OSSL_SIGNATURE_PARAM_DIGEST_SIZE) <unsigned integer>"
556 Gets or sets the output size of the digest algorithm used for the input to the
557 signature functions.
558 The length of the "digest-size" parameter should not exceed that of a \fBsize_t\fR.
559 .IP """algorithm-id"" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) <octet string>" 4
560 .IX Item """algorithm-id"" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>"
561 Gets the DER-encoded AlgorithmIdentifier for the signature operation.
562 This typically corresponds to the combination of a digest algorithm
563 with a purely asymmetric signature algorithm, such as SHA256WithECDSA.
564 .Sp
565 The \fBASN1_item_sign_ctx\fR\|(3) function relies on this operation and is used by
566 many other functions that sign ASN.1 structures such as X.509 certificates,
567 certificate requests, and CRLs, as well as OCSP, CMP, and CMS messages.
568 .IP """nonce-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) <unsigned integer>" 4
569 .IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>"
570 Set this to 1 to use deterministic digital signature generation with
571 ECDSA or DSA, as defined in RFC 6979 (see Section 3.2 "Generation of
572 k"). In this case, the "digest" parameter must be explicitly set
573 (otherwise, deterministic nonce generation will fail). Before using
574 deterministic digital signature generation, please read RFC 6979
575 Section 4 "Security Considerations". The default value for
576 "nonce-type" is 0 and results in a random value being used for the
577 nonce \fBk\fR as defined in FIPS 186\-4 Section 6.3 "Secret Number
578 Generation".
579 .Sp
580 The FIPS provider does not support deterministic digital signature generation
581 for DSA.
582 .Sp
583 The FIPS provider supports deterministic digital signature generation for
584 ECDSA.
585 .IP """kat"" (\fBOSSL_SIGNATURE_PARAM_KAT\fR) <unsigned integer>" 4
586 .IX Item """kat"" (OSSL_SIGNATURE_PARAM_KAT) <unsigned integer>"
587 Sets a flag to modify the sign operation to return an error if the initial
588 calculated signature is invalid.
589 In the normal mode of operation \- new random values are chosen until the
590 signature operation succeeds.
591 By default it retries until a signature is calculated.
592 Setting the value to 0 causes the sign operation to retry,
593 otherwise the sign operation is only tried once and returns whether or not it
594 was successful.
595 Known answer tests can be performed if the random generator is overridden to
596 supply known values that either pass or fail.
597 .PP
598 The following parameters are used by the OpenSSL FIPS provider:
599 .IP """fips-indicator"" (\fBOSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR\fR) <integer>" 4
600 .IX Item """fips-indicator"" (OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR) <integer>"
601 A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
602 This may be used after calling either the sign or verify final functions. It may
603 return 0 if either the "digest-check", "key-check", or "sign-check" are set to 0.
604 .IP """verify-message"" (\fBOSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE\fR <integer>" 4
605 .IX Item """verify-message"" (OSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE <integer>"
606 A getter that returns 1 if a signature verification operation acted on
607 a raw message, or 0 if it verified a predigested message. A value of 0
608 indicates likely non-approved usage of the FIPS provider. This flag is
609 set when any signature verification initialisation function is called.
610 It is also set to 1 when any signing operation is performed to signify
611 compliance. See FIPS 140\-3 IG 2.4.B for further information.
612 .IP """key-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK\fR) <integer>" 4
613 .IX Item """key-check"" (OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK) <integer>"
614 If required this parameter should be set early via an init function
615 (e.g. \fBOSSL_FUNC_signature_sign_init()\fR or \fBOSSL_FUNC_signature_verify_init()\fR).
616 The default value of 1 causes an error during the init if the key is not FIPS
617 approved (e.g. The key has a security strength of less than 112 bits).
618 Setting this to 0 will ignore the error and set the approved "indicator" to 0.
619 This option breaks FIPS compliance if it causes the approved "fips-indicator"
620 to return 0.
621 .IP """digest-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK\fR) <integer>" 4
622 .IX Item """digest-check"" (OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK) <integer>"
623 If required this parameter should be set before the signature digest is set.
624 The default value of 1 causes an error when the digest is set if the digest is
625 not FIPS approved (e.g. SHA1 is used for signing). Setting this to 0 will ignore
626 the error and set the approved "fips-indicator" to 0.
627 This option breaks FIPS compliance if it causes the approved "fips-indicator"
628 to return 0.
629 .IP """sign-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_SIGN_CHECK\fR) <integer>" 4
630 .IX Item """sign-check"" (OSSL_SIGNATURE_PARAM_FIPS_SIGN_CHECK) <integer>"
631 If required this parameter should be set early via an init function.
632 The default value of 1 causes an error when a signing algorithm is used. (This
633 is triggered by deprecated signing algorithms).
634 Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0.
635 This option breaks FIPS compliance if it causes the approved "fips-indicator" to
636 return 0.
637 .IP """sign\-x931\-pad\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK\fR) <integer>" 4
638 .IX Item """sign-x931-pad-check"" (OSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK) <integer>"
639 If required this parameter should be set before the padding mode is set.
640 The default value of 1 causes an error if the padding mode is set to X9.31 padding
641 for a RSA signing operation. Setting this to 0 will ignore the error and set the
642 approved "fips-indicator" to 0.
643 This option breaks FIPS compliance if it causes the approved "fips-indicator"
644 to return 0.
645 .PP
646 \&\fBOSSL_FUNC_signature_gettable_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_ctx_params()\fR get a
647 constant \fBOSSL_PARAM\fR\|(3) array that describes the gettable and settable parameters,
648 i.e. parameters that can be used with \fBOSSL_FUNC_signature_get_ctx_params()\fR and
649 \&\fBOSSL_FUNC_signature_set_ctx_params()\fR respectively.
650 .SS "MD parameters"
651 .IX Subsection "MD parameters"
652 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by
653 the \fBOSSL_FUNC_signature_get_md_ctx_params()\fR and \fBOSSL_FUNC_signature_set_md_ctx_params()\fR
654 functions.
655 .PP
656 \&\fBOSSL_FUNC_signature_get_md_ctx_params()\fR gets digest parameters associated with the
657 given provider side digest signature context \fIctx\fR and stores them in \fIparams\fR.
658 Passing NULL for \fIparams\fR should return true.
659 .PP
660 \&\fBOSSL_FUNC_signature_set_ms_ctx_params()\fR sets the digest parameters associated with the
661 given provider side digest signature context \fIctx\fR to \fIparams\fR.
662 Any parameter settings are additional to any that were previously set.
663 Passing NULL for \fIparams\fR should return true.
664 .PP
665 Parameters currently recognised by built-in signature algorithms are the same
666 as those for built-in digest algorithms. See
667 "Digest Parameters" in \fBprovider\-digest\fR\|(7) for further information.
668 .PP
669 \&\fBOSSL_FUNC_signature_gettable_md_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_md_ctx_params()\fR
670 get a constant \fBOSSL_PARAM\fR\|(3) array that describes the gettable and settable
671 digest parameters, i.e. parameters that can be used with
672 \&\fBOSSL_FUNC_signature_get_md_ctx_params()\fR and \fBOSSL_FUNC_signature_set_md_ctx_params()\fR
673 respectively.
674 .SH "RETURN VALUES"
675 .IX Header "RETURN VALUES"
676 \&\fBOSSL_FUNC_signature_newctx()\fR and \fBOSSL_FUNC_signature_dupctx()\fR should return the newly created
677 provider side signature context, or NULL on failure.
678 .PP
679 \&\fBOSSL_FUNC_signature_gettable_ctx_params()\fR, \fBOSSL_FUNC_signature_settable_ctx_params()\fR,
680 \&\fBOSSL_FUNC_signature_gettable_md_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_md_ctx_params()\fR,
681 return the gettable or settable parameters in a constant \fBOSSL_PARAM\fR\|(3) array.
682 .PP
683 \&\fBOSSL_FUNC_signature_query_key_types()\fR should return a NULL-terminated array of strings.
684 .PP
685 All verification functions should return 1 for success,
686 0 for a non-matching signature, and a negative value for operation failure.
687 .PP
688 All other functions should return 1 for success
689 and 0 or a negative value for failure.
690 .SH "SEE ALSO"
691 .IX Header "SEE ALSO"
692 \&\fBprovider\fR\|(7), "Provider Functions" in \fBprovider\-base\fR\|(7),
693 \&\fBOSSL_PARAM\fR\|(3), \fBOSSL_DISPATCH\fR\|(3), \fBOSSL_ALGORITHM\fR\|(3),
694 \&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify\fR\|(3), \fBEVP_PKEY_verify_recover\fR\|(3),
695 \&\fBEVP_SIGNATURE_is_a\fR\|(3), \fBASN1_item_sign_ctx\fR\|(3)
696 .SH HISTORY
697 .IX Header "HISTORY"
698 The provider SIGNATURE interface was introduced in OpenSSL 3.0.
699 .PP
700 The \fBOSSL_FUNC_signature_sign_message_init()\fR, \fBOSSL_FUNC_signature_sign_message_update()\fR,
701 \&\fBOSSL_FUNC_signature_sign_message_final()\fR, \fBOSSL_FUNC_signature_verify_message_init()\fR,
702 \&\fBOSSL_FUNC_signature_verify_message_update()\fR and \fBOSSL_FUNC_signature_verify_message_final()\fR
703 functions were added in OpenSSL 3.4.
704 .PP
705 The Signature Parameters "fips-indicator", "key-check" and "digest-check" were added in
706 OpenSSL 3.4.
707 .PP
708 Deterministic digital signature generation for ECDSA was added to the FIPS provider in OpenSSL
709 3.6.
710 .SH COPYRIGHT
711 .IX Header "COPYRIGHT"
712 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
713 .PP
714 Licensed under the Apache License 2.0 (the "License"). You may not use
715 this file except in compliance with the License. You can obtain a copy
716 in the file LICENSE in the source distribution or at
717 <https://www.openssl.org/source/license.html>.