45d97e668ccc69cdee060279a2a66eb47ae8cd10
[openssl.git] / doc / man7 / provider-signature.pod
1 =pod
2
3 =head1 NAME
4
5 provider-signature - The signature library E<lt>-E<gt> provider functions
6
7 =head1 SYNOPSIS
8
9 =for openssl multiple includes
10
11  #include <openssl/core_numbers.h>
12  #include <openssl/core_names.h>
13
14  /*
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.
18   */
19
20  /* Context management */
21  void *OP_signature_newctx(void *provctx);
22  void OP_signature_freectx(void *ctx);
23  void *OP_signature_dupctx(void *ctx);
24
25  /* Signing */
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);
29
30  /* Verifying */
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);
34
35  /* Verify Recover */
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);
40
41  /* Digest Sign */
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,
45                                      size_t datalen);
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,
50                               size_t tbslen);
51
52  /* Digest Verify */
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,
56                                        size_t datalen);
57  int OP_signature_digest_verify_final(void *ctx, const unsigned char *sig,
58                                       size_t siglen);
59  int OP_signature_digest_verify(void *ctx, const unsigned char *sig,
60                                 size_t siglen, const unsigned char *tbs,
61                                 size_t tbslen);
62
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);
68
69  /* MD parameters */
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);
74
75 =head1 DESCRIPTION
76
77 This documentation is primarily aimed at provider authors. See L<provider(7)>
78 for further information.
79
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).
86
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>).
92
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
96 B<OSSL_get_{name}>.
97 For example, the "function" OP_signature_newctx() has these:
98
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);
102
103 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
104 macros in L<openssl-core_numbers.h(7)>, as follows:
105
106  OP_signature_newctx                 OSSL_FUNC_SIGNATURE_NEWCTX
107  OP_signature_freectx                OSSL_FUNC_SIGNATURE_FREECTX
108  OP_signature_dupctx                 OSSL_FUNC_SIGNATURE_DUPCTX
109
110  OP_signature_sign_init              OSSL_FUNC_SIGNATURE_SIGN_INIT
111  OP_signature_sign                   OSSL_FUNC_SIGNATURE_SIGN
112
113  OP_signature_verify_init            OSSL_FUNC_SIGNATURE_VERIFY_INIT
114  OP_signature_verify                 OSSL_FUNC_SIGNATURE_VERIFY
115
116  OP_signature_verify_recover_init    OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
117  OP_signature_verify_recover         OSSL_FUNC_SIGNATURE_VERIFY_RECOVER
118
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
123
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
128
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
133
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
138
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:
143
144 =over 4
145
146 =item OP_signature_sign_init and OP_signature_sign
147
148 =item OP_signature_verify_init and OP_signature_verify
149
150 =item OP_signature_verify_recover_init and OP_signature_verify_init
151
152 =item OP_signature_digest_sign_init, OP_signature_digest_sign_update and OP_signature_digest_sign_final
153
154 =item OP_signature_digest_verify_init, OP_signature_digest_verify_update and OP_signature_digest_verify_final
155
156 =item OP_signature_digest_sign_init and OP_signature_digest_sign
157
158 =item OP_signature_digest_verify_init and OP_signature_digest_verify
159
160 =back
161
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.
166
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.
170
171 =head2 Context Management Functions
172
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)>).
179
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.
183
184 OP_signature_dupctx() should duplicate the provider side signature context in
185 the I<ctx> parameter and return the duplicate copy.
186
187 =head2 Signing Functions
188
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)>.
195
196 OP_signature_sign() performs the actual signing itself.
197 A previously initialised signature context is passed in the I<ctx>
198 parameter.
199 The data to be signed is pointed to be the I<tbs> parameter which is I<tbslen>
200 bytes long.
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
205 I<*siglen>.
206
207 =head2 Verify Functions
208
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)>.
215
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
221 long.
222
223 =head2 Verify Recover Functions
224
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)>.
231
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
235 long.
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.
241
242 =head2 Digest Sign Functions
243
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.
252
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.
257
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>.
267
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>.
276
277 =head2 Digest Verify Functions
278
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.
287
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.
292
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.
299
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.
305
306 =head2 Signature Parameters
307
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.
310
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.
316
317 Parameters currently recognised by built-in signature algorithms are as
318 follows.
319 Not all parameters are relevant to, or are understood by all signature
320 algorithms:
321
322 =over 4
323
324 =item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
325
326 Get or sets the name of the digest algorithm used for the input to the signature
327 functions.
328
329 =item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
330
331 Gets or sets the output size of the digest algorithm used for the input to the
332 signature functions.
333 The length of the "digest-size" parameter should not exceed that of a B<size_t>.
334
335 = item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
336
337 Gets the DER encoded AlgorithmIdentifier that corresponds to the combination of
338 signature algorithm and digest algorithm for the signature operation.
339
340 =item "kat" (B<OSSL_SIGNATURE_PARAM_KAT>) <unsigned integer>
341
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
349 was successful.
350 Known answer tests can be performed if the random generator is overridden to
351 supply known values that either pass or fail.
352
353 =back
354
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.
360
361 =head2 MD Parameters
362
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()
365 functions.
366
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.
372
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.
376
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
382 descriptor.
383
384 =head1 RETURN VALUES
385
386 OP_signature_newctx() and OP_signature_dupctx() should return the newly created
387 provider side signature, or NULL on failure.
388
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.
392
393 All other functions should return 1 for success or 0 on error.
394
395 =head1 SEE ALSO
396
397 L<provider(7)>
398
399 =head1 HISTORY
400
401 The provider SIGNATURE interface was introduced in OpenSSL 3.0.
402
403 =head1 COPYRIGHT
404
405 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
406
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>.
411
412 =cut