]>
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 | 10 | |
23c48d94 | 11 | #include <openssl/core_dispatch.h> |
4f62f5d9 MC |
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 */ | |
5fdc95e4 | 21 | void *OSSL_FUNC_signature_newctx(void *provctx, const char *propq); |
363b1e5d DMSP |
22 | void OSSL_FUNC_signature_freectx(void *ctx); |
23 | void *OSSL_FUNC_signature_dupctx(void *ctx); | |
4f62f5d9 MC |
24 | |
25 | /* Signing */ | |
f187d4f9 P |
26 | int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey, |
27 | const OSSL_PARAM params[]); | |
363b1e5d DMSP |
28 | int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen, |
29 | size_t sigsize, const unsigned char *tbs, size_t tbslen); | |
4f62f5d9 MC |
30 | |
31 | /* Verifying */ | |
f187d4f9 P |
32 | int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey, |
33 | const OSSL_PARAM params[]); | |
363b1e5d DMSP |
34 | int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen, |
35 | const unsigned char *tbs, size_t tbslen); | |
4f62f5d9 MC |
36 | |
37 | /* Verify Recover */ | |
f187d4f9 P |
38 | int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey, |
39 | const OSSL_PARAM params[]); | |
363b1e5d DMSP |
40 | int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout, |
41 | size_t *routlen, size_t routsize, | |
42 | const unsigned char *sig, size_t siglen); | |
4f62f5d9 | 43 | |
d62be158 | 44 | /* Digest Sign */ |
363b1e5d | 45 | int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname, |
a07a70c7 | 46 | void *provkey, |
f187d4f9 | 47 | const OSSL_PARAM params[]); |
363b1e5d | 48 | int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data, |
d62be158 | 49 | size_t datalen); |
363b1e5d DMSP |
50 | int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig, |
51 | size_t *siglen, size_t sigsize); | |
52 | int OSSL_FUNC_signature_digest_sign(void *ctx, | |
2bd8190a | 53 | unsigned char *sig, size_t *siglen, |
d62be158 MC |
54 | size_t sigsize, const unsigned char *tbs, |
55 | size_t tbslen); | |
56 | ||
57 | /* Digest Verify */ | |
363b1e5d | 58 | int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname, |
a07a70c7 | 59 | void *provkey, |
f187d4f9 | 60 | const OSSL_PARAM params[]); |
363b1e5d DMSP |
61 | int OSSL_FUNC_signature_digest_verify_update(void *ctx, |
62 | const unsigned char *data, | |
63 | size_t datalen); | |
64 | int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig, | |
d62be158 | 65 | size_t siglen); |
363b1e5d | 66 | int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig, |
d62be158 MC |
67 | size_t siglen, const unsigned char *tbs, |
68 | size_t tbslen); | |
69 | ||
4f62f5d9 | 70 | /* Signature parameters */ |
363b1e5d | 71 | int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]); |
fb67126e TM |
72 | const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void *ctx, |
73 | void *provctx); | |
363b1e5d | 74 | int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]); |
fb67126e TM |
75 | const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void *ctx, |
76 | void *provctx); | |
d62be158 | 77 | /* MD parameters */ |
363b1e5d DMSP |
78 | int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]); |
79 | const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx); | |
80 | int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]); | |
81 | const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx); | |
d62be158 | 82 | |
4f62f5d9 MC |
83 | =head1 DESCRIPTION |
84 | ||
85 | This documentation is primarily aimed at provider authors. See L<provider(7)> | |
86 | for further information. | |
87 | ||
88 | The signature (OSSL_OP_SIGNATURE) operation enables providers to implement | |
89 | signature algorithms and make them available to applications via the API | |
fadb57e5 RS |
90 | functions L<EVP_PKEY_sign(3)>, |
91 | L<EVP_PKEY_verify(3)>, | |
92 | and L<EVP_PKEY_verify_recover(3)> (as well | |
4f62f5d9 MC |
93 | as other related functions). |
94 | ||
95 | All "functions" mentioned here are passed as function pointers between | |
318a9dfa RL |
96 | F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via |
97 | L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's | |
4f62f5d9 MC |
98 | provider_query_operation() function |
99 | (see L<provider-base(7)/Provider Functions>). | |
100 | ||
101 | All these "functions" have a corresponding function type definition | |
bd6e7fb7 | 102 | named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the |
318a9dfa | 103 | function pointer from an L<OSSL_DISPATCH(3)> element named |
363b1e5d DMSP |
104 | B<OSSL_FUNC_{name}>. |
105 | For example, the "function" OSSL_FUNC_signature_newctx() has these: | |
4f62f5d9 | 106 | |
5fdc95e4 | 107 | typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx, const char *propq); |
363b1e5d DMSP |
108 | static ossl_inline OSSL_FUNC_signature_newctx_fn |
109 | OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf); | |
4f62f5d9 | 110 | |
318a9dfa | 111 | L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as |
23c48d94 | 112 | macros in L<openssl-core_dispatch.h(7)>, as follows: |
4f62f5d9 | 113 | |
363b1e5d DMSP |
114 | OSSL_FUNC_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX |
115 | OSSL_FUNC_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX | |
116 | OSSL_FUNC_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX | |
4f62f5d9 | 117 | |
363b1e5d DMSP |
118 | OSSL_FUNC_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT |
119 | OSSL_FUNC_signature_sign OSSL_FUNC_SIGNATURE_SIGN | |
4f62f5d9 | 120 | |
363b1e5d DMSP |
121 | OSSL_FUNC_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT |
122 | OSSL_FUNC_signature_verify OSSL_FUNC_SIGNATURE_VERIFY | |
4f62f5d9 | 123 | |
363b1e5d DMSP |
124 | OSSL_FUNC_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT |
125 | OSSL_FUNC_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER | |
4f62f5d9 | 126 | |
363b1e5d DMSP |
127 | OSSL_FUNC_signature_digest_sign_init OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT |
128 | OSSL_FUNC_signature_digest_sign_update OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE | |
129 | OSSL_FUNC_signature_digest_sign_final OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL | |
130 | OSSL_FUNC_signature_digest_sign OSSL_FUNC_SIGNATURE_DIGEST_SIGN | |
d62be158 | 131 | |
363b1e5d DMSP |
132 | OSSL_FUNC_signature_digest_verify_init OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT |
133 | OSSL_FUNC_signature_digest_verify_update OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE | |
134 | OSSL_FUNC_signature_digest_verify_final OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL | |
135 | OSSL_FUNC_signature_digest_verify OSSL_FUNC_SIGNATURE_DIGEST_VERIFY | |
d62be158 | 136 | |
363b1e5d DMSP |
137 | OSSL_FUNC_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS |
138 | OSSL_FUNC_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS | |
139 | OSSL_FUNC_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS | |
140 | OSSL_FUNC_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS | |
4f62f5d9 | 141 | |
363b1e5d DMSP |
142 | OSSL_FUNC_signature_get_ctx_md_params OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS |
143 | OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS | |
144 | OSSL_FUNC_signature_set_ctx_md_params OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS | |
145 | OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS | |
d62be158 | 146 | |
4f62f5d9 | 147 | A signature algorithm implementation may not implement all of these functions. |
d62be158 | 148 | In order to be a consistent set of functions we must have at least a set of |
363b1e5d | 149 | context functions (OSSL_FUNC_signature_newctx and OSSL_FUNC_signature_freectx) as well as a |
d62be158 MC |
150 | set of "signature" functions, i.e. at least one of: |
151 | ||
152 | =over 4 | |
153 | ||
363b1e5d | 154 | =item OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign |
d62be158 | 155 | |
363b1e5d | 156 | =item OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify |
d62be158 | 157 | |
51b941ac | 158 | =item OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover |
d62be158 | 159 | |
363b1e5d | 160 | =item OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final |
d62be158 | 161 | |
363b1e5d | 162 | =item OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final |
d62be158 | 163 | |
363b1e5d | 164 | =item OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign |
d62be158 | 165 | |
363b1e5d | 166 | =item OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify |
d62be158 MC |
167 | |
168 | =back | |
169 | ||
363b1e5d | 170 | OSSL_FUNC_signature_set_ctx_params and OSSL_FUNC_signature_settable_ctx_params are optional, |
d62be158 | 171 | but if one of them is present then the other one must also be present. The same |
363b1e5d DMSP |
172 | applies to OSSL_FUNC_signature_get_ctx_params and OSSL_FUNC_signature_gettable_ctx_params, as |
173 | well as the "md_params" functions. The OSSL_FUNC_signature_dupctx function is optional. | |
4f62f5d9 MC |
174 | |
175 | A signature algorithm must also implement some mechanism for generating, | |
176 | loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. | |
177 | See L<provider-keymgmt(7)> for further details. | |
178 | ||
179 | =head2 Context Management Functions | |
180 | ||
363b1e5d | 181 | OSSL_FUNC_signature_newctx() should create and return a pointer to a provider side |
4f62f5d9 MC |
182 | structure for holding context information during a signature operation. |
183 | A pointer to this context will be passed back in a number of the other signature | |
184 | operation function calls. | |
dfabee82 | 185 | The parameter I<provctx> is the provider context generated during provider |
5fdc95e4 MC |
186 | initialisation (see L<provider(7)>). The I<propq> parameter is a property query |
187 | string that may be (optionally) used by the provider during any "fetches" that | |
188 | it may perform (if it performs any). | |
4f62f5d9 | 189 | |
363b1e5d | 190 | OSSL_FUNC_signature_freectx() is passed a pointer to the provider side signature |
dfabee82 | 191 | context in the I<ctx> parameter. |
4f62f5d9 MC |
192 | This function should free any resources associated with that context. |
193 | ||
363b1e5d | 194 | OSSL_FUNC_signature_dupctx() should duplicate the provider side signature context in |
dfabee82 | 195 | the I<ctx> parameter and return the duplicate copy. |
4f62f5d9 MC |
196 | |
197 | =head2 Signing Functions | |
198 | ||
363b1e5d | 199 | OSSL_FUNC_signature_sign_init() initialises a context for signing given a provider side |
dfabee82 RL |
200 | signature context in the I<ctx> parameter, and a pointer to a provider key object |
201 | in the I<provkey> parameter. | |
f187d4f9 P |
202 | The I<params>, if not NULL, should be set on the context in a manner similar to |
203 | using OSSL_FUNC_signature_set_ctx_params(). | |
4f62f5d9 MC |
204 | The key object should have been previously generated, loaded or imported into |
205 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
206 | provider-keymgmt(7)>. | |
207 | ||
363b1e5d | 208 | OSSL_FUNC_signature_sign() performs the actual signing itself. |
dfabee82 | 209 | A previously initialised signature context is passed in the I<ctx> |
4f62f5d9 | 210 | parameter. |
dfabee82 | 211 | The data to be signed is pointed to be the I<tbs> parameter which is I<tbslen> |
4f62f5d9 | 212 | bytes long. |
dfabee82 RL |
213 | Unless I<sig> is NULL, the signature should be written to the location pointed |
214 | to by the I<sig> parameter and it should not exceed I<sigsize> bytes in length. | |
215 | The length of the signature should be written to I<*siglen>. | |
216 | If I<sig> is NULL then the maximum length of the signature should be written to | |
217 | I<*siglen>. | |
4f62f5d9 MC |
218 | |
219 | =head2 Verify Functions | |
220 | ||
363b1e5d | 221 | OSSL_FUNC_signature_verify_init() initialises a context for verifying a signature given |
dfabee82 RL |
222 | a provider side signature context in the I<ctx> parameter, and a pointer to a |
223 | provider key object in the I<provkey> parameter. | |
f187d4f9 P |
224 | The I<params>, if not NULL, should be set on the context in a manner similar to |
225 | using OSSL_FUNC_signature_set_ctx_params(). | |
4f62f5d9 MC |
226 | The key object should have been previously generated, loaded or imported into |
227 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
228 | provider-keymgmt(7)>. | |
229 | ||
363b1e5d | 230 | OSSL_FUNC_signature_verify() performs the actual verification itself. |
dfabee82 RL |
231 | A previously initialised signature context is passed in the I<ctx> parameter. |
232 | The data that the signature covers is pointed to be the I<tbs> parameter which | |
233 | is I<tbslen> bytes long. | |
234 | The signature is pointed to by the I<sig> parameter which is I<siglen> bytes | |
4f62f5d9 MC |
235 | long. |
236 | ||
237 | =head2 Verify Recover Functions | |
238 | ||
363b1e5d | 239 | OSSL_FUNC_signature_verify_recover_init() initialises a context for recovering the |
dfabee82 RL |
240 | signed data given a provider side signature context in the I<ctx> parameter, and |
241 | a pointer to a provider key object in the I<provkey> parameter. | |
f187d4f9 P |
242 | The I<params>, if not NULL, should be set on the context in a manner similar to |
243 | using OSSL_FUNC_signature_set_ctx_params(). | |
4f62f5d9 MC |
244 | The key object should have been previously generated, loaded or imported into |
245 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
246 | provider-keymgmt(7)>. | |
247 | ||
363b1e5d | 248 | OSSL_FUNC_signature_verify_recover() performs the actual verify recover itself. |
dfabee82 RL |
249 | A previously initialised signature context is passed in the I<ctx> parameter. |
250 | The signature is pointed to by the I<sig> parameter which is I<siglen> bytes | |
4f62f5d9 | 251 | long. |
dfabee82 RL |
252 | Unless I<rout> is NULL, the recovered data should be written to the location |
253 | pointed to by I<rout> which should not exceed I<routsize> bytes in length. | |
254 | The length of the recovered data should be written to I<*routlen>. | |
255 | If I<rout> is NULL then the maximum size of the output buffer is written to | |
256 | the I<routlen> parameter. | |
4f62f5d9 | 257 | |
d62be158 MC |
258 | =head2 Digest Sign Functions |
259 | ||
363b1e5d | 260 | OSSL_FUNC_signature_digeset_sign_init() initialises a context for signing given a |
d62be158 | 261 | provider side signature context in the I<ctx> parameter, and a pointer to a |
f187d4f9 P |
262 | provider key object in the I<provkey> parameter. |
263 | The I<params>, if not NULL, should be set on the context in a manner similar to | |
264 | using OSSL_FUNC_signature_set_ctx_params() and | |
265 | OSSL_FUNC_signature_set_ctx_md_params(). | |
266 | The key object should have been | |
d62be158 MC |
267 | previously generated, loaded or imported into the provider using the |
268 | key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. | |
a07a70c7 | 269 | The name of the digest to be used will be in the I<mdname> parameter. |
d62be158 | 270 | |
363b1e5d | 271 | OSSL_FUNC_signature_digest_sign_update() provides data to be signed in the I<data> |
d62be158 MC |
272 | parameter which should be of length I<datalen>. A previously initialised |
273 | signature context is passed in the I<ctx> parameter. This function may be called | |
af0d4136 | 274 | multiple times to cumulatively add data to be signed. |
d62be158 | 275 | |
363b1e5d DMSP |
276 | OSSL_FUNC_signature_digest_sign_final() finalises a signature operation previously |
277 | started through OSSL_FUNC_signature_digest_sign_init() and | |
278 | OSSL_FUNC_signature_digest_sign_update() calls. Once finalised no more data will be | |
279 | added through OSSL_FUNC_signature_digest_sign_update(). A previously initialised | |
d62be158 MC |
280 | signature context is passed in the I<ctx> parameter. Unless I<sig> is NULL, the |
281 | signature should be written to the location pointed to by the I<sig> parameter | |
282 | and it should not exceed I<sigsize> bytes in length. The length of the signature | |
283 | should be written to I<*siglen>. If I<sig> is NULL then the maximum length of | |
284 | the signature should be written to I<*siglen>. | |
285 | ||
363b1e5d DMSP |
286 | OSSL_FUNC_signature_digest_sign() implements a "one shot" digest sign operation |
287 | previously started through OSSL_FUNC_signature_digeset_sign_init(). A previously | |
d62be158 MC |
288 | initialised signature context is passed in the I<ctx> parameter. The data to be |
289 | signed is in I<tbs> which should be I<tbslen> bytes long. Unless I<sig> is NULL, | |
290 | the signature should be written to the location pointed to by the I<sig> | |
291 | parameter and it should not exceed I<sigsize> bytes in length. The length of the | |
292 | signature should be written to I<*siglen>. If I<sig> is NULL then the maximum | |
293 | length of the signature should be written to I<*siglen>. | |
294 | ||
295 | =head2 Digest Verify Functions | |
296 | ||
363b1e5d | 297 | OSSL_FUNC_signature_digeset_verify_init() initialises a context for verifying given a |
d62be158 | 298 | provider side verification context in the I<ctx> parameter, and a pointer to a |
f187d4f9 P |
299 | provider key object in the I<provkey> parameter. |
300 | The I<params>, if not NULL, should be set on the context in a manner similar to | |
301 | OSSL_FUNC_signature_set_ctx_params() and | |
302 | OSSL_FUNC_signature_set_ctx_md_params(). | |
303 | The key object should have been | |
d62be158 MC |
304 | previously generated, loaded or imported into the provider using the |
305 | key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. | |
a07a70c7 | 306 | The name of the digest to be used will be in the I<mdname> parameter. |
d62be158 | 307 | |
363b1e5d | 308 | OSSL_FUNC_signature_digest_verify_update() provides data to be verified in the I<data> |
d62be158 MC |
309 | parameter which should be of length I<datalen>. A previously initialised |
310 | verification context is passed in the I<ctx> parameter. This function may be | |
af0d4136 | 311 | called multiple times to cumulatively add data to be verified. |
d62be158 | 312 | |
363b1e5d DMSP |
313 | OSSL_FUNC_signature_digest_verify_final() finalises a verification operation previously |
314 | started through OSSL_FUNC_signature_digest_verify_init() and | |
315 | OSSL_FUNC_signature_digest_verify_update() calls. Once finalised no more data will be | |
316 | added through OSSL_FUNC_signature_digest_verify_update(). A previously initialised | |
d62be158 MC |
317 | verification context is passed in the I<ctx> parameter. The signature to be |
318 | verified is in I<sig> which is I<siglen> bytes long. | |
319 | ||
363b1e5d DMSP |
320 | OSSL_FUNC_signature_digest_verify() implements a "one shot" digest verify operation |
321 | previously started through OSSL_FUNC_signature_digeset_verify_init(). A previously | |
d62be158 MC |
322 | initialised verification context is passed in the I<ctx> parameter. The data to be |
323 | verified is in I<tbs> which should be I<tbslen> bytes long. The signature to be | |
324 | verified is in I<sig> which is I<siglen> bytes long. | |
325 | ||
b8086652 | 326 | =head2 Signature parameters |
4f62f5d9 MC |
327 | |
328 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by | |
363b1e5d | 329 | the OSSL_FUNC_signature_get_ctx_params() and OSSL_FUNC_signature_set_ctx_params() functions. |
4f62f5d9 | 330 | |
363b1e5d | 331 | OSSL_FUNC_signature_get_ctx_params() gets signature parameters associated with the |
dfabee82 | 332 | given provider side signature context I<ctx> and stored them in I<params>. |
f59612fe P |
333 | Passing NULL for I<params> should return true. |
334 | ||
363b1e5d | 335 | OSSL_FUNC_signature_set_ctx_params() sets the signature parameters associated with the |
dfabee82 | 336 | given provider side signature context I<ctx> to I<params>. |
4f62f5d9 | 337 | Any parameter settings are additional to any that were previously set. |
f59612fe | 338 | Passing NULL for I<params> should return true. |
4f62f5d9 | 339 | |
b8086652 | 340 | Common parameters currently recognised by built-in signature algorithms are as |
4f62f5d9 | 341 | follows. |
4f62f5d9 MC |
342 | |
343 | =over 4 | |
344 | ||
0c452a51 | 345 | =item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string> |
4f62f5d9 | 346 | |
26372a4d TM |
347 | Get or sets the name of the digest algorithm used for the input to the |
348 | signature functions. It is required in order to calculate the "algorithm-id". | |
b8086652 | 349 | |
26372a4d | 350 | =item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string> |
b8086652 SL |
351 | |
352 | Sets the name of the property query associated with the "digest" algorithm. | |
353 | NULL is used if this optional value is not set. | |
4f62f5d9 | 354 | |
0c452a51 | 355 | =item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer> |
4f62f5d9 | 356 | |
9c45222d MC |
357 | Gets or sets the output size of the digest algorithm used for the input to the |
358 | signature functions. | |
72c162ab P |
359 | The length of the "digest-size" parameter should not exceed that of a B<size_t>. |
360 | ||
26372a4d | 361 | =item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string> |
edd3b7a3 SL |
362 | |
363 | Gets the DER encoded AlgorithmIdentifier that corresponds to the combination of | |
364 | signature algorithm and digest algorithm for the signature operation. | |
365 | ||
f3090fc7 | 366 | =item "nonce-type" (B<OSSL_SIGNATURE_PARAM_NONCE_TYPE>) <unsigned integer> |
367 | ||
ff7b32e1 JM |
368 | Set this to 1 to use deterministic digital signature generation with |
369 | ECDSA or DSA, as defined in RFC 6979 (see Section 3.2 "Generation of | |
370 | k"). In this case, the "digest" parameter must be explicitly set | |
371 | (otherwise, deterministic nonce generation will fail). Before using | |
372 | deterministic digital signature generation, please read RFC 6979 | |
373 | Section 4 "Security Considerations". The default value for | |
374 | "nonce-type" is 0 and results in a random value being used for the | |
375 | nonce B<k> as defined in FIPS 186-4 Section 6.3 "Secret Number | |
376 | Generation". | |
f3090fc7 | 377 | |
edd3b7a3 SL |
378 | =item "kat" (B<OSSL_SIGNATURE_PARAM_KAT>) <unsigned integer> |
379 | ||
380 | Sets a flag to modify the sign operation to return an error if the initial | |
381 | calculated signature is invalid. | |
382 | In the normal mode of operation - new random values are chosen until the | |
383 | signature operation succeeds. | |
57cd10dd | 384 | By default it retries until a signature is calculated. |
edd3b7a3 SL |
385 | Setting the value to 0 causes the sign operation to retry, |
386 | otherwise the sign operation is only tried once and returns whether or not it | |
387 | was successful. | |
af0d4136 | 388 | Known answer tests can be performed if the random generator is overridden to |
edd3b7a3 | 389 | supply known values that either pass or fail. |
4f62f5d9 MC |
390 | |
391 | =back | |
392 | ||
363b1e5d | 393 | OSSL_FUNC_signature_gettable_ctx_params() and OSSL_FUNC_signature_settable_ctx_params() get a |
318a9dfa | 394 | constant L<OSSL_PARAM(3)> array that describes the gettable and settable parameters, |
363b1e5d DMSP |
395 | i.e. parameters that can be used with OSSL_FUNC_signature_get_ctx_params() and |
396 | OSSL_FUNC_signature_set_ctx_params() respectively. | |
9c45222d | 397 | |
b8086652 | 398 | =head2 MD parameters |
d62be158 MC |
399 | |
400 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by | |
363b1e5d | 401 | the OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params() |
d62be158 MC |
402 | functions. |
403 | ||
363b1e5d | 404 | OSSL_FUNC_signature_get_md_ctx_params() gets digest parameters associated with the |
d62be158 | 405 | given provider side digest signature context I<ctx> and stores them in I<params>. |
f59612fe P |
406 | Passing NULL for I<params> should return true. |
407 | ||
363b1e5d | 408 | OSSL_FUNC_signature_set_ms_ctx_params() sets the digest parameters associated with the |
d62be158 MC |
409 | given provider side digest signature context I<ctx> to I<params>. |
410 | Any parameter settings are additional to any that were previously set. | |
f59612fe | 411 | Passing NULL for I<params> should return true. |
d62be158 MC |
412 | |
413 | Parameters currently recognised by built-in signature algorithms are the same | |
414 | as those for built-in digest algorithms. See | |
415 | L<provider-digest(7)/Digest Parameters> for further information. | |
416 | ||
363b1e5d | 417 | OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params() |
318a9dfa | 418 | get a constant L<OSSL_PARAM(3)> array that describes the gettable and settable |
d62be158 | 419 | digest parameters, i.e. parameters that can be used with |
363b1e5d | 420 | OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params() |
318a9dfa | 421 | respectively. |
d62be158 | 422 | |
4f62f5d9 MC |
423 | =head1 RETURN VALUES |
424 | ||
363b1e5d | 425 | OSSL_FUNC_signature_newctx() and OSSL_FUNC_signature_dupctx() should return the newly created |
b2023d5d | 426 | provider side signature context, or NULL on failure. |
4f62f5d9 | 427 | |
363b1e5d DMSP |
428 | OSSL_FUNC_signature_gettable_ctx_params(), OSSL_FUNC_signature_settable_ctx_params(), |
429 | OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params(), | |
318a9dfa | 430 | return the gettable or settable parameters in a constant L<OSSL_PARAM(3)> array. |
d62be158 | 431 | |
9c45222d | 432 | All other functions should return 1 for success or 0 on error. |
4f62f5d9 MC |
433 | |
434 | =head1 SEE ALSO | |
435 | ||
436 | L<provider(7)> | |
437 | ||
438 | =head1 HISTORY | |
439 | ||
440 | The provider SIGNATURE interface was introduced in OpenSSL 3.0. | |
441 | ||
442 | =head1 COPYRIGHT | |
443 | ||
0ce7d1f3 | 444 | Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. |
4f62f5d9 MC |
445 | |
446 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
447 | this file except in compliance with the License. You can obtain a copy | |
448 | in the file LICENSE in the source distribution or at | |
449 | L<https://www.openssl.org/source/license.html>. | |
450 | ||
451 | =cut |