1=pod 2 3=head1 NAME 4 5provider-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_dispatch.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 *OSSL_FUNC_signature_newctx(void *provctx, const char *propq); 22 void OSSL_FUNC_signature_freectx(void *ctx); 23 void *OSSL_FUNC_signature_dupctx(void *ctx); 24 25 /* Get the key types that a signature algorithm supports */ 26 const char **OSSL_FUNC_signature_query_key_types(void); 27 28 /* Signing */ 29 int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey, 30 const OSSL_PARAM params[]); 31 int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen, 32 size_t sigsize, const unsigned char *tbs, size_t tbslen); 33 int OSSL_FUNC_signature_sign_message_init(void *ctx, void *provkey, 34 const OSSL_PARAM params[]); 35 int OSSL_FUNC_signature_sign_message_update(void *ctx, const unsigned char *in, 36 size_t inlen); 37 int OSSL_FUNC_signature_sign_message_final(void *ctx, unsigned char *sig, 38 size_t *siglen, size_t sigsize); 39 40 /* Verifying */ 41 int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey, 42 const OSSL_PARAM params[]); 43 int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen, 44 const unsigned char *tbs, size_t tbslen); 45 int OSSL_FUNC_signature_verify_message_init(void *ctx, void *provkey, 46 const OSSL_PARAM params[]); 47 int OSSL_FUNC_signature_verify_message_update(void *ctx, const unsigned char *in, 48 size_t inlen); 49 /* 50 * OSSL_FUNC_signature_verify_message_final requires that the signature to be 51 * verified is specified via a "signature" OSSL_PARAM, which is given with a 52 * previous call of OSSL_FUNC_signature_set_ctx_params(). 53 */ 54 int OSSL_FUNC_signature_verify_message_final(void *ctx); 55 56 /* Verify Recover */ 57 int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey, 58 const OSSL_PARAM params[]); 59 int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout, 60 size_t *routlen, size_t routsize, 61 const unsigned char *sig, size_t siglen); 62 63 /* Digest Sign */ 64 int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname, 65 void *provkey, 66 const OSSL_PARAM params[]); 67 int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data, 68 size_t datalen); 69 int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig, 70 size_t *siglen, size_t sigsize); 71 int OSSL_FUNC_signature_digest_sign(void *ctx, 72 unsigned char *sig, size_t *siglen, 73 size_t sigsize, const unsigned char *tbs, 74 size_t tbslen); 75 76 /* Digest Verify */ 77 int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname, 78 void *provkey, 79 const OSSL_PARAM params[]); 80 int OSSL_FUNC_signature_digest_verify_update(void *ctx, 81 const unsigned char *data, 82 size_t datalen); 83 int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig, 84 size_t siglen); 85 int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig, 86 size_t siglen, const unsigned char *tbs, 87 size_t tbslen); 88 89 /* Signature parameters */ 90 int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]); 91 const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void *ctx, 92 void *provctx); 93 int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]); 94 const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void *ctx, 95 void *provctx); 96 /* MD parameters */ 97 int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]); 98 const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx); 99 int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]); 100 const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx); 101 102=head1 DESCRIPTION 103 104This documentation is primarily aimed at provider authors. See L<provider(7)> 105for further information. 106 107The signature (OSSL_OP_SIGNATURE) operation enables providers to implement 108signature algorithms and make them available to applications via the API 109functions L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify(3)>, 110and L<EVP_PKEY_verify_recover(3)> (as well 111as other related functions). 112 113All "functions" mentioned here are passed as function pointers between 114F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via 115L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's 116provider_query_operation() function 117(see L<provider-base(7)/Provider Functions>). 118 119All these "functions" have a corresponding function type definition 120named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the 121function pointer from an L<OSSL_DISPATCH(3)> element named 122B<OSSL_FUNC_{name}>. 123For example, the "function" OSSL_FUNC_signature_newctx() has these: 124 125 typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx, const char *propq); 126 static ossl_inline OSSL_FUNC_signature_newctx_fn 127 OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf); 128 129L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as 130macros in L<openssl-core_dispatch.h(7)>, as follows: 131 132 OSSL_FUNC_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX 133 OSSL_FUNC_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX 134 OSSL_FUNC_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX 135 136 OSSL_FUNC_signature_query_key_types OSSL_FUNC_SIGNATURE_QUERY_KEY_TYPES 137 138 OSSL_FUNC_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT 139 OSSL_FUNC_signature_sign OSSL_FUNC_SIGNATURE_SIGN 140 OSSL_FUNC_signature_sign_message_init OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_INIT 141 OSSL_FUNC_signature_sign_message_update OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_UPDATE 142 OSSL_FUNC_signature_sign_message_final OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_FINAL 143 144 OSSL_FUNC_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT 145 OSSL_FUNC_signature_verify OSSL_FUNC_SIGNATURE_VERIFY 146 OSSL_FUNC_signature_verify_message_init OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_INIT 147 OSSL_FUNC_signature_verify_message_update OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_UPDATE 148 OSSL_FUNC_signature_verify_message_final OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_FINAL 149 150 OSSL_FUNC_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT 151 OSSL_FUNC_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER 152 153 OSSL_FUNC_signature_digest_sign_init OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT 154 OSSL_FUNC_signature_digest_sign_update OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE 155 OSSL_FUNC_signature_digest_sign_final OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL 156 OSSL_FUNC_signature_digest_sign OSSL_FUNC_SIGNATURE_DIGEST_SIGN 157 158 OSSL_FUNC_signature_digest_verify_init OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT 159 OSSL_FUNC_signature_digest_verify_update OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE 160 OSSL_FUNC_signature_digest_verify_final OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL 161 OSSL_FUNC_signature_digest_verify OSSL_FUNC_SIGNATURE_DIGEST_VERIFY 162 163 OSSL_FUNC_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS 164 OSSL_FUNC_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS 165 OSSL_FUNC_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS 166 OSSL_FUNC_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS 167 168 OSSL_FUNC_signature_get_ctx_md_params OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS 169 OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS 170 OSSL_FUNC_signature_set_ctx_md_params OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS 171 OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS 172 173A signature algorithm implementation may not implement all of these functions. 174In order to be a consistent set of functions we must have at least a set of 175context functions (OSSL_FUNC_signature_newctx and OSSL_FUNC_signature_freectx) as well as a 176set of "signature" functions, i.e. at least one of: 177 178=over 4 179 180=item OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign 181 182=item OSSL_FUNC_signature_sign_message_init and OSSL_FUNC_signature_sign 183 184=item OSSL_FUNC_signature_sign_message_init, OSSL_FUNC_signature_sign_message_update and OSSL_FUNC_signature_sign_message_final 185 186=item OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify 187 188=item OSSL_FUNC_signature_verify_message_init and OSSL_FUNC_signature_verify 189 190=item OSSL_FUNC_signature_verify_message_init, OSSL_FUNC_signature_verify_message_update and OSSL_FUNC_signature_verify_message_final 191 192=item OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover 193 194=item OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final 195 196=item OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final 197 198=item OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign 199 200=item OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify 201 202=back 203 204OSSL_FUNC_signature_set_ctx_params and OSSL_FUNC_signature_settable_ctx_params are optional, 205but if one of them is present then the other one must also be present. The same 206applies to OSSL_FUNC_signature_get_ctx_params and OSSL_FUNC_signature_gettable_ctx_params, as 207well as the "md_params" functions. The OSSL_FUNC_signature_dupctx function is optional. 208 209A signature algorithm must also implement some mechanism for generating, 210loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. 211See L<provider-keymgmt(7)> for further details. 212 213=head2 Context Management Functions 214 215OSSL_FUNC_signature_newctx() should create and return a pointer to a provider side 216structure for holding context information during a signature operation. 217A pointer to this context will be passed back in a number of the other signature 218operation function calls. 219The parameter I<provctx> is the provider context generated during provider 220initialisation (see L<provider(7)>). The I<propq> parameter is a property query 221string that may be (optionally) used by the provider during any "fetches" that 222it may perform (if it performs any). 223 224OSSL_FUNC_signature_freectx() is passed a pointer to the provider side signature 225context in the I<ctx> parameter. 226This function should free any resources associated with that context. 227 228OSSL_FUNC_signature_dupctx() should duplicate the provider side signature context in 229the I<ctx> parameter and return the duplicate copy. 230 231=head2 Signing Functions 232 233OSSL_FUNC_signature_sign_init() initialises a context for signing given a provider side 234signature context in the I<ctx> parameter, and a pointer to a provider key object 235in the I<provkey> parameter. 236The I<params>, if not NULL, should be set on the context in a manner similar to 237using OSSL_FUNC_signature_set_ctx_params(). 238The key object should have been previously generated, loaded or imported into 239the provider using the key management (OSSL_OP_KEYMGMT) operation (see 240L<provider-keymgmt(7)>). 241 242OSSL_FUNC_signature_sign() performs the actual signing itself. 243A previously initialised signature context is passed in the I<ctx> 244parameter. 245The data to be signed is pointed to be the I<tbs> parameter which is I<tbslen> 246bytes long. 247Unless I<sig> is NULL, the signature should be written to the location pointed 248to by the I<sig> parameter and it should not exceed I<sigsize> bytes in length. 249The length of the signature should be written to I<*siglen>. 250If I<sig> is NULL then the maximum length of the signature should be written to 251I<*siglen>. 252 253=head2 Message Signing Functions 254 255These functions are suitable for providers that implement algorithms that 256accumulate a full message and sign the result of that accumulation, such as 257RSA-SHA256. 258 259OSSL_FUNC_signature_sign_message_init() initialises a context for signing a 260message given a provider side signature context in the I<ctx> parameter, and a 261pointer to a provider key object in the I<provkey> parameter. 262The I<params>, if not NULL, should be set on the context in a manner similar to 263using OSSL_FUNC_signature_set_ctx_params(). 264The key object should have been previously generated, loaded or imported into 265the provider using the key management (OSSL_OP_KEYMGMT) operation (see 266L<provider-keymgmt(7)>). 267 268OSSL_FUNC_signature_sign_message_update() gathers the data pointed at by 269I<in>, which is I<inlen> bytes long. 270 271OSSL_FUNC_signature_sign_message_final() performs the actual signing on the 272data that was gathered with OSSL_FUNC_signature_sign_message_update(). 273 274OSSL_FUNC_signature_sign() can be used for one-shot signature calls. In that 275case, I<tbs> is expected to be the whole message to be signed, I<tbslen> bytes 276long. 277 278For both OSSL_FUNC_signature_sign_message_final() and OSSL_FUNC_signature_sign(), 279if I<sig> is not NULL, the signature should be written to the location pointed 280to by I<sig>, and it should not exceed I<sigsize> bytes in length. 281The length of the signature should be written to I<*siglen>. 282If I<sig> is NULL then the maximum length of the signature should be written to 283I<*siglen>. 284 285=head2 Verify Functions 286 287OSSL_FUNC_signature_verify_init() initialises a context for verifying a signature given 288a provider side signature context in the I<ctx> parameter, and a pointer to a 289provider key object in the I<provkey> parameter. 290The I<params>, if not NULL, should be set on the context in a manner similar to 291using OSSL_FUNC_signature_set_ctx_params(). 292The key object should have been previously generated, loaded or imported into 293the provider using the key management (OSSL_OP_KEYMGMT) operation (see 294L<provider-keymgmt(7)>). 295 296OSSL_FUNC_signature_verify() performs the actual verification itself. 297A previously initialised signature context is passed in the I<ctx> parameter. 298The data that the signature covers is pointed to be the I<tbs> parameter which 299is I<tbslen> bytes long. 300The signature is pointed to by the I<sig> parameter which is I<siglen> bytes 301long. 302 303=head2 Message Verify Functions 304 305These functions are suitable for providers that implement algorithms that 306accumulate a full message and verify a signature on the result of that 307accumulation, such as RSA-SHA256. 308 309OSSL_FUNC_signature_verify_message_init() initialises a context for verifying 310a signature on a message given a provider side signature context in the I<ctx> 311parameter, and a pointer to a provider key object in the I<provkey> parameter. 312The I<params>, if not NULL, should be set on the context in a manner similar to 313using OSSL_FUNC_signature_set_ctx_params(). 314The key object should have been previously generated, loaded or imported into 315the provider using the key management (OSSL_OP_KEYMGMT) operation (see 316L<provider-keymgmt(7)>). 317 318OSSL_FUNC_signature_verify_message_update() gathers the data pointed at by 319I<in>, which is I<inlen> bytes long. 320 321OSSL_FUNC_signature_verify_message_final() performs the actual verification on 322the data that was gathered with OSSL_FUNC_signature_verify_message_update(). 323The signature itself must have been passed through the "signature" 324(B<OSSL_SIGNATURE_PARAM_SIGNATURE>) L<Signature parameter|/Signature parameters> 325before this function is called. 326 327OSSL_FUNC_signature_verify() can be used for one-shot verification calls. In 328that case, I<tbs> is expected to be the whole message to be verified on, 329I<tbslen> bytes long. 330 331=head2 Verify Recover Functions 332 333OSSL_FUNC_signature_verify_recover_init() initialises a context for recovering the 334signed data given a provider side signature context in the I<ctx> parameter, and 335a pointer to a provider key object in the I<provkey> parameter. 336The I<params>, if not NULL, should be set on the context in a manner similar to 337using OSSL_FUNC_signature_set_ctx_params(). 338The key object should have been previously generated, loaded or imported into 339the provider using the key management (OSSL_OP_KEYMGMT) operation (see 340L<provider-keymgmt(7)>). 341 342OSSL_FUNC_signature_verify_recover() performs the actual verify recover itself. 343A previously initialised signature context is passed in the I<ctx> parameter. 344The signature is pointed to by the I<sig> parameter which is I<siglen> bytes 345long. 346Unless I<rout> is NULL, the recovered data should be written to the location 347pointed to by I<rout> which should not exceed I<routsize> bytes in length. 348The length of the recovered data should be written to I<*routlen>. 349If I<rout> is NULL then the maximum size of the output buffer is written to 350the I<routlen> parameter. 351 352=head2 Digest Sign Functions 353 354OSSL_FUNC_signature_digest_sign_init() initialises a context for signing given a 355provider side signature context in the I<ctx> parameter, and a pointer to a 356provider key object in the I<provkey> parameter. 357The I<params>, if not NULL, should be set on the context in a manner similar to 358using OSSL_FUNC_signature_set_ctx_params() and 359OSSL_FUNC_signature_set_ctx_md_params(). 360The key object should have been 361previously generated, loaded or imported into the provider using the 362key management (OSSL_OP_KEYMGMT) operation (see L<provider-keymgmt(7)>). 363The name of the digest to be used will be in the I<mdname> parameter. 364 365OSSL_FUNC_signature_digest_sign_update() provides data to be signed in the I<data> 366parameter which should be of length I<datalen>. A previously initialised 367signature context is passed in the I<ctx> parameter. This function may be called 368multiple times to cumulatively add data to be signed. 369 370OSSL_FUNC_signature_digest_sign_final() finalises a signature operation previously 371started through OSSL_FUNC_signature_digest_sign_init() and 372OSSL_FUNC_signature_digest_sign_update() calls. Once finalised no more data will be 373added through OSSL_FUNC_signature_digest_sign_update(). A previously initialised 374signature context is passed in the I<ctx> parameter. Unless I<sig> is NULL, the 375signature should be written to the location pointed to by the I<sig> parameter 376and it should not exceed I<sigsize> bytes in length. The length of the signature 377should be written to I<*siglen>. If I<sig> is NULL then the maximum length of 378the signature should be written to I<*siglen>. 379 380OSSL_FUNC_signature_digest_sign() implements a "one shot" digest sign operation 381previously started through OSSL_FUNC_signature_digeset_sign_init(). A previously 382initialised signature context is passed in the I<ctx> parameter. The data to be 383signed is in I<tbs> which should be I<tbslen> bytes long. Unless I<sig> is NULL, 384the signature should be written to the location pointed to by the I<sig> 385parameter and it should not exceed I<sigsize> bytes in length. The length of the 386signature should be written to I<*siglen>. If I<sig> is NULL then the maximum 387length of the signature should be written to I<*siglen>. 388 389=head2 Digest Verify Functions 390 391OSSL_FUNC_signature_digeset_verify_init() initialises a context for verifying given a 392provider side verification context in the I<ctx> parameter, and a pointer to a 393provider key object in the I<provkey> parameter. 394The I<params>, if not NULL, should be set on the context in a manner similar to 395OSSL_FUNC_signature_set_ctx_params() and 396OSSL_FUNC_signature_set_ctx_md_params(). 397The key object should have been 398previously generated, loaded or imported into the provider using the 399key management (OSSL_OP_KEYMGMT) operation (see L<provider-keymgmt(7)>). 400The name of the digest to be used will be in the I<mdname> parameter. 401 402OSSL_FUNC_signature_digest_verify_update() provides data to be verified in the I<data> 403parameter which should be of length I<datalen>. A previously initialised 404verification context is passed in the I<ctx> parameter. This function may be 405called multiple times to cumulatively add data to be verified. 406 407OSSL_FUNC_signature_digest_verify_final() finalises a verification operation previously 408started through OSSL_FUNC_signature_digest_verify_init() and 409OSSL_FUNC_signature_digest_verify_update() calls. Once finalised no more data will be 410added through OSSL_FUNC_signature_digest_verify_update(). A previously initialised 411verification context is passed in the I<ctx> parameter. The signature to be 412verified is in I<sig> which is I<siglen> bytes long. 413 414OSSL_FUNC_signature_digest_verify() implements a "one shot" digest verify operation 415previously started through OSSL_FUNC_signature_digeset_verify_init(). A previously 416initialised verification context is passed in the I<ctx> parameter. The data to be 417verified is in I<tbs> which should be I<tbslen> bytes long. The signature to be 418verified is in I<sig> which is I<siglen> bytes long. 419 420=head2 Signature parameters 421 422See L<OSSL_PARAM(3)> for further details on the parameters structure used by 423the OSSL_FUNC_signature_get_ctx_params() and OSSL_FUNC_signature_set_ctx_params() functions. 424 425OSSL_FUNC_signature_get_ctx_params() gets signature parameters associated with the 426given provider side signature context I<ctx> and stored them in I<params>. 427Passing NULL for I<params> should return true. 428 429OSSL_FUNC_signature_set_ctx_params() sets the signature parameters associated with the 430given provider side signature context I<ctx> to I<params>. 431Any parameter settings are additional to any that were previously set. 432Passing NULL for I<params> should return true. 433 434Common parameters currently recognised by built-in signature algorithms are as 435follows. 436 437=over 4 438 439=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string> 440 441Get or sets the name of the digest algorithm used for the input to the 442signature functions. It is required in order to calculate the "algorithm-id". 443 444=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string> 445 446Sets the name of the property query associated with the "digest" algorithm. 447NULL is used if this optional value is not set. 448 449=back 450 451Note that when implementing a signature algorithm that gathers a full message, 452like RSA-SHA256, the "digest" and "properties" parameters should not be used. 453For such implementations, it's acceptable to simply ignore them if they happen 454to be passed in a call to OSSL_FUNC_signature_set_ctx_params(). For such 455implementations, however, it is not acceptable to have them in the B<OSSL_PARAM> 456array that's returned by OSSL_FUNC_signature_settable_ctx_params(). 457 458=over 4 459 460=item "signature" (B<OSSL_SIGNATURE_PARAM_SIGNATURE>) <octet string> 461 462Sets the signature to verify, specifically when 463OSSL_FUNC_signature_verify_message_final() is used. 464 465=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer> 466 467Gets or sets the output size of the digest algorithm used for the input to the 468signature functions. 469The length of the "digest-size" parameter should not exceed that of a B<size_t>. 470 471=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string> 472 473Gets the DER encoded AlgorithmIdentifier that corresponds to the combination of 474signature algorithm and digest algorithm for the signature operation. 475 476=item "nonce-type" (B<OSSL_SIGNATURE_PARAM_NONCE_TYPE>) <unsigned integer> 477 478Set this to 1 to use deterministic digital signature generation with 479ECDSA or DSA, as defined in RFC 6979 (see Section 3.2 "Generation of 480k"). In this case, the "digest" parameter must be explicitly set 481(otherwise, deterministic nonce generation will fail). Before using 482deterministic digital signature generation, please read RFC 6979 483Section 4 "Security Considerations". The default value for 484"nonce-type" is 0 and results in a random value being used for the 485nonce B<k> as defined in FIPS 186-4 Section 6.3 "Secret Number 486Generation". 487 488=item "kat" (B<OSSL_SIGNATURE_PARAM_KAT>) <unsigned integer> 489 490Sets a flag to modify the sign operation to return an error if the initial 491calculated signature is invalid. 492In the normal mode of operation - new random values are chosen until the 493signature operation succeeds. 494By default it retries until a signature is calculated. 495Setting the value to 0 causes the sign operation to retry, 496otherwise the sign operation is only tried once and returns whether or not it 497was successful. 498Known answer tests can be performed if the random generator is overridden to 499supply known values that either pass or fail. 500 501=back 502 503The following parameters are used by the OpenSSL FIPS provider: 504 505=over 4 506 507=item "fips-indicator" (B<OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 508 509A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 510This may be used after calling either the sign or verify final functions. It may 511return 0 if either the "digest-check", "key-check", or "sign-check" are set to 0. 512 513=item "verify-message" (B<OSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE> <integer> 514 515A getter that returns 1 if a signature verification operation acted on 516a raw message, or 0 if it verified a predigested message. A value of 0 517indicates likely non-approved usage of the FIPS provider. This flag is 518set when any signature verification initialisation function is called. 519It is also set to 1 when any signing operation is performed to signify 520compliance. See FIPS 140-3 IG 2.4.B for further information. 521 522=item "key-check" (B<OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK>) <integer> 523 524If required this parameter should be set early via an init function 525(e.g. OSSL_FUNC_signature_sign_init() or OSSL_FUNC_signature_verify_init()). 526The default value of 1 causes an error during the init if the key is not FIPS 527approved (e.g. The key has a security strength of less than 112 bits). 528Setting this to 0 will ignore the error and set the approved "indicator" to 0. 529This option breaks FIPS compliance if it causes the approved "fips-indicator" 530to return 0. 531 532=item "digest-check" (B<OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK>) <integer> 533 534If required this parameter should be set before the signature digest is set. 535The default value of 1 causes an error when the digest is set if the digest is 536not FIPS approved (e.g. SHA1 is used for signing). Setting this to 0 will ignore 537the error and set the approved "fips-indicator" to 0. 538This option breaks FIPS compliance if it causes the approved "fips-indicator" 539to return 0. 540 541=item "sign-check" (B<OSSL_SIGNATURE_PARAM_FIPS_SIGN_CHECK>) <integer> 542 543If required this parameter should be set early via an init function. 544The default value of 1 causes an error when a signing algorithm is used. (This 545is triggered by deprecated signing algorithms). 546Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. 547This option breaks FIPS compliance if it causes the approved "fips-indicator" to 548return 0. 549 550=item "sign-x931-pad-check" (B<OSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK>) <integer> 551 552If required this parameter should be set before the padding mode is set. 553The default value of 1 causes an error if the padding mode is set to X9.31 padding 554for a RSA signing operation. Setting this to 0 will ignore the error and set the 555approved "fips-indicator" to 0. 556This option breaks FIPS compliance if it causes the approved "fips-indicator" 557to return 0. 558 559=back 560 561OSSL_FUNC_signature_gettable_ctx_params() and OSSL_FUNC_signature_settable_ctx_params() get a 562constant L<OSSL_PARAM(3)> array that describes the gettable and settable parameters, 563i.e. parameters that can be used with OSSL_FUNC_signature_get_ctx_params() and 564OSSL_FUNC_signature_set_ctx_params() respectively. 565 566=head2 MD parameters 567 568See L<OSSL_PARAM(3)> for further details on the parameters structure used by 569the OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params() 570functions. 571 572OSSL_FUNC_signature_get_md_ctx_params() gets digest parameters associated with the 573given provider side digest signature context I<ctx> and stores them in I<params>. 574Passing NULL for I<params> should return true. 575 576OSSL_FUNC_signature_set_ms_ctx_params() sets the digest parameters associated with the 577given provider side digest signature context I<ctx> to I<params>. 578Any parameter settings are additional to any that were previously set. 579Passing NULL for I<params> should return true. 580 581Parameters currently recognised by built-in signature algorithms are the same 582as those for built-in digest algorithms. See 583L<provider-digest(7)/Digest Parameters> for further information. 584 585OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params() 586get a constant L<OSSL_PARAM(3)> array that describes the gettable and settable 587digest parameters, i.e. parameters that can be used with 588OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params() 589respectively. 590 591=head1 RETURN VALUES 592 593OSSL_FUNC_signature_newctx() and OSSL_FUNC_signature_dupctx() should return the newly created 594provider side signature context, or NULL on failure. 595 596OSSL_FUNC_signature_gettable_ctx_params(), OSSL_FUNC_signature_settable_ctx_params(), 597OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params(), 598return the gettable or settable parameters in a constant L<OSSL_PARAM(3)> array. 599 600All other functions should return 1 for success or 0 on error. 601 602=head1 SEE ALSO 603 604L<provider(7)> 605 606=head1 HISTORY 607 608The provider SIGNATURE interface was introduced in OpenSSL 3.0. 609The Signature Parameters "fips-indicator", "key-check" and "digest-check" 610were added in OpenSSL 3.4. 611 612=head1 COPYRIGHT 613 614Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 615 616Licensed under the Apache License 2.0 (the "License"). You may not use 617this file except in compliance with the License. You can obtain a copy 618in the file LICENSE in the source distribution or at 619L<https://www.openssl.org/source/license.html>. 620 621=cut 622
