5 provider-signature - The signature library E<lt>-E<gt> provider functions
9 =for openssl multiple includes
11 #include <openssl/core_dispatch.h>
12 #include <openssl/core_names.h>
15 * None of these are actual functions, but are displayed like this for
16 * the function signatures for functions that are offered as function
17 * pointers in OSSL_DISPATCH arrays.
20 /* Context management */
21 void *OSSL_FUNC_signature_newctx(void *provctx);
22 void OSSL_FUNC_signature_freectx(void *ctx);
23 void *OSSL_FUNC_signature_dupctx(void *ctx);
26 int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey);
27 int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen,
28 size_t sigsize, const unsigned char *tbs, size_t tbslen);
31 int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey);
32 int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen,
33 const unsigned char *tbs, size_t tbslen);
36 int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey);
37 int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout,
38 size_t *routlen, size_t routsize,
39 const unsigned char *sig, size_t siglen);
42 int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname,
43 const char *props, void *provkey);
44 int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data,
46 int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig,
47 size_t *siglen, size_t sigsize);
48 int OSSL_FUNC_signature_digest_sign(void *ctx,
49 unsigned char *sigret, size_t *siglen,
50 size_t sigsize, const unsigned char *tbs,
54 int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname,
55 const char *props, void *provkey);
56 int OSSL_FUNC_signature_digest_verify_update(void *ctx,
57 const unsigned char *data,
59 int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig,
61 int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig,
62 size_t siglen, const unsigned char *tbs,
65 /* Signature parameters */
66 int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]);
67 const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void);
68 int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
69 const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void);
72 int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]);
73 const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx);
74 int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]);
75 const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx);
79 This documentation is primarily aimed at provider authors. See L<provider(7)>
80 for further information.
82 The signature (OSSL_OP_SIGNATURE) operation enables providers to implement
83 signature algorithms and make them available to applications via the API
84 functions L<EVP_PKEY_sign(3)>,
85 L<EVP_PKEY_verify(3)>,
86 and L<EVP_PKEY_verify_recover(3)> (as well
87 as other related functions).
89 All "functions" mentioned here are passed as function pointers between
90 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
91 B<OSSL_ALGORITHM> arrays that are returned by the provider's
92 provider_query_operation() function
93 (see L<provider-base(7)/Provider Functions>).
95 All these "functions" have a corresponding function type definition
96 named B<OSSL_{name}_fn>, and a helper function to retrieve the
97 function pointer from an B<OSSL_DISPATCH> element named
99 For example, the "function" OSSL_FUNC_signature_newctx() has these:
101 typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx);
102 static ossl_inline OSSL_FUNC_signature_newctx_fn
103 OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf);
105 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
106 macros in L<openssl-core_dispatch.h(7)>, as follows:
108 OSSL_FUNC_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX
109 OSSL_FUNC_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX
110 OSSL_FUNC_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX
112 OSSL_FUNC_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT
113 OSSL_FUNC_signature_sign OSSL_FUNC_SIGNATURE_SIGN
115 OSSL_FUNC_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT
116 OSSL_FUNC_signature_verify OSSL_FUNC_SIGNATURE_VERIFY
118 OSSL_FUNC_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
119 OSSL_FUNC_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER
121 OSSL_FUNC_signature_digest_sign_init OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT
122 OSSL_FUNC_signature_digest_sign_update OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE
123 OSSL_FUNC_signature_digest_sign_final OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL
124 OSSL_FUNC_signature_digest_sign OSSL_FUNC_SIGNATURE_DIGEST_SIGN
126 OSSL_FUNC_signature_digest_verify_init OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT
127 OSSL_FUNC_signature_digest_verify_update OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE
128 OSSL_FUNC_signature_digest_verify_final OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL
129 OSSL_FUNC_signature_digest_verify OSSL_FUNC_SIGNATURE_DIGEST_VERIFY
131 OSSL_FUNC_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS
132 OSSL_FUNC_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS
133 OSSL_FUNC_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS
134 OSSL_FUNC_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS
136 OSSL_FUNC_signature_get_ctx_md_params OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS
137 OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS
138 OSSL_FUNC_signature_set_ctx_md_params OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS
139 OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS
141 A signature algorithm implementation may not implement all of these functions.
142 In order to be a consistent set of functions we must have at least a set of
143 context functions (OSSL_FUNC_signature_newctx and OSSL_FUNC_signature_freectx) as well as a
144 set of "signature" functions, i.e. at least one of:
148 =item OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign
150 =item OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify
152 =item OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_init
154 =item OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final
156 =item OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final
158 =item OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign
160 =item OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify
164 OSSL_FUNC_signature_set_ctx_params and OSSL_FUNC_signature_settable_ctx_params are optional,
165 but if one of them is present then the other one must also be present. The same
166 applies to OSSL_FUNC_signature_get_ctx_params and OSSL_FUNC_signature_gettable_ctx_params, as
167 well as the "md_params" functions. The OSSL_FUNC_signature_dupctx function is optional.
169 A signature algorithm must also implement some mechanism for generating,
170 loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
171 See L<provider-keymgmt(7)> for further details.
173 =head2 Context Management Functions
175 OSSL_FUNC_signature_newctx() should create and return a pointer to a provider side
176 structure for holding context information during a signature operation.
177 A pointer to this context will be passed back in a number of the other signature
178 operation function calls.
179 The parameter I<provctx> is the provider context generated during provider
180 initialisation (see L<provider(7)>).
182 OSSL_FUNC_signature_freectx() is passed a pointer to the provider side signature
183 context in the I<ctx> parameter.
184 This function should free any resources associated with that context.
186 OSSL_FUNC_signature_dupctx() should duplicate the provider side signature context in
187 the I<ctx> parameter and return the duplicate copy.
189 =head2 Signing Functions
191 OSSL_FUNC_signature_sign_init() initialises a context for signing given a provider side
192 signature context in the I<ctx> parameter, and a pointer to a provider key object
193 in the I<provkey> parameter.
194 The key object should have been previously generated, loaded or imported into
195 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
196 provider-keymgmt(7)>.
198 OSSL_FUNC_signature_sign() performs the actual signing itself.
199 A previously initialised signature context is passed in the I<ctx>
201 The data to be signed is pointed to be the I<tbs> parameter which is I<tbslen>
203 Unless I<sig> is NULL, the signature should be written to the location pointed
204 to by the I<sig> parameter and it should not exceed I<sigsize> bytes in length.
205 The length of the signature should be written to I<*siglen>.
206 If I<sig> is NULL then the maximum length of the signature should be written to
209 =head2 Verify Functions
211 OSSL_FUNC_signature_verify_init() initialises a context for verifying a signature given
212 a provider side signature context in the I<ctx> parameter, and a pointer to a
213 provider key object in the I<provkey> parameter.
214 The key object should have been previously generated, loaded or imported into
215 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
216 provider-keymgmt(7)>.
218 OSSL_FUNC_signature_verify() performs the actual verification itself.
219 A previously initialised signature context is passed in the I<ctx> parameter.
220 The data that the signature covers is pointed to be the I<tbs> parameter which
221 is I<tbslen> bytes long.
222 The signature is pointed to by the I<sig> parameter which is I<siglen> bytes
225 =head2 Verify Recover Functions
227 OSSL_FUNC_signature_verify_recover_init() initialises a context for recovering the
228 signed data given a provider side signature context in the I<ctx> parameter, and
229 a pointer to a provider key object in the I<provkey> parameter.
230 The key object should have been previously generated, loaded or imported into
231 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
232 provider-keymgmt(7)>.
234 OSSL_FUNC_signature_verify_recover() performs the actual verify recover itself.
235 A previously initialised signature context is passed in the I<ctx> parameter.
236 The signature is pointed to by the I<sig> parameter which is I<siglen> bytes
238 Unless I<rout> is NULL, the recovered data should be written to the location
239 pointed to by I<rout> which should not exceed I<routsize> bytes in length.
240 The length of the recovered data should be written to I<*routlen>.
241 If I<rout> is NULL then the maximum size of the output buffer is written to
242 the I<routlen> parameter.
244 =head2 Digest Sign Functions
246 OSSL_FUNC_signature_digeset_sign_init() initialises a context for signing given a
247 provider side signature context in the I<ctx> parameter, and a pointer to a
248 provider key object in the I<provkey> parameter. The key object should have been
249 previously generated, loaded or imported into the provider using the
250 key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
251 The name of the digest to be used will be in the I<mdname> parameter. There may
252 also be properties to be used in fetching the digest in the I<props> parameter,
253 although this may be ignored by providers.
255 OSSL_FUNC_signature_digest_sign_update() provides data to be signed in the I<data>
256 parameter which should be of length I<datalen>. A previously initialised
257 signature context is passed in the I<ctx> parameter. This function may be called
258 multiple times to cumulatively add data to be signed.
260 OSSL_FUNC_signature_digest_sign_final() finalises a signature operation previously
261 started through OSSL_FUNC_signature_digest_sign_init() and
262 OSSL_FUNC_signature_digest_sign_update() calls. Once finalised no more data will be
263 added through OSSL_FUNC_signature_digest_sign_update(). A previously initialised
264 signature context is passed in the I<ctx> parameter. Unless I<sig> is NULL, the
265 signature should be written to the location pointed to by the I<sig> parameter
266 and it should not exceed I<sigsize> bytes in length. The length of the signature
267 should be written to I<*siglen>. If I<sig> is NULL then the maximum length of
268 the signature should be written to I<*siglen>.
270 OSSL_FUNC_signature_digest_sign() implements a "one shot" digest sign operation
271 previously started through OSSL_FUNC_signature_digeset_sign_init(). A previously
272 initialised signature context is passed in the I<ctx> parameter. The data to be
273 signed is in I<tbs> which should be I<tbslen> bytes long. Unless I<sig> is NULL,
274 the signature should be written to the location pointed to by the I<sig>
275 parameter and it should not exceed I<sigsize> bytes in length. The length of the
276 signature should be written to I<*siglen>. If I<sig> is NULL then the maximum
277 length of the signature should be written to I<*siglen>.
279 =head2 Digest Verify Functions
281 OSSL_FUNC_signature_digeset_verify_init() initialises a context for verifying given a
282 provider side verification context in the I<ctx> parameter, and a pointer to a
283 provider key object in the I<provkey> parameter. The key object should have been
284 previously generated, loaded or imported into the provider using the
285 key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
286 The name of the digest to be used will be in the I<mdname> parameter. There may
287 also be properties to be used in fetching the digest in the I<props> parameter,
288 although this may be ignored by providers.
290 OSSL_FUNC_signature_digest_verify_update() provides data to be verified in the I<data>
291 parameter which should be of length I<datalen>. A previously initialised
292 verification context is passed in the I<ctx> parameter. This function may be
293 called multiple times to cumulatively add data to be verified.
295 OSSL_FUNC_signature_digest_verify_final() finalises a verification operation previously
296 started through OSSL_FUNC_signature_digest_verify_init() and
297 OSSL_FUNC_signature_digest_verify_update() calls. Once finalised no more data will be
298 added through OSSL_FUNC_signature_digest_verify_update(). A previously initialised
299 verification context is passed in the I<ctx> parameter. The signature to be
300 verified is in I<sig> which is I<siglen> bytes long.
302 OSSL_FUNC_signature_digest_verify() implements a "one shot" digest verify operation
303 previously started through OSSL_FUNC_signature_digeset_verify_init(). A previously
304 initialised verification context is passed in the I<ctx> parameter. The data to be
305 verified is in I<tbs> which should be I<tbslen> bytes long. The signature to be
306 verified is in I<sig> which is I<siglen> bytes long.
308 =head2 Signature parameters
310 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
311 the OSSL_FUNC_signature_get_ctx_params() and OSSL_FUNC_signature_set_ctx_params() functions.
313 OSSL_FUNC_signature_get_ctx_params() gets signature parameters associated with the
314 given provider side signature context I<ctx> and stored them in I<params>.
315 OSSL_FUNC_signature_set_ctx_params() sets the signature parameters associated with the
316 given provider side signature context I<ctx> to I<params>.
317 Any parameter settings are additional to any that were previously set.
319 Common parameters currently recognised by built-in signature algorithms are as
324 =item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
326 Get or sets the name of the digest algorithm used for the input to the signature
327 functions. It is required in order to calculate the "algorithm-id".
329 = item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
331 Sets the name of the property query associated with the "digest" algorithm.
332 NULL is used if this optional value is not set.
334 =item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
336 Gets or sets the output size of the digest algorithm used for the input to the
338 The length of the "digest-size" parameter should not exceed that of a B<size_t>.
340 = item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
342 Gets the DER encoded AlgorithmIdentifier that corresponds to the combination of
343 signature algorithm and digest algorithm for the signature operation.
345 =item "kat" (B<OSSL_SIGNATURE_PARAM_KAT>) <unsigned integer>
347 Sets a flag to modify the sign operation to return an error if the initial
348 calculated signature is invalid.
349 In the normal mode of operation - new random values are chosen until the
350 signature operation succeeds.
351 By default it retries until a signature is calculated.
352 Setting the value to 0 causes the sign operation to retry,
353 otherwise the sign operation is only tried once and returns whether or not it
355 Known answer tests can be performed if the random generator is overridden to
356 supply known values that either pass or fail.
360 OSSL_FUNC_signature_gettable_ctx_params() and OSSL_FUNC_signature_settable_ctx_params() get a
361 constant B<OSSL_PARAM> array that describes the gettable and settable parameters,
362 i.e. parameters that can be used with OSSL_FUNC_signature_get_ctx_params() and
363 OSSL_FUNC_signature_set_ctx_params() respectively.
364 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
368 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
369 the OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params()
372 OSSL_FUNC_signature_get_md_ctx_params() gets digest parameters associated with the
373 given provider side digest signature context I<ctx> and stores them in I<params>.
374 OSSL_FUNC_signature_set_ms_ctx_params() sets the digest parameters associated with the
375 given provider side digest signature context I<ctx> to I<params>.
376 Any parameter settings are additional to any that were previously set.
378 Parameters currently recognised by built-in signature algorithms are the same
379 as those for built-in digest algorithms. See
380 L<provider-digest(7)/Digest Parameters> for further information.
382 OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params()
383 get a constant B<OSSL_PARAM> array that describes the gettable and settable
384 digest parameters, i.e. parameters that can be used with
385 OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params()
386 respectively. See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter
391 OSSL_FUNC_signature_newctx() and OSSL_FUNC_signature_dupctx() should return the newly created
392 provider side signature, or NULL on failure.
394 OSSL_FUNC_signature_gettable_ctx_params(), OSSL_FUNC_signature_settable_ctx_params(),
395 OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params(),
396 return the gettable or settable parameters in a constant B<OSSL_PARAM> array.
398 All other functions should return 1 for success or 0 on error.
406 The provider SIGNATURE interface was introduced in OpenSSL 3.0.
410 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
412 Licensed under the Apache License 2.0 (the "License"). You may not use
413 this file except in compliance with the License. You can obtain a copy
414 in the file LICENSE in the source distribution or at
415 L<https://www.openssl.org/source/license.html>.