doc/man7/provider-signature.pod

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