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