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