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_numbers.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_numbers.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 cummulatively 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 cummulatively 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 Parameters currently recognised by built-in signature algorithms are as
 318 follows.
 319 Not all parameters are relevant to, or are understood by all signature
 320 algorithms:
 321
 322 =over 4
 323
 324 =item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
 325
 326 Get or sets the name of the digest algorithm used for the input to the signature
 327 functions.
 328
 329 =item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
 330
 331 Gets or sets the output size of the digest algorithm used for the input to the
 332 signature functions.
 333 The length of the "digest-size" parameter should not exceed that of a B<size_t>.
 334
 335
 336 =back
 337
 338 OP_signature_gettable_ctx_params() and OP_signature_settable_ctx_params() get a
 339 constant B<OSSL_PARAM> array that describes the gettable and settable parameters,
 340 i.e. parameters that can be used with OP_signature_get_ctx_params() and
 341 OP_signature_set_ctx_params() respectively.
 342 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
 343
 344 =head2 MD Parameters
 345
 346 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
 347 the OP_signature_get_md_ctx_params() and OP_signature_set_md_ctx_params()
 348 functions.
 349
 350 OP_signature_get_md_ctx_params() gets digest parameters associated with the
 351 given provider side digest signature context I<ctx> and stores them in I<params>.
 352 OP_signature_set_ms_ctx_params() sets the digest parameters associated with the
 353 given provider side digest signature context I<ctx> to I<params>.
 354 Any parameter settings are additional to any that were previously set.
 355
 356 Parameters currently recognised by built-in signature algorithms are the same
 357 as those for built-in digest algorithms. See
 358 L<provider-digest(7)/Digest Parameters> for further information.
 359
 360 OP_signature_gettable_md_ctx_params() and OP_signature_settable_md_ctx_params()
 361 get a constant B<OSSL_PARAM> array that describes the gettable and settable
 362 digest parameters, i.e. parameters that can be used with
 363 OP_signature_get_md_ctx_params() and OP_signature_set_md_ctx_params()
 364 respectively. See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter
 365 descriptor.
 366
 367 =head1 RETURN VALUES
 368
 369 OP_signature_newctx() and OP_signature_dupctx() should return the newly created
 370 provider side signature, or NULL on failure.
 371
 372 OP_signature_gettable_ctx_params(), OP_signature_settable_ctx_params(),
 373 OP_signature_gettable_md_ctx_params() and OP_signature_settable_md_ctx_params(),
 374 return the gettable or settable parameters in a constant B<OSSL_PARAM> array.
 375
 376 All other functions should return 1 for success or 0 on error.
 377
 378 =head1 SEE ALSO
 379
 380 L<provider(7)>
 381
 382 =head1 HISTORY
 383
 384 The provider SIGNATURE interface was introduced in OpenSSL 3.0.
 385
 386 =head1 COPYRIGHT
 387
 388 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 389
 390 Licensed under the Apache License 2.0 (the "License").  You may not use
 391 this file except in compliance with the License.  You can obtain a copy
 392 in the file LICENSE in the source distribution or at
 393 L<https://www.openssl.org/source/license.html>.
 394
 395 =cut