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