5 provider-signature - The signature library E<lt>-E<gt> provider functions
9 =for openssl multiple includes
11 #include <openssl/core_numbers.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 *OP_signature_newctx(void *provctx);
22 void OP_signature_freectx(void *ctx);
23 void *OP_signature_dupctx(void *ctx);
26 int OP_signature_sign_init(void *ctx, void *provkey);
27 int OP_signature_sign(void *ctx, unsigned char *sig, size_t *siglen,
28 size_t sigsize, const unsigned char *tbs, size_t tbslen);
31 int OP_signature_verify_init(void *ctx, void *provkey);
32 int OP_signature_verify(void *ctx, const unsigned char *sig, size_t siglen,
33 const unsigned char *tbs, size_t tbslen);
36 int OP_signature_verify_recover_init(void *ctx, void *provkey);
37 int OP_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 OP_signature_digest_sign_init(void *ctx, const char *mdname,
43 const char *props, void *provkey);
44 int OP_signature_digest_sign_update(void *ctx, const unsigned char *data,
46 int OP_signature_digest_sign_final(void *ctx, unsigned char *sig,
47 size_t *siglen, size_t sigsize);
48 int OP_signature_digest_sign(void *ctx, unsigned char *sigret, size_t *siglen,
49 size_t sigsize, const unsigned char *tbs,
53 int OP_signature_digest_verify_init(void *ctx, const char *mdname,
54 const char *props, void *provkey);
55 int OP_signature_digest_verify_update(void *ctx, const unsigned char *data,
57 int OP_signature_digest_verify_final(void *ctx, const unsigned char *sig,
59 int OP_signature_digest_verify(void *ctx, const unsigned char *sig,
60 size_t siglen, const unsigned char *tbs,
63 /* Signature parameters */
64 int OP_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]);
65 const OSSL_PARAM *OP_signature_gettable_ctx_params(void);
66 int OP_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
67 const OSSL_PARAM *OP_signature_settable_ctx_params(void);
70 int OP_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]);
71 const OSSL_PARAM * OP_signature_gettable_ctx_md_params(void *ctx);
72 int OP_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]);
73 const OSSL_PARAM * OP_signature_settable_ctx_md_params(void *ctx);
77 This documentation is primarily aimed at provider authors. See L<provider(7)>
78 for further information.
80 The signature (OSSL_OP_SIGNATURE) operation enables providers to implement
81 signature algorithms and make them available to applications via the API
82 functions L<EVP_PKEY_sign(3)>,
83 L<EVP_PKEY_verify(3)>,
84 and L<EVP_PKEY_verify_recover(3)> (as well
85 as other related functions).
87 All "functions" mentioned here are passed as function pointers between
88 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
89 B<OSSL_ALGORITHM> arrays that are returned by the provider's
90 provider_query_operation() function
91 (see L<provider-base(7)/Provider Functions>).
93 All these "functions" have a corresponding function type definition
94 named B<OSSL_{name}_fn>, and a helper function to retrieve the
95 function pointer from an B<OSSL_DISPATCH> element named
97 For example, the "function" OP_signature_newctx() has these:
99 typedef void *(OSSL_OP_signature_newctx_fn)(void *provctx);
100 static ossl_inline OSSL_OP_signature_newctx_fn
101 OSSL_get_OP_signature_newctx(const OSSL_DISPATCH *opf);
103 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
104 macros in L<openssl-core_numbers.h(7)>, as follows:
106 OP_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX
107 OP_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX
108 OP_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX
110 OP_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT
111 OP_signature_sign OSSL_FUNC_SIGNATURE_SIGN
113 OP_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT
114 OP_signature_verify OSSL_FUNC_SIGNATURE_VERIFY
116 OP_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
117 OP_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER
119 OP_signature_digest_sign_init OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT
120 OP_signature_digest_sign_update OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE
121 OP_signature_digest_sign_final OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL
122 OP_signature_digest_sign OSSL_FUNC_SIGNATURE_DIGEST_SIGN
124 OP_signature_digest_verify_init OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT
125 OP_signature_digest_verify_update OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE
126 OP_signature_digest_verify_final OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL
127 OP_signature_digest_verify OSSL_FUNC_SIGNATURE_DIGEST_VERIFY
129 OP_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS
130 OP_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS
131 OP_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS
132 OP_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS
134 OP_signature_get_ctx_md_params OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS
135 OP_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS
136 OP_signature_set_ctx_md_params OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS
137 OP_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS
139 A signature algorithm implementation may not implement all of these functions.
140 In order to be a consistent set of functions we must have at least a set of
141 context functions (OP_signature_newctx and OP_signature_freectx) as well as a
142 set of "signature" functions, i.e. at least one of:
146 =item OP_signature_sign_init and OP_signature_sign
148 =item OP_signature_verify_init and OP_signature_verify
150 =item OP_signature_verify_recover_init and OP_signature_verify_init
152 =item OP_signature_digest_sign_init, OP_signature_digest_sign_update and OP_signature_digest_sign_final
154 =item OP_signature_digest_verify_init, OP_signature_digest_verify_update and OP_signature_digest_verify_final
156 =item OP_signature_digest_sign_init and OP_signature_digest_sign
158 =item OP_signature_digest_verify_init and OP_signature_digest_verify
162 OP_signature_set_ctx_params and OP_signature_settable_ctx_params are optional,
163 but if one of them is present then the other one must also be present. The same
164 applies to OP_signature_get_ctx_params and OP_signature_gettable_ctx_params, as
165 well as the "md_params" functions. The OP_signature_dupctx function is optional.
167 A signature algorithm must also implement some mechanism for generating,
168 loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
169 See L<provider-keymgmt(7)> for further details.
171 =head2 Context Management Functions
173 OP_signature_newctx() should create and return a pointer to a provider side
174 structure for holding context information during a signature operation.
175 A pointer to this context will be passed back in a number of the other signature
176 operation function calls.
177 The parameter I<provctx> is the provider context generated during provider
178 initialisation (see L<provider(7)>).
180 OP_signature_freectx() is passed a pointer to the provider side signature
181 context in the I<ctx> parameter.
182 This function should free any resources associated with that context.
184 OP_signature_dupctx() should duplicate the provider side signature context in
185 the I<ctx> parameter and return the duplicate copy.
187 =head2 Signing Functions
189 OP_signature_sign_init() initialises a context for signing given a provider side
190 signature context in the I<ctx> parameter, and a pointer to a provider key object
191 in the I<provkey> parameter.
192 The key object should have been previously generated, loaded or imported into
193 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
194 provider-keymgmt(7)>.
196 OP_signature_sign() performs the actual signing itself.
197 A previously initialised signature context is passed in the I<ctx>
199 The data to be signed is pointed to be the I<tbs> parameter which is I<tbslen>
201 Unless I<sig> is NULL, the signature should be written to the location pointed
202 to by the I<sig> parameter and it should not exceed I<sigsize> bytes in length.
203 The length of the signature should be written to I<*siglen>.
204 If I<sig> is NULL then the maximum length of the signature should be written to
207 =head2 Verify Functions
209 OP_signature_verify_init() initialises a context for verifying a signature given
210 a provider side signature context in the I<ctx> parameter, and a pointer to a
211 provider key object in the I<provkey> parameter.
212 The key object should have been previously generated, loaded or imported into
213 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
214 provider-keymgmt(7)>.
216 OP_signature_verify() performs the actual verification itself.
217 A previously initialised signature context is passed in the I<ctx> parameter.
218 The data that the signature covers is pointed to be the I<tbs> parameter which
219 is I<tbslen> bytes long.
220 The signature is pointed to by the I<sig> parameter which is I<siglen> bytes
223 =head2 Verify Recover Functions
225 OP_signature_verify_recover_init() initialises a context for recovering the
226 signed data given a provider side signature context in the I<ctx> parameter, and
227 a pointer to a provider key object in the I<provkey> parameter.
228 The key object should have been previously generated, loaded or imported into
229 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
230 provider-keymgmt(7)>.
232 OP_signature_verify_recover() performs the actual verify recover itself.
233 A previously initialised signature context is passed in the I<ctx> parameter.
234 The signature is pointed to by the I<sig> parameter which is I<siglen> bytes
236 Unless I<rout> is NULL, the recovered data should be written to the location
237 pointed to by I<rout> which should not exceed I<routsize> bytes in length.
238 The length of the recovered data should be written to I<*routlen>.
239 If I<rout> is NULL then the maximum size of the output buffer is written to
240 the I<routlen> parameter.
242 =head2 Digest Sign Functions
244 OP_signature_digeset_sign_init() initialises a context for signing given a
245 provider side signature context in the I<ctx> parameter, and a pointer to a
246 provider key object in the I<provkey> parameter. The key object should have been
247 previously generated, loaded or imported into the provider using the
248 key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
249 The name of the digest to be used will be in the I<mdname> parameter. There may
250 also be properties to be used in fetching the digest in the I<props> parameter,
251 although this may be ignored by providers.
253 OP_signature_digest_sign_update() provides data to be signed in the I<data>
254 parameter which should be of length I<datalen>. A previously initialised
255 signature context is passed in the I<ctx> parameter. This function may be called
256 multiple times to cumulatively add data to be signed.
258 OP_signature_digest_sign_final() finalises a signature operation previously
259 started through OP_signature_digest_sign_init() and
260 OP_signature_digest_sign_update() calls. Once finalised no more data will be
261 added through OP_signature_digest_sign_update(). A previously initialised
262 signature context is passed in the I<ctx> parameter. Unless I<sig> is NULL, the
263 signature should be written to the location pointed to by the I<sig> parameter
264 and it should not exceed I<sigsize> bytes in length. The length of the signature
265 should be written to I<*siglen>. If I<sig> is NULL then the maximum length of
266 the signature should be written to I<*siglen>.
268 OP_signature_digest_sign() implements a "one shot" digest sign operation
269 previously started through OP_signature_digeset_sign_init(). A previously
270 initialised signature context is passed in the I<ctx> parameter. The data to be
271 signed is in I<tbs> which should be I<tbslen> bytes long. Unless I<sig> is NULL,
272 the signature should be written to the location pointed to by the I<sig>
273 parameter and it should not exceed I<sigsize> bytes in length. The length of the
274 signature should be written to I<*siglen>. If I<sig> is NULL then the maximum
275 length of the signature should be written to I<*siglen>.
277 =head2 Digest Verify Functions
279 OP_signature_digeset_verify_init() initialises a context for verifying given a
280 provider side verification context in the I<ctx> parameter, and a pointer to a
281 provider key object in the I<provkey> parameter. The key object should have been
282 previously generated, loaded or imported into the provider using the
283 key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
284 The name of the digest to be used will be in the I<mdname> parameter. There may
285 also be properties to be used in fetching the digest in the I<props> parameter,
286 although this may be ignored by providers.
288 OP_signature_digest_verify_update() provides data to be verified in the I<data>
289 parameter which should be of length I<datalen>. A previously initialised
290 verification context is passed in the I<ctx> parameter. This function may be
291 called multiple times to cumulatively add data to be verified.
293 OP_signature_digest_verify_final() finalises a verification operation previously
294 started through OP_signature_digest_verify_init() and
295 OP_signature_digest_verify_update() calls. Once finalised no more data will be
296 added through OP_signature_digest_verify_update(). A previously initialised
297 verification context is passed in the I<ctx> parameter. The signature to be
298 verified is in I<sig> which is I<siglen> bytes long.
300 OP_signature_digest_verify() implements a "one shot" digest verify operation
301 previously started through OP_signature_digeset_verify_init(). A previously
302 initialised verification context is passed in the I<ctx> parameter. The data to be
303 verified is in I<tbs> which should be I<tbslen> bytes long. The signature to be
304 verified is in I<sig> which is I<siglen> bytes long.
306 =head2 Signature Parameters
308 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
309 the OP_signature_get_ctx_params() and OP_signature_set_ctx_params() functions.
311 OP_signature_get_ctx_params() gets signature parameters associated with the
312 given provider side signature context I<ctx> and stored them in I<params>.
313 OP_signature_set_ctx_params() sets the signature parameters associated with the
314 given provider side signature context I<ctx> to I<params>.
315 Any parameter settings are additional to any that were previously set.
317 Parameters currently recognised by built-in signature algorithms are as
319 Not all parameters are relevant to, or are understood by all signature
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
329 =item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
331 Gets or sets the output size of the digest algorithm used for the input to the
333 The length of the "digest-size" parameter should not exceed that of a B<size_t>.
335 = item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
337 Gets the DER encoded AlgorithmIdentifier that corresponds to the combination of
338 signature algorithm and digest algorithm for the signature operation.
340 =item "kat" (B<OSSL_SIGNATURE_PARAM_KAT>) <unsigned integer>
342 Sets a flag to modify the sign operation to return an error if the initial
343 calculated signature is invalid.
344 In the normal mode of operation - new random values are chosen until the
345 signature operation succeeds.
346 By default it retries until a signature is calculated.
347 Setting the value to 0 causes the sign operation to retry,
348 otherwise the sign operation is only tried once and returns whether or not it
350 Known answer tests can be performed if the random generator is overridden to
351 supply known values that either pass or fail.
355 OP_signature_gettable_ctx_params() and OP_signature_settable_ctx_params() get a
356 constant B<OSSL_PARAM> array that describes the gettable and settable parameters,
357 i.e. parameters that can be used with OP_signature_get_ctx_params() and
358 OP_signature_set_ctx_params() respectively.
359 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
363 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
364 the OP_signature_get_md_ctx_params() and OP_signature_set_md_ctx_params()
367 OP_signature_get_md_ctx_params() gets digest parameters associated with the
368 given provider side digest signature context I<ctx> and stores them in I<params>.
369 OP_signature_set_ms_ctx_params() sets the digest parameters associated with the
370 given provider side digest signature context I<ctx> to I<params>.
371 Any parameter settings are additional to any that were previously set.
373 Parameters currently recognised by built-in signature algorithms are the same
374 as those for built-in digest algorithms. See
375 L<provider-digest(7)/Digest Parameters> for further information.
377 OP_signature_gettable_md_ctx_params() and OP_signature_settable_md_ctx_params()
378 get a constant B<OSSL_PARAM> array that describes the gettable and settable
379 digest parameters, i.e. parameters that can be used with
380 OP_signature_get_md_ctx_params() and OP_signature_set_md_ctx_params()
381 respectively. See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter
386 OP_signature_newctx() and OP_signature_dupctx() should return the newly created
387 provider side signature, or NULL on failure.
389 OP_signature_gettable_ctx_params(), OP_signature_settable_ctx_params(),
390 OP_signature_gettable_md_ctx_params() and OP_signature_settable_md_ctx_params(),
391 return the gettable or settable parameters in a constant B<OSSL_PARAM> array.
393 All other functions should return 1 for success or 0 on error.
401 The provider SIGNATURE interface was introduced in OpenSSL 3.0.
405 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
407 Licensed under the Apache License 2.0 (the "License"). You may not use
408 this file except in compliance with the License. You can obtain a copy
409 in the file LICENSE in the source distribution or at
410 L<https://www.openssl.org/source/license.html>.