doc/man7/provider.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 provider - OpenSSL operation implementation providers
   6
   7 =head1 SYNOPSIS
   8
   9 =for openssl generic
  10
  11 #include <openssl/provider.h>
  12
  13 =head1 DESCRIPTION
  14
  15 =head2 General
  16
  17 A I<provider>, in OpenSSL terms, is a unit of code that provides one
  18 or more implementations for various operations for diverse algorithms
  19 that one might want to perform.
  20
  21 An I<operation> is something one wants to do, such as encryption and
  22 decryption, key derivation, MAC calculation, signing and verification,
  23 etc.
  24
  25 An I<algorithm> is a named method to perform an operation.
  26 Very often, the algorithms revolve around cryptographic operations,
  27 but may also revolve around other types of operation, such as managing
  28 certain types of objects.
  29
  30 =head2 Provider
  31
  32 I<NOTE: This section is mostly interesting for provider authors.>
  33
  34 A I<provider> offers an initialization function, as a set of base
  35 functions in the form of an B<OSSL_DISPATCH> array, and by extension,
  36 a set of B<OSSL_ALGORITHM>s (see L<openssl-core.h(7)>).
  37 It may be a dynamically loadable module, or may be built-in, in
  38 OpenSSL libraries or in the application.
  39 If it's a dynamically loadable module, the initialization function
  40 must be named C<OSSL_provider_init> and must be exported.
  41 If it's built-in, the initialization function may have any name.
  42
  43 The initialization function must have the following signature:
  44
  45  int NAME(const OSSL_PROVIDER *provider,
  46           const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
  47           void **provctx);
  48
  49 I<provider> is the OpenSSL library object for the provider, and works
  50 as a handle for everything the OpenSSL libraries need to know about
  51 the provider.
  52 For the provider itself, it may hold some interesting information,
  53 and is also passed to some of the functions given in the dispatch
  54 array I<in>.
  55
  56 I<in> is a dispatch array of base functions offered by the OpenSSL
  57 libraries, and the available functions are further described in
  58 L<provider-base(7)>.
  59
  60 I<*out> must be assigned a dispatch array of base functions that the
  61 provider offers to the OpenSSL libraries.
  62 The functions that may be offered are further described in
  63 L<provider-base(7)>, and they are the central means of communication
  64 between the OpenSSL libraries and the provider.
  65
  66 I<*provctx> should be assigned a provider specific context to allow
  67 the provider multiple simultaneous uses.
  68 This pointer will be passed to various operation functions offered by
  69 the provider.
  70
  71 One of the functions the provider offers to the OpenSSL libraries is
  72 the central mechanism for the OpenSSL libraries to get access to
  73 operation implementations for diverse algorithms.
  74 Its referred to with the number B<OSSL_FUNC_PROVIDER_QUERY_OPERATION>
  75 and has the following signature:
  76
  77  const OSSL_ALGORITHM *provider_query_operation(void *provctx,
  78                                                 int operation_id,
  79                                                 const int *no_store);
  80
  81 I<provctx> is the provider specific context that was passed back by
  82 the initialization function.
  83
  84 I<operation_id> is an operation identity (see L</Operations> below).
  85
  86 I<no_store> is a flag back to the OpenSSL libraries which, when
  87 nonzero, signifies that the OpenSSL libraries will not store a
  88 reference to the returned data in their internal store of
  89 implementations.
  90
  91 The returned B<OSSL_ALGORITHM> is the foundation of any OpenSSL
  92 library API that uses providers for their implementation, most
  93 commonly in the I<fetching> type of functions
  94 (see L</Fetching algorithms> below).
  95
  96 =head2 Operations
  97
  98 I<NOTE: This section is mostly interesting for provider authors.>
  99
 100 Operations are referred to with numbers, via macros with names
 101 starting with C<OSSL_OP_>.
 102
 103 With each operation comes a set of defined function types that a
 104 provider may or may not offer, depending on its needs.
 105
 106 Currently available operations are:
 107
 108 =over 4
 109
 110 =item Digests
 111
 112 In the OpenSSL libraries, the corresponding method object is
 113 B<EVP_MD>.
 114 The number for this operation is B<OSSL_OP_DIGEST>.
 115 The functions the provider can offer are described in
 116 L<provider-digest(7)>
 117
 118 =item Symmetric ciphers
 119
 120 In the OpenSSL libraries, the corresponding method object is
 121 B<EVP_CIPHER>.
 122 The number for this operation is B<OSSL_OP_CIPHER>.
 123 The functions the provider can offer are described in
 124 L<provider-cipher(7)>
 125
 126 =item Message Authentication Code (MAC)
 127
 128 In the OpenSSL libraries, the corresponding method object is
 129 B<EVP_MAC>.
 130 The number for this operation is B<OSSL_OP_MAC>.
 131 The functions the provider can offer are described in
 132 L<provider-mac(7)>
 133
 134 =item Key Derivation Function (KDF)
 135
 136 In the OpenSSL libraries, the corresponding method object is
 137 B<EVP_KDF>.
 138 The number for this operation is B<OSSL_OP_KDF>.
 139 The functions the provider can offer are described in
 140 L<provider-kdf(7)>
 141
 142 =item Key Exchange
 143
 144 In the OpenSSL libraries, the corresponding method object is
 145 B<EVP_KEYEXCH>.
 146 The number for this operation is B<OSSL_OP_KEYEXCH>.
 147 The functions the provider can offer are described in
 148 L<provider-keyexch(7)>
 149
 150 =back
 151
 152 =head2 Fetching algorithms
 153
 154 =head3 Explicit fetch
 155
 156 I<NOTE: This section is mostly interesting to OpenSSL users.>
 157
 158 Users of the OpenSSL libraries never query the provider directly for
 159 its diverse implementations and dispatch tables.
 160 Instead, the diverse OpenSSL APIs often have fetching functions that
 161 do the work, and they return an appropriate method object back to the
 162 user.
 163 These functions usually have the name C<APINAME_fetch>, where
 164 C<APINAME> is the name of the API, for example L<EVP_MD_fetch(3)>.
 165
 166 These fetching functions follow a fairly common pattern, where three
 167 arguments are passed:
 168
 169 =over 4
 170
 171 =item The library context
 172
 173 See L<OPENSSL_CTX(3)> for a more detailed description.
 174 This may be NULL to signify the default (global) library context, or a
 175 context created by the user.
 176 Only providers loaded in this library context (see
 177 L<OSSL_PROVIDER_load(3)>) will be considered by the fetching
 178 function.
 179
 180 =item An identifier
 181
 182 This is most commonly an algorithm name (this is the case for all EVP
 183 methods), but may also be called something else.
 184
 185 =for comment For example, an OSSL_STORE implementation would use the
 186 URI scheme as an identifier.
 187
 188 =item A property query string
 189
 190 See L<property(7)> for a more detailed description.
 191 This is used to select more exactly which providers will get to offer
 192 an implementation.
 193
 194 =back
 195
 196 The method object that is fetched can then be used with diverse other
 197 functions that use them, for example L<EVP_DigestInit_ex(3)>.
 198
 199 =head3 Implicit fetch
 200
 201 I<NOTE: This section is mostly interesting to OpenSSL users.>
 202
 203 OpenSSL has a number of functions that return a method object with no
 204 associated implementation, such as L<EVP_sha256(3)>,
 205 L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>, which are present for
 206 compatibility with OpenSSL before version 3.0.
 207
 208 When they are used with functions like L<EVP_DigestInit_ex(3)> or
 209 L<EVP_CipherInit_ex(3)>, the actual implementation to be used is
 210 fetched implicitly using default search criteria.
 211
 212 Implicit fetching can also occur with functions such as
 213 L<EVP_PKEY_CTX_derive_init_ex(3)> where a NULL algorithm parameter is
 214 supplied.
 215 In this case an algorithm implementation is implicitly fetched using
 216 default search criteria and an algorithm name that is consistent with
 217 the type of EVP_PKEY being used.
 218
 219 =head1 OPENSSL PROVIDERS
 220
 221 OpenSSL comes with a set of providers.
 222 All the algorithm names mentioned can be used as an algorithm
 223 identifier to the appropriate fetching function.
 224
 225 =head2 Default provider
 226
 227 The default provider is built in as part of the F<libcrypto> library.
 228 Should it be needed (if other providers are loaded and offer
 229 implementations of the same algorithms), the property "default=yes"
 230 can be used as a search criterion for these implementations.
 231
 232 It currently offers the following named algorithms:
 233
 234 =over 4
 235
 236 =item Digests
 237
 238 SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
 239 SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3,
 240 BLAKE2b512, BLAKE2s256, KMAC128, KMAC256, MD5, MD5-SHA1
 241
 242 =item Symmetric ciphers
 243
 244 AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
 245 AES-128-CBC, AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB,
 246 AES-192-CFB, AES-128-CFB, AES-256-CFB1, AES-192-CFB1, AES-128-CFB1,
 247 AES-256-CFB8, AES-192-CFB8, AES-128-CFB8, AES-256-CTR, AES-192-CTR,
 248 AES-128-CTR, id-aes256-GCM, id-aes192-GCM, id-aes128-GCM
 249
 250 =item Key Exchange
 251
 252 dhKeyAgreement
 253
 254 =back
 255
 256 =head2 FIPS provider
 257
 258 The FIPS provider is a dynamically loadable module, and must therefore
 259 be loaded explicitly, either in code or through OpenSSL configuration
 260 (see L<config(5)>).
 261 Should it be needed (if other providers are loaded and offer
 262 implementations of the same algorithms), the property "fips=yes" can
 263 be used as a search criterion for these implementations.
 264
 265 It currently offers the following FIPS approved named algorithms:
 266
 267 =over 4
 268
 269 =item Digests
 270
 271 SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
 272 SHA3-224, SHA3-256, SHA3-384, SHA3-512, KMAC128, KMAC256
 273
 274 =item Symmetric ciphers
 275
 276 AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
 277 AES-128-CBC, AES-256-CTR, AES-192-CTR, AES-128-CTR
 278
 279 =back
 280
 281 =head2 Legacy provider
 282
 283 The legacy provider is a dynamically loadable module, and must therefore
 284 be loaded explicitly, either in code or through OpenSSL configuration
 285 (see L<config(5)>).
 286 Should it be needed (if other providers are loaded and offer
 287 implementations of the same algorithms), the property "legacy=yes" can be
 288 used as a search criterion for these implementations.
 289
 290 It currently offers the following named algorithms:
 291
 292 =over 4
 293
 294 =item Digest algorithms:
 295
 296 RIPEMD160, MD2, MD4, MDC2, whirlpool.
 297
 298 =back
 299
 300 =head1 EXAMPLES
 301
 302 =head2 Fetching
 303
 304 Fetch any available implementation of SHA256 in the default context:
 305
 306  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
 307  ...
 308  EVP_MD_meth_free(md);
 309
 310 Fetch any available implementation of AES-128-CBC in the default context:
 311
 312  EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
 313  ...
 314  EVP_CIPHER_meth_free(cipher);
 315
 316 Fetch an implementation of SHA256 from the default provider in the default
 317 context:
 318
 319  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
 320  ...
 321  EVP_MD_meth_free(md);
 322
 323 Fetch an implementation of SHA256 that is not from the default provider in the
 324 default context:
 325
 326  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
 327  ...
 328  EVP_MD_meth_free(md);
 329
 330 Fetch an implementation of SHA256 from the default provider in the specified
 331 context:
 332
 333  EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
 334  ...
 335  EVP_MD_meth_free(md);
 336
 337 Load the legacy provider into the default context and then fetch an
 338 implementation of whirlpool from it:
 339
 340  /* This only needs to be done once - usually at application start up */
 341  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 342
 343  EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
 344  ...
 345  EVP_MD_meth_free(md);
 346
 347 Note that in the above example the property string "legacy=yes" is optional
 348 since, assuming no other providers have been loaded, the only implementation of
 349 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
 350 default provider should be explicitly loaded if it is required in addition to
 351 other providers:
 352
 353  /* This only needs to be done once - usually at application start up */
 354  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 355  OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
 356
 357  EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
 358  EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
 359  ...
 360  EVP_MD_meth_free(md_whirlpool);
 361  EVP_MD_meth_free(md_sha256);
 362
 363
 364 =head1 SEE ALSO
 365
 366 L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>,
 367 L<EVP_PKEY_derive_init_ex(3)>,
 368 L<OPENSSL_CTX(3)>,
 369 L<EVP_set_default_properties(3)>,
 370 L<EVP_MD_fetch(3)>,
 371 L<EVP_CIPHER_fetch(3)>,
 372 L<EVP_KEYMGMT_fetch(3)>,
 373 L<openssl-core.h(7)>,
 374 L<provider-base(7)>,
 375 L<provider-digest(7)>,
 376 L<provider-cipher(7)>,
 377 L<provider-keyexch(7)>
 378
 379 =head1 HISTORY
 380
 381 The concept of providers and everything surrounding them was
 382 introduced in OpenSSL 3.0.
 383
 384 =head1 COPYRIGHT
 385
 386 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 387
 388 Licensed under the Apache License 2.0 (the "License").  You may not use
 389 this file except in compliance with the License.  You can obtain a copy
 390 in the file LICENSE in the source distribution or at
 391 L<https://www.openssl.org/source/license.html>.
 392
 393 =cut