doc/man7/provider.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 provider - OpenSSL operation implementation providers
   6
   7 =head1 SYNOPSIS
   8
   9 =for comment 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 non-zero, 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 =begin comment NOT AVAILABLE YET
 127
 128 =item Message Authentication Code (MAC)
 129
 130 In the OpenSSL libraries, the corresponding method object is
 131 B<EVP_MAC>.
 132 The number for this operation is B<OSSL_OP_MAC>.
 133 The functions the provider can offer are described in
 134 L<provider-mac(7)>
 135
 136 =end comment
 137
 138 =begin comment NOT AVAILABLE YET
 139
 140 =item Key Derivation Function (KDF)
 141
 142 In the OpenSSL libraries, the corresponding method object is
 143 B<EVP_KDF>.
 144 The number for this operation is B<OSSL_OP_KDF>.
 145 The functions the provider can offer are described in
 146 L<provider-kdf(7)>
 147
 148 =end comment
 149
 150 =item Key Exchange
 151
 152 In the OpenSSL libraries, the corresponding method object is
 153 B<EVP_KEYEXCh>.
 154 The number for this operation is B<OSSL_OP_KEYEXCH>.
 155 The functions the provider can offer are described in
 156 L<provider-keyexch(7)>
 157
 158 =back
 159
 160 =head2 Fetching algorithms
 161
 162 =head3 Explicit fetch
 163
 164 I<NOTE: This section is mostly interesting to OpenSSL users.>
 165
 166 Users of the OpenSSL libraries never query the provider directly for
 167 its diverse implementations and dispatch tables.
 168 Instead, the diverse OpenSSL APIs often have fetching functions that
 169 do the work, and they return an appropriate method object back to the
 170 user.
 171 These functions usually have the name C<APINAME_fetch>, where
 172 C<APINAME> is the name of the API, for example L<EVP_MD_fetch(3)>.
 173
 174 These fetching functions follow a fairly common pattern, where three
 175 arguments are passed:
 176
 177 =over 4
 178
 179 =item The library context
 180
 181 See L<OPENSSL_CTX(3)> for a more detailed description.
 182 This may be NULL to signify the default (global) library context, or a
 183 context created by the user.
 184 Only providers loaded in this library context (see
 185 L<OSSL_PROVIDER_load(3)>) will be considered by the fetching
 186 function.
 187
 188 =item An identifier
 189
 190 This is most commonly an algorithm name (this is the case for all EVP
 191 methods), but may also be called something else.
 192
 193 =for comment For example, an OSSL_STORE implementation would use the
 194 URI scheme as an identifier.
 195
 196 =item A property query string
 197
 198 See L<property(7)> for a more detailed description.
 199 This is used to select more exactly which providers will get to offer
 200 an implementation.
 201
 202 =back
 203
 204 The method object that is fetched can then be used with diverse other
 205 functions that use them, for example L<EVP_DigestInit_ex(3)>.
 206
 207 =head2 Implicit fetch
 208
 209 I<NOTE: This section is mostly interesting to OpenSSL users.>
 210
 211 OpenSSL has a number of functions that return a method object with no
 212 associated implementation, such as L<EVP_sha256(3)>,
 213 L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>, which are present for
 214 compatibility with OpenSSL before version 3.0.
 215
 216 When they are used with functions like L<EVP_DigestInit_ex(3)> or
 217 L<EVP_CipherInit_ex(3)>, the actual implementation to be used is
 218 fetched implicitly using default search criteria.
 219
 220 Implicit fetching can also occur with functions such as
 221 L<EVP_PKEY_CTX_derive_init_ex(3)> where a NULL algorithm parameter is
 222 supplied.
 223 In this case an algorithm implementation is implicitly fetched using
 224 default search criteria and an algorithm name that is consistent with
 225 the type of EVP_PKEY being used.
 226
 227 =head1 OPENSSL PROVIDERS
 228
 229 OpenSSL comes with a set of providers.
 230 All the algorithm names mentioned can be used as an algorithm
 231 identifier to the appropriate fetching function.
 232
 233 =head2 Default provider
 234
 235 The default provider is built in as part of the F<libcrypto> library.
 236 Should it be needed (if other providers are loaded and offer
 237 implementations of the same algorithms), the property "default=yes"
 238 can be used as a search criterion for these implementations.
 239
 240 It currently offers the following named algorithms:
 241
 242 =over 4
 243
 244 =item Digests
 245
 246 SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
 247 SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3,
 248 BLAKE2b512, BLAKE2s256, KMAC128, KMAC256, MD5, MD5-SHA1
 249
 250 =item Symmetric ciphers
 251
 252 AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
 253 AES-128-CBC, AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB,
 254 AES-192-CFB, AES-128-CFB, AES-256-CFB1, AES-192-CFB1, AES-128-CFB1,
 255 AES-256-CFB8, AES-192-CFB8, AES-128-CFB8, AES-256-CTR, AES-192-CTR,
 256 AES-128-CTR, id-aes256-GCM, id-aes192-GCM, id-aes128-GCM
 257
 258 =item Key Exchange
 259
 260 dhKeyAgreement
 261
 262 =back
 263
 264 =head2 FIPS provider
 265
 266 The FIPS provider is a dynamically loadable module, and must therefore
 267 be loaded explicitly, either in code or through OpenSSL configuration
 268 (see L<config(5)>).
 269 Should it be needed (if other providers are loaded and offer
 270 implementations of the same algorithms), the property "fips=yes" can
 271 be used as a search criterion for these implementations.
 272
 273 It currently offers the following FIPS approved named algorithms:
 274
 275 =over 4
 276
 277 =item Digests
 278
 279 SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
 280 SHA3-224, SHA3-256, SHA3-384, SHA3-512, KMAC128, KMAC256
 281
 282 =item Symmetric ciphers
 283
 284 AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
 285 AES-128-CBC, AES-256-CTR, AES-192-CTR, AES-128-CTR
 286
 287 =back
 288
 289 =head2 Legacy provider
 290
 291 The legacy provider is a dynamically loadable module, and must therefore
 292 be loaded explicitly, either in code or through OpenSSL configuration
 293 (see L<config(5)>).
 294 Should it be needed (if other providers are loaded and offer
 295 implementations of the same algorithms), the property "legacy=yes" can be
 296 used as a search criterion for these implementations.
 297
 298 It currently offers the following named algorithms:
 299
 300 =over 4
 301
 302 =item Digest algorithms:
 303
 304 RIPEMD160, MD2, MD4, MDC2, whirlpool.
 305
 306 =back
 307
 308 =head1 EXAMPLES
 309
 310 =head2 Fetching
 311
 312 Fetch any available implementation of SHA256 in the default context:
 313
 314  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
 315  ...
 316  EVP_MD_meth_free(md);
 317
 318 Fetch any available implementation of AES-128-CBC in the default context:
 319
 320  EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
 321  ...
 322  EVP_CIPHER_meth_free(cipher);
 323
 324 Fetch an implementation of SHA256 from the default provider in the default
 325 context:
 326
 327  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
 328  ...
 329  EVP_MD_meth_free(md);
 330
 331 Fetch an implementation of SHA256 that is not from the default provider in the
 332 default context:
 333
 334  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
 335  ...
 336  EVP_MD_meth_free(md);
 337
 338 Fetch an implementation of SHA256 from the default provider in the specified
 339 context:
 340
 341  EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
 342  ...
 343  EVP_MD_meth_free(md);
 344
 345 Load the legacy provider into the default context and then fetch an
 346 implementation of whirlpool from it:
 347
 348  /* This only needs to be done once - usually at application start up */
 349  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 350
 351  EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
 352  ...
 353  EVP_MD_meth_free(md);
 354
 355 Note that in the above example the property string "legacy=yes" is optional
 356 since, assuming no other providers have been loaded, the only implementation of
 357 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
 358 default provider should be explicitly loaded if it is required in addition to
 359 other providers:
 360
 361  /* This only needs to be done once - usually at application start up */
 362  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 363  OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
 364
 365  EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
 366  EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
 367  ...
 368  EVP_MD_meth_free(md_whirlpool);
 369  EVP_MD_meth_free(md_sha256);
 370
 371
 372 =head1 SEE ALSO
 373
 374 L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>,
 375 L<EVP_PKEY_derive_init_ex(3)>,
 376 L<OPENSSL_CTX(3)>,
 377 L<EVP_set_default_properties(3)>,
 378 L<EVP_MD_fetch(3)>,
 379 L<EVP_CIPHER_fetch(3)>,
 380 L<EVP_KEYMGMT_fetch(3)>,
 381 L<openssl-core.h(7)>,
 382 L<provider-base(7)>,
 383 L<provider-digest(7)>,
 384 L<provider-cipher(7)>,
 385 L<provider-keyexch(7)>
 386
 387 =head1 HISTORY
 388
 389 The concept of providers and everything surrounding them was
 390 introduced in OpenSSL 3.0.
 391
 392 =head1 COPYRIGHT
 393
 394 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 395
 396 Licensed under the Apache License 2.0 (the "License").  You may not use
 397 this file except in compliance with the License.  You can obtain a copy
 398 in the file LICENSE in the source distribution or at
 399 L<https://www.openssl.org/source/license.html>.
 400
 401 =cut