1PROVIDER-SIGNATURE(7ossl)           OpenSSL          PROVIDER-SIGNATURE(7ossl)
2
3
4

NAME

6       provider-signature - The signature library <-> provider functions
7

SYNOPSIS

9        #include <openssl/core_dispatch.h>
10        #include <openssl/core_names.h>
11
12        /*
13         * None of these are actual functions, but are displayed like this for
14         * the function signatures for functions that are offered as function
15         * pointers in OSSL_DISPATCH arrays.
16         */
17
18        /* Context management */
19        void *OSSL_FUNC_signature_newctx(void *provctx, const char *propq);
20        void OSSL_FUNC_signature_freectx(void *ctx);
21        void *OSSL_FUNC_signature_dupctx(void *ctx);
22
23        /* Signing */
24        int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey,
25                                          const OSSL_PARAM params[]);
26        int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen,
27                                     size_t sigsize, const unsigned char *tbs, size_t tbslen);
28
29        /* Verifying */
30        int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey,
31                                            const OSSL_PARAM params[]);
32        int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen,
33                                       const unsigned char *tbs, size_t tbslen);
34
35        /* Verify Recover */
36        int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey,
37                                                    const OSSL_PARAM params[]);
38        int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout,
39                                               size_t *routlen, size_t routsize,
40                                               const unsigned char *sig, size_t siglen);
41
42        /* Digest Sign */
43        int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname,
44                                                 void *provkey,
45                                                 const OSSL_PARAM params[]);
46        int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data,
47                                            size_t datalen);
48        int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig,
49                                                  size_t *siglen, size_t sigsize);
50        int OSSL_FUNC_signature_digest_sign(void *ctx,
51                                     unsigned char *sig, size_t *siglen,
52                                     size_t sigsize, const unsigned char *tbs,
53                                     size_t tbslen);
54
55        /* Digest Verify */
56        int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname,
57                                                   void *provkey,
58                                                   const OSSL_PARAM params[]);
59        int OSSL_FUNC_signature_digest_verify_update(void *ctx,
60                                                     const unsigned char *data,
61                                                     size_t datalen);
62        int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig,
63                                             size_t siglen);
64        int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig,
65                                       size_t siglen, const unsigned char *tbs,
66                                       size_t tbslen);
67
68        /* Signature parameters */
69        int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]);
70        const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void *ctx,
71                                                                  void *provctx);
72        int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
73        const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void *ctx,
74                                                                  void *provctx);
75        /* MD parameters */
76        int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]);
77        const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx);
78        int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]);
79        const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx);
80

DESCRIPTION

82       This documentation is primarily aimed at provider authors. See
83       provider(7) for further information.
84
85       The signature (OSSL_OP_SIGNATURE) operation enables providers to
86       implement signature algorithms and make them available to applications
87       via the API functions EVP_PKEY_sign(3), EVP_PKEY_verify(3), and
88       EVP_PKEY_verify_recover(3) (as well as other related functions).
89
90       All "functions" mentioned here are passed as function pointers between
91       libcrypto and the provider in OSSL_DISPATCH(3) arrays via
92       OSSL_ALGORITHM(3) arrays that are returned by the provider's
93       provider_query_operation() function (see "Provider Functions" in
94       provider-base(7)).
95
96       All these "functions" have a corresponding function type definition
97       named OSSL_FUNC_{name}_fn, and a helper function to retrieve the
98       function pointer from an OSSL_DISPATCH(3) element named
99       OSSL_FUNC_{name}.  For example, the "function"
100       OSSL_FUNC_signature_newctx() has these:
101
102        typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx, const char *propq);
103        static ossl_inline OSSL_FUNC_signature_newctx_fn
104            OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf);
105
106       OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as
107       macros in openssl-core_dispatch.h(7), as follows:
108
109        OSSL_FUNC_signature_newctx                 OSSL_FUNC_SIGNATURE_NEWCTX
110        OSSL_FUNC_signature_freectx                OSSL_FUNC_SIGNATURE_FREECTX
111        OSSL_FUNC_signature_dupctx                 OSSL_FUNC_SIGNATURE_DUPCTX
112
113        OSSL_FUNC_signature_sign_init              OSSL_FUNC_SIGNATURE_SIGN_INIT
114        OSSL_FUNC_signature_sign                   OSSL_FUNC_SIGNATURE_SIGN
115
116        OSSL_FUNC_signature_verify_init            OSSL_FUNC_SIGNATURE_VERIFY_INIT
117        OSSL_FUNC_signature_verify                 OSSL_FUNC_SIGNATURE_VERIFY
118
119        OSSL_FUNC_signature_verify_recover_init    OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
120        OSSL_FUNC_signature_verify_recover         OSSL_FUNC_SIGNATURE_VERIFY_RECOVER
121
122        OSSL_FUNC_signature_digest_sign_init       OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT
123        OSSL_FUNC_signature_digest_sign_update     OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE
124        OSSL_FUNC_signature_digest_sign_final      OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL
125        OSSL_FUNC_signature_digest_sign            OSSL_FUNC_SIGNATURE_DIGEST_SIGN
126
127        OSSL_FUNC_signature_digest_verify_init     OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT
128        OSSL_FUNC_signature_digest_verify_update   OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE
129        OSSL_FUNC_signature_digest_verify_final    OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL
130        OSSL_FUNC_signature_digest_verify          OSSL_FUNC_SIGNATURE_DIGEST_VERIFY
131
132        OSSL_FUNC_signature_get_ctx_params         OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS
133        OSSL_FUNC_signature_gettable_ctx_params    OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS
134        OSSL_FUNC_signature_set_ctx_params         OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS
135        OSSL_FUNC_signature_settable_ctx_params    OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS
136
137        OSSL_FUNC_signature_get_ctx_md_params      OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS
138        OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS
139        OSSL_FUNC_signature_set_ctx_md_params      OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS
140        OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS
141
142       A signature algorithm implementation may not implement all of these
143       functions.  In order to be a consistent set of functions we must have
144       at least a set of context functions (OSSL_FUNC_signature_newctx and
145       OSSL_FUNC_signature_freectx) as well as a set of "signature" functions,
146       i.e. at least one of:
147
148       OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign
149       OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify
150       OSSL_FUNC_signature_verify_recover_init and
151       OSSL_FUNC_signature_verify_recover
152       OSSL_FUNC_signature_digest_sign_init,
153       OSSL_FUNC_signature_digest_sign_update and
154       OSSL_FUNC_signature_digest_sign_final
155       OSSL_FUNC_signature_digest_verify_init,
156       OSSL_FUNC_signature_digest_verify_update and
157       OSSL_FUNC_signature_digest_verify_final
158       OSSL_FUNC_signature_digest_sign_init and
159       OSSL_FUNC_signature_digest_sign
160       OSSL_FUNC_signature_digest_verify_init and
161       OSSL_FUNC_signature_digest_verify
162
163       OSSL_FUNC_signature_set_ctx_params and
164       OSSL_FUNC_signature_settable_ctx_params are optional, but if one of
165       them is present then the other one must also be present. The same
166       applies to OSSL_FUNC_signature_get_ctx_params and
167       OSSL_FUNC_signature_gettable_ctx_params, as well as the "md_params"
168       functions. The OSSL_FUNC_signature_dupctx function is optional.
169
170       A signature algorithm must also implement some mechanism for
171       generating, loading or importing keys via the key management
172       (OSSL_OP_KEYMGMT) operation.  See provider-keymgmt(7) for further
173       details.
174
175   Context Management Functions
176       OSSL_FUNC_signature_newctx() should create and return a pointer to a
177       provider side structure for holding context information during a
178       signature operation.  A pointer to this context will be passed back in
179       a number of the other signature operation function calls.  The
180       parameter provctx is the provider context generated during provider
181       initialisation (see provider(7)). The propq parameter is a property
182       query string that may be (optionally) used by the provider during any
183       "fetches" that it may perform (if it performs any).
184
185       OSSL_FUNC_signature_freectx() is passed a pointer to the provider side
186       signature context in the ctx parameter.  This function should free any
187       resources associated with that context.
188
189       OSSL_FUNC_signature_dupctx() should duplicate the provider side
190       signature context in the ctx parameter and return the duplicate copy.
191
192   Signing Functions
193       OSSL_FUNC_signature_sign_init() initialises a context for signing given
194       a provider side signature context in the ctx parameter, and a pointer
195       to a provider key object in the provkey parameter.  The params, if not
196       NULL, should be set on the context in a manner similar to using
197       OSSL_FUNC_signature_set_ctx_params().  The key object should have been
198       previously generated, loaded or imported into the provider using the
199       key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
200
201       OSSL_FUNC_signature_sign() performs the actual signing itself.  A
202       previously initialised signature context is passed in the ctx
203       parameter.  The data to be signed is pointed to be the tbs parameter
204       which is tbslen bytes long.  Unless sig is NULL, the signature should
205       be written to the location pointed to by the sig parameter and it
206       should not exceed sigsize bytes in length.  The length of the signature
207       should be written to *siglen.  If sig is NULL then the maximum length
208       of the signature should be written to *siglen.
209
210   Verify Functions
211       OSSL_FUNC_signature_verify_init() initialises a context for verifying a
212       signature given a provider side signature context in the ctx parameter,
213       and a pointer to a provider key object in the provkey parameter.  The
214       params, if not NULL, should be set on the context in a manner similar
215       to using OSSL_FUNC_signature_set_ctx_params().  The key object should
216       have been previously generated, loaded or imported into the provider
217       using the key management (OSSL_OP_KEYMGMT) operation (see
218       provider-keymgmt(7)>.
219
220       OSSL_FUNC_signature_verify() performs the actual verification itself.
221       A previously initialised signature context is passed in the ctx
222       parameter.  The data that the signature covers is pointed to be the tbs
223       parameter which is tbslen bytes long.  The signature is pointed to by
224       the sig parameter which is siglen bytes long.
225
226   Verify Recover Functions
227       OSSL_FUNC_signature_verify_recover_init() initialises a context for
228       recovering the signed data given a provider side signature context in
229       the ctx parameter, and a pointer to a provider key object in the
230       provkey parameter.  The params, if not NULL, should be set on the
231       context in a manner similar to using
232       OSSL_FUNC_signature_set_ctx_params().  The key object should have been
233       previously generated, loaded or imported into the provider using the
234       key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
235
236       OSSL_FUNC_signature_verify_recover() performs the actual verify recover
237       itself.  A previously initialised signature context is passed in the
238       ctx parameter.  The signature is pointed to by the sig parameter which
239       is siglen bytes long.  Unless rout is NULL, the recovered data should
240       be written to the location pointed to by rout which should not exceed
241       routsize bytes in length.  The length of the recovered data should be
242       written to *routlen.  If rout is NULL then the maximum size of the
243       output buffer is written to the routlen parameter.
244
245   Digest Sign Functions
246       OSSL_FUNC_signature_digeset_sign_init() initialises a context for
247       signing given a provider side signature context in the ctx parameter,
248       and a pointer to a provider key object in the provkey parameter.  The
249       params, if not NULL, should be set on the context in a manner similar
250       to using OSSL_FUNC_signature_set_ctx_params() and
251       OSSL_FUNC_signature_set_ctx_md_params().  The key object should have
252       been previously generated, loaded or imported into the provider using
253       the key management (OSSL_OP_KEYMGMT) operation (see
254       provider-keymgmt(7)>.  The name of the digest to be used will be in the
255       mdname parameter.
256
257       OSSL_FUNC_signature_digest_sign_update() provides data to be signed in
258       the data parameter which should be of length datalen. A previously
259       initialised signature context is passed in the ctx parameter. This
260       function may be called multiple times to cumulatively add data to be
261       signed.
262
263       OSSL_FUNC_signature_digest_sign_final() finalises a signature operation
264       previously started through OSSL_FUNC_signature_digest_sign_init() and
265       OSSL_FUNC_signature_digest_sign_update() calls. Once finalised no more
266       data will be added through OSSL_FUNC_signature_digest_sign_update(). A
267       previously initialised signature context is passed in the ctx
268       parameter. Unless sig is NULL, the signature should be written to the
269       location pointed to by the sig parameter and it should not exceed
270       sigsize bytes in length. The length of the signature should be written
271       to *siglen. If sig is NULL then the maximum length of the signature
272       should be written to *siglen.
273
274       OSSL_FUNC_signature_digest_sign() implements a "one shot" digest sign
275       operation previously started through
276       OSSL_FUNC_signature_digeset_sign_init(). A previously initialised
277       signature context is passed in the ctx parameter. The data to be signed
278       is in tbs which should be tbslen bytes long. Unless sig is NULL, the
279       signature should be written to the location pointed to by the sig
280       parameter and it should not exceed sigsize bytes in length. The length
281       of the signature should be written to *siglen. If sig is NULL then the
282       maximum length of the signature should be written to *siglen.
283
284   Digest Verify Functions
285       OSSL_FUNC_signature_digeset_verify_init() initialises a context for
286       verifying given a provider side verification context in the ctx
287       parameter, and a pointer to a provider key object in the provkey
288       parameter.  The params, if not NULL, should be set on the context in a
289       manner similar to OSSL_FUNC_signature_set_ctx_params() and
290       OSSL_FUNC_signature_set_ctx_md_params().  The key object should have
291       been previously generated, loaded or imported into the provider using
292       the key management (OSSL_OP_KEYMGMT) operation (see
293       provider-keymgmt(7)>.  The name of the digest to be used will be in the
294       mdname parameter.
295
296       OSSL_FUNC_signature_digest_verify_update() provides data to be verified
297       in the data parameter which should be of length datalen. A previously
298       initialised verification context is passed in the ctx parameter. This
299       function may be called multiple times to cumulatively add data to be
300       verified.
301
302       OSSL_FUNC_signature_digest_verify_final() finalises a verification
303       operation previously started through
304       OSSL_FUNC_signature_digest_verify_init() and
305       OSSL_FUNC_signature_digest_verify_update() calls. Once finalised no
306       more data will be added through
307       OSSL_FUNC_signature_digest_verify_update(). A previously initialised
308       verification context is passed in the ctx parameter. The signature to
309       be verified is in sig which is siglen bytes long.
310
311       OSSL_FUNC_signature_digest_verify() implements a "one shot" digest
312       verify operation previously started through
313       OSSL_FUNC_signature_digeset_verify_init(). A previously initialised
314       verification context is passed in the ctx parameter. The data to be
315       verified is in tbs which should be tbslen bytes long. The signature to
316       be verified is in sig which is siglen bytes long.
317
318   Signature parameters
319       See OSSL_PARAM(3) for further details on the parameters structure used
320       by the OSSL_FUNC_signature_get_ctx_params() and
321       OSSL_FUNC_signature_set_ctx_params() functions.
322
323       OSSL_FUNC_signature_get_ctx_params() gets signature parameters
324       associated with the given provider side signature context ctx and
325       stored them in params.  Passing NULL for params should return true.
326
327       OSSL_FUNC_signature_set_ctx_params() sets the signature parameters
328       associated with the given provider side signature context ctx to
329       params.  Any parameter settings are additional to any that were
330       previously set.  Passing NULL for params should return true.
331
332       Common parameters currently recognised by built-in signature algorithms
333       are as follows.
334
335       "digest" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>
336           Get or sets the name of the digest algorithm used for the input to
337           the signature functions. It is required in order to calculate the
338           "algorithm-id".
339
340       "properties" (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>
341           Sets the name of the property query associated with the "digest"
342           algorithm.  NULL is used if this optional value is not set.
343
344       "digest-size" (OSSL_SIGNATURE_PARAM_DIGEST_SIZE) <unsigned integer>
345           Gets or sets the output size of the digest algorithm used for the
346           input to the signature functions.  The length of the "digest-size"
347           parameter should not exceed that of a size_t.
348
349       "algorithm-id" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>
350           Gets the DER encoded AlgorithmIdentifier that corresponds to the
351           combination of signature algorithm and digest algorithm for the
352           signature operation.
353
354       "kat" (OSSL_SIGNATURE_PARAM_KAT) <unsigned integer>
355           Sets a flag to modify the sign operation to return an error if the
356           initial calculated signature is invalid.  In the normal mode of
357           operation - new random values are chosen until the signature
358           operation succeeds.  By default it retries until a signature is
359           calculated.  Setting the value to 0 causes the sign operation to
360           retry, otherwise the sign operation is only tried once and returns
361           whether or not it was successful.  Known answer tests can be
362           performed if the random generator is overridden to supply known
363           values that either pass or fail.
364
365       OSSL_FUNC_signature_gettable_ctx_params() and
366       OSSL_FUNC_signature_settable_ctx_params() get a constant OSSL_PARAM(3)
367       array that describes the gettable and settable parameters, i.e.
368       parameters that can be used with OSSL_FUNC_signature_get_ctx_params()
369       and OSSL_FUNC_signature_set_ctx_params() respectively.
370
371   MD parameters
372       See OSSL_PARAM(3) for further details on the parameters structure used
373       by the OSSL_FUNC_signature_get_md_ctx_params() and
374       OSSL_FUNC_signature_set_md_ctx_params() functions.
375
376       OSSL_FUNC_signature_get_md_ctx_params() gets digest parameters
377       associated with the given provider side digest signature context ctx
378       and stores them in params.  Passing NULL for params should return true.
379
380       OSSL_FUNC_signature_set_ms_ctx_params() sets the digest parameters
381       associated with the given provider side digest signature context ctx to
382       params.  Any parameter settings are additional to any that were
383       previously set.  Passing NULL for params should return true.
384
385       Parameters currently recognised by built-in signature algorithms are
386       the same as those for built-in digest algorithms. See "Digest
387       Parameters" in provider-digest(7) for further information.
388
389       OSSL_FUNC_signature_gettable_md_ctx_params() and
390       OSSL_FUNC_signature_settable_md_ctx_params() get a constant
391       OSSL_PARAM(3) array that describes the gettable and settable digest
392       parameters, i.e. parameters that can be used with
393       OSSL_FUNC_signature_get_md_ctx_params() and
394       OSSL_FUNC_signature_set_md_ctx_params() respectively.
395

RETURN VALUES

397       OSSL_FUNC_signature_newctx() and OSSL_FUNC_signature_dupctx() should
398       return the newly created provider side signature context, or NULL on
399       failure.
400
401       OSSL_FUNC_signature_gettable_ctx_params(),
402       OSSL_FUNC_signature_settable_ctx_params(),
403       OSSL_FUNC_signature_gettable_md_ctx_params() and
404       OSSL_FUNC_signature_settable_md_ctx_params(), return the gettable or
405       settable parameters in a constant OSSL_PARAM(3) array.
406
407       All other functions should return 1 for success or 0 on error.
408

SEE ALSO

410       provider(7)
411

HISTORY

413       The provider SIGNATURE interface was introduced in OpenSSL 3.0.
414
416       Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
417
418       Licensed under the Apache License 2.0 (the "License").  You may not use
419       this file except in compliance with the License.  You can obtain a copy
420       in the file LICENSE in the source distribution or at
421       <https://www.openssl.org/source/license.html>.
422
423
424
4253.1.1                             2023-08-31         PROVIDER-SIGNATURE(7ossl)
Impressum