]>
Commit | Line | Data |
---|---|---|
4f62f5d9 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider-signature - The signature library E<lt>-E<gt> provider functions | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
bb82531f | 9 | =for openssl multiple includes |
4f62f5d9 MC |
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 | /* Signature parameters */ | |
9c45222d MC |
42 | int OP_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]); |
43 | const OSSL_PARAM *OP_signature_gettable_ctx_params(void); | |
44 | int OP_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]); | |
45 | const OSSL_PARAM *OP_signature_settable_ctx_params(void); | |
4f62f5d9 MC |
46 | |
47 | =head1 DESCRIPTION | |
48 | ||
49 | This documentation is primarily aimed at provider authors. See L<provider(7)> | |
50 | for further information. | |
51 | ||
52 | The signature (OSSL_OP_SIGNATURE) operation enables providers to implement | |
53 | signature algorithms and make them available to applications via the API | |
fadb57e5 RS |
54 | functions L<EVP_PKEY_sign(3)>, |
55 | L<EVP_PKEY_verify(3)>, | |
56 | and L<EVP_PKEY_verify_recover(3)> (as well | |
4f62f5d9 MC |
57 | as other related functions). |
58 | ||
59 | All "functions" mentioned here are passed as function pointers between | |
60 | F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via | |
61 | B<OSSL_ALGORITHM> arrays that are returned by the provider's | |
62 | provider_query_operation() function | |
63 | (see L<provider-base(7)/Provider Functions>). | |
64 | ||
65 | All these "functions" have a corresponding function type definition | |
66 | named B<OSSL_{name}_fn>, and a helper function to retrieve the | |
67 | function pointer from an B<OSSL_DISPATCH> element named | |
68 | B<OSSL_get_{name}>. | |
69 | For example, the "function" OP_signature_newctx() has these: | |
70 | ||
71 | typedef void *(OSSL_OP_signature_newctx_fn)(void *provctx); | |
72 | static ossl_inline OSSL_OP_signature_newctx_fn | |
73 | OSSL_get_OP_signature_newctx(const OSSL_DISPATCH *opf); | |
74 | ||
75 | B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as | |
76 | macros in L<openssl-core_numbers.h(7)>, as follows: | |
77 | ||
78 | OP_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX | |
79 | OP_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX | |
80 | OP_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX | |
81 | ||
82 | OP_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT | |
83 | OP_signature_sign OSSL_FUNC_SIGNATURE_SIGN | |
84 | ||
85 | OP_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT | |
86 | OP_signature_verify OSSL_FUNC_SIGNATURE_VERIFY | |
87 | ||
88 | OP_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT | |
89 | OP_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER | |
90 | ||
9c45222d MC |
91 | OP_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS |
92 | OP_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS | |
93 | OP_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS | |
94 | OP_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS | |
4f62f5d9 MC |
95 | |
96 | A signature algorithm implementation may not implement all of these functions. | |
97 | In order to be a consistent set of functions a provider must implement | |
98 | OP_signature_newctx and OP_signature_freectx. | |
99 | It must also implement both of OP_signature_sign_init and OP_signature_sign, | |
100 | or both of OP_signature_verify_init and OP_signature_verify, or both of | |
101 | OP_signature_verify_recover_init and OP_signature_verify_recover. | |
102 | All other functions are optional. | |
103 | ||
104 | A signature algorithm must also implement some mechanism for generating, | |
105 | loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. | |
106 | See L<provider-keymgmt(7)> for further details. | |
107 | ||
108 | =head2 Context Management Functions | |
109 | ||
110 | OP_signature_newctx() should create and return a pointer to a provider side | |
111 | structure for holding context information during a signature operation. | |
112 | A pointer to this context will be passed back in a number of the other signature | |
113 | operation function calls. | |
dfabee82 | 114 | The parameter I<provctx> is the provider context generated during provider |
d7cea0b8 | 115 | initialisation (see L<provider(7)>). |
4f62f5d9 MC |
116 | |
117 | OP_signature_freectx() is passed a pointer to the provider side signature | |
dfabee82 | 118 | context in the I<ctx> parameter. |
4f62f5d9 MC |
119 | This function should free any resources associated with that context. |
120 | ||
121 | OP_signature_dupctx() should duplicate the provider side signature context in | |
dfabee82 | 122 | the I<ctx> parameter and return the duplicate copy. |
4f62f5d9 MC |
123 | |
124 | =head2 Signing Functions | |
125 | ||
126 | OP_signature_sign_init() initialises a context for signing given a provider side | |
dfabee82 RL |
127 | signature context in the I<ctx> parameter, and a pointer to a provider key object |
128 | in the I<provkey> parameter. | |
4f62f5d9 MC |
129 | The key object should have been previously generated, loaded or imported into |
130 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
131 | provider-keymgmt(7)>. | |
132 | ||
133 | OP_signature_sign() performs the actual signing itself. | |
dfabee82 | 134 | A previously initialised signature context is passed in the I<ctx> |
4f62f5d9 | 135 | parameter. |
dfabee82 | 136 | The data to be signed is pointed to be the I<tbs> parameter which is I<tbslen> |
4f62f5d9 | 137 | bytes long. |
dfabee82 RL |
138 | Unless I<sig> is NULL, the signature should be written to the location pointed |
139 | to by the I<sig> parameter and it should not exceed I<sigsize> bytes in length. | |
140 | The length of the signature should be written to I<*siglen>. | |
141 | If I<sig> is NULL then the maximum length of the signature should be written to | |
142 | I<*siglen>. | |
4f62f5d9 MC |
143 | |
144 | =head2 Verify Functions | |
145 | ||
146 | OP_signature_verify_init() initialises a context for verifying a signature given | |
dfabee82 RL |
147 | a provider side signature context in the I<ctx> parameter, and a pointer to a |
148 | provider key object in the I<provkey> parameter. | |
4f62f5d9 MC |
149 | The key object should have been previously generated, loaded or imported into |
150 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
151 | provider-keymgmt(7)>. | |
152 | ||
153 | OP_signature_verify() performs the actual verification itself. | |
dfabee82 RL |
154 | A previously initialised signature context is passed in the I<ctx> parameter. |
155 | The data that the signature covers is pointed to be the I<tbs> parameter which | |
156 | is I<tbslen> bytes long. | |
157 | The signature is pointed to by the I<sig> parameter which is I<siglen> bytes | |
4f62f5d9 MC |
158 | long. |
159 | ||
160 | =head2 Verify Recover Functions | |
161 | ||
162 | OP_signature_verify_recover_init() initialises a context for recovering the | |
dfabee82 RL |
163 | signed data given a provider side signature context in the I<ctx> parameter, and |
164 | a pointer to a provider key object in the I<provkey> parameter. | |
4f62f5d9 MC |
165 | The key object should have been previously generated, loaded or imported into |
166 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
167 | provider-keymgmt(7)>. | |
168 | ||
169 | OP_signature_verify_recover() performs the actual verify recover itself. | |
dfabee82 RL |
170 | A previously initialised signature context is passed in the I<ctx> parameter. |
171 | The signature is pointed to by the I<sig> parameter which is I<siglen> bytes | |
4f62f5d9 | 172 | long. |
dfabee82 RL |
173 | Unless I<rout> is NULL, the recovered data should be written to the location |
174 | pointed to by I<rout> which should not exceed I<routsize> bytes in length. | |
175 | The length of the recovered data should be written to I<*routlen>. | |
176 | If I<rout> is NULL then the maximum size of the output buffer is written to | |
177 | the I<routlen> parameter. | |
4f62f5d9 MC |
178 | |
179 | =head2 Signature Parameters | |
180 | ||
181 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by | |
9c45222d | 182 | the OP_signature_get_ctx_params() and OP_signature_set_ctx_params() functions. |
4f62f5d9 | 183 | |
9c45222d | 184 | OP_signature_get_ctx_params() gets signature parameters associated with the |
dfabee82 | 185 | given provider side signature context I<ctx> and stored them in I<params>. |
9c45222d | 186 | OP_signature_set_ctx_params() sets the signature parameters associated with the |
dfabee82 | 187 | given provider side signature context I<ctx> to I<params>. |
4f62f5d9 MC |
188 | Any parameter settings are additional to any that were previously set. |
189 | ||
190 | Parameters currently recognised by built-in signature algorithms are as | |
191 | follows. | |
192 | Not all parameters are relevant to, or are understood by all signature | |
193 | algorithms: | |
194 | ||
195 | =over 4 | |
196 | ||
0c452a51 | 197 | =item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string> |
4f62f5d9 | 198 | |
9c45222d | 199 | Get or sets the name of the digest algorithm used for the input to the signature |
4f62f5d9 MC |
200 | functions. |
201 | ||
0c452a51 | 202 | =item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer> |
4f62f5d9 | 203 | |
9c45222d MC |
204 | Gets or sets the output size of the digest algorithm used for the input to the |
205 | signature functions. | |
72c162ab P |
206 | The length of the "digest-size" parameter should not exceed that of a B<size_t>. |
207 | ||
4f62f5d9 MC |
208 | |
209 | =back | |
210 | ||
9c45222d | 211 | OP_signature_gettable_ctx_params() and OP_signature_settable_ctx_params() get a |
79c44b4e | 212 | constant B<OSSL_PARAM> array that describes the gettable and settable parameters, |
9c45222d MC |
213 | i.e. parameters that can be used with OP_signature_get_ctx_params() and |
214 | OP_signature_set_ctx_params() respectively. | |
215 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. | |
216 | ||
4f62f5d9 MC |
217 | =head1 RETURN VALUES |
218 | ||
219 | OP_signature_newctx() and OP_signature_dupctx() should return the newly created | |
220 | provider side signature, or NULL on failure. | |
221 | ||
9c45222d | 222 | All other functions should return 1 for success or 0 on error. |
4f62f5d9 MC |
223 | |
224 | =head1 SEE ALSO | |
225 | ||
226 | L<provider(7)> | |
227 | ||
228 | =head1 HISTORY | |
229 | ||
230 | The provider SIGNATURE interface was introduced in OpenSSL 3.0. | |
231 | ||
232 | =head1 COPYRIGHT | |
233 | ||
234 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
235 | ||
236 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
237 | this file except in compliance with the License. You can obtain a copy | |
238 | in the file LICENSE in the source distribution or at | |
239 | L<https://www.openssl.org/source/license.html>. | |
240 | ||
241 | =cut |