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 const char *props, 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 const char *props, 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 B<OSSL_DISPATCH> arrays via 97B<OSSL_ALGORITHM> 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 B<OSSL_DISPATCH> 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 111B<OSSL_DISPATCH> 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_init 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. There may 270also be properties to be used in fetching the digest in the I<props> parameter, 271although this may be ignored by providers. 272 273OSSL_FUNC_signature_digest_sign_update() provides data to be signed in the I<data> 274parameter which should be of length I<datalen>. A previously initialised 275signature context is passed in the I<ctx> parameter. This function may be called 276multiple times to cumulatively add data to be signed. 277 278OSSL_FUNC_signature_digest_sign_final() finalises a signature operation previously 279started through OSSL_FUNC_signature_digest_sign_init() and 280OSSL_FUNC_signature_digest_sign_update() calls. Once finalised no more data will be 281added through OSSL_FUNC_signature_digest_sign_update(). A previously initialised 282signature context is passed in the I<ctx> parameter. Unless I<sig> is NULL, the 283signature should be written to the location pointed to by the I<sig> parameter 284and it should not exceed I<sigsize> bytes in length. The length of the signature 285should be written to I<*siglen>. If I<sig> is NULL then the maximum length of 286the signature should be written to I<*siglen>. 287 288OSSL_FUNC_signature_digest_sign() implements a "one shot" digest sign operation 289previously started through OSSL_FUNC_signature_digeset_sign_init(). A previously 290initialised signature context is passed in the I<ctx> parameter. The data to be 291signed is in I<tbs> which should be I<tbslen> bytes long. Unless I<sig> is NULL, 292the signature should be written to the location pointed to by the I<sig> 293parameter and it should not exceed I<sigsize> bytes in length. The length of the 294signature should be written to I<*siglen>. If I<sig> is NULL then the maximum 295length of the signature should be written to I<*siglen>. 296 297=head2 Digest Verify Functions 298 299OSSL_FUNC_signature_digeset_verify_init() initialises a context for verifying given a 300provider side verification context in the I<ctx> parameter, and a pointer to a 301provider key object in the I<provkey> parameter. 302The I<params>, if not NULL, should be set on the context in a manner similar to 303OSSL_FUNC_signature_set_ctx_params() and 304OSSL_FUNC_signature_set_ctx_md_params(). 305The key object should have been 306previously generated, loaded or imported into the provider using the 307key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. 308The name of the digest to be used will be in the I<mdname> parameter. There may 309also be properties to be used in fetching the digest in the I<props> parameter, 310although this may be ignored by providers. 311 312OSSL_FUNC_signature_digest_verify_update() provides data to be verified in the I<data> 313parameter which should be of length I<datalen>. A previously initialised 314verification context is passed in the I<ctx> parameter. This function may be 315called multiple times to cumulatively add data to be verified. 316 317OSSL_FUNC_signature_digest_verify_final() finalises a verification operation previously 318started through OSSL_FUNC_signature_digest_verify_init() and 319OSSL_FUNC_signature_digest_verify_update() calls. Once finalised no more data will be 320added through OSSL_FUNC_signature_digest_verify_update(). A previously initialised 321verification context is passed in the I<ctx> parameter. The signature to be 322verified is in I<sig> which is I<siglen> bytes long. 323 324OSSL_FUNC_signature_digest_verify() implements a "one shot" digest verify operation 325previously started through OSSL_FUNC_signature_digeset_verify_init(). A previously 326initialised verification context is passed in the I<ctx> parameter. The data to be 327verified is in I<tbs> which should be I<tbslen> bytes long. The signature to be 328verified is in I<sig> which is I<siglen> bytes long. 329 330=head2 Signature parameters 331 332See L<OSSL_PARAM(3)> for further details on the parameters structure used by 333the OSSL_FUNC_signature_get_ctx_params() and OSSL_FUNC_signature_set_ctx_params() functions. 334 335OSSL_FUNC_signature_get_ctx_params() gets signature parameters associated with the 336given provider side signature context I<ctx> and stored them in I<params>. 337Passing NULL for I<params> should return true. 338 339OSSL_FUNC_signature_set_ctx_params() sets the signature parameters associated with the 340given provider side signature context I<ctx> to I<params>. 341Any parameter settings are additional to any that were previously set. 342Passing NULL for I<params> should return true. 343 344Common parameters currently recognised by built-in signature algorithms are as 345follows. 346 347=over 4 348 349=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string> 350 351Get or sets the name of the digest algorithm used for the input to the 352signature functions. It is required in order to calculate the "algorithm-id". 353 354=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string> 355 356Sets the name of the property query associated with the "digest" algorithm. 357NULL is used if this optional value is not set. 358 359=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer> 360 361Gets or sets the output size of the digest algorithm used for the input to the 362signature functions. 363The length of the "digest-size" parameter should not exceed that of a B<size_t>. 364 365=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string> 366 367Gets the DER encoded AlgorithmIdentifier that corresponds to the combination of 368signature algorithm and digest algorithm for the signature operation. 369 370=item "kat" (B<OSSL_SIGNATURE_PARAM_KAT>) <unsigned integer> 371 372Sets a flag to modify the sign operation to return an error if the initial 373calculated signature is invalid. 374In the normal mode of operation - new random values are chosen until the 375signature operation succeeds. 376By default it retries until a signature is calculated. 377Setting the value to 0 causes the sign operation to retry, 378otherwise the sign operation is only tried once and returns whether or not it 379was successful. 380Known answer tests can be performed if the random generator is overridden to 381supply known values that either pass or fail. 382 383=back 384 385OSSL_FUNC_signature_gettable_ctx_params() and OSSL_FUNC_signature_settable_ctx_params() get a 386constant B<OSSL_PARAM> array that describes the gettable and settable parameters, 387i.e. parameters that can be used with OSSL_FUNC_signature_get_ctx_params() and 388OSSL_FUNC_signature_set_ctx_params() respectively. 389See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. 390 391=head2 MD parameters 392 393See L<OSSL_PARAM(3)> for further details on the parameters structure used by 394the OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params() 395functions. 396 397OSSL_FUNC_signature_get_md_ctx_params() gets digest parameters associated with the 398given provider side digest signature context I<ctx> and stores them in I<params>. 399Passing NULL for I<params> should return true. 400 401OSSL_FUNC_signature_set_ms_ctx_params() sets the digest parameters associated with the 402given provider side digest signature context I<ctx> to I<params>. 403Any parameter settings are additional to any that were previously set. 404Passing NULL for I<params> should return true. 405 406Parameters currently recognised by built-in signature algorithms are the same 407as those for built-in digest algorithms. See 408L<provider-digest(7)/Digest Parameters> for further information. 409 410OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params() 411get a constant B<OSSL_PARAM> array that describes the gettable and settable 412digest parameters, i.e. parameters that can be used with 413OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params() 414respectively. See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter 415descriptor. 416 417=head1 RETURN VALUES 418 419OSSL_FUNC_signature_newctx() and OSSL_FUNC_signature_dupctx() should return the newly created 420provider side signature, or NULL on failure. 421 422OSSL_FUNC_signature_gettable_ctx_params(), OSSL_FUNC_signature_settable_ctx_params(), 423OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params(), 424return the gettable or settable parameters in a constant B<OSSL_PARAM> array. 425 426All other functions should return 1 for success or 0 on error. 427 428=head1 SEE ALSO 429 430L<provider(7)> 431 432=head1 HISTORY 433 434The provider SIGNATURE interface was introduced in OpenSSL 3.0. 435 436=head1 COPYRIGHT 437 438Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 439 440Licensed under the Apache License 2.0 (the "License"). You may not use 441this file except in compliance with the License. You can obtain a copy 442in the file LICENSE in the source distribution or at 443L<https://www.openssl.org/source/license.html>. 444 445=cut 446