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_CORE_HANDLE *handle,
  46           const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
  47           void **provctx);
  48
  49 I<handle> 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 is passed to some of the functions given in the
  53 dispatch array I<in>.
  54
  55 I<in> is a dispatch array of base functions offered by the OpenSSL
  56 libraries, and the available functions are further described in
  57 L<provider-base(7)>.
  58
  59 I<*out> must be assigned a dispatch array of base functions that the
  60 provider offers to the OpenSSL libraries.
  61 The functions that may be offered are further described in
  62 L<provider-base(7)>, and they are the central means of communication
  63 between the OpenSSL libraries and the provider.
  64
  65 I<*provctx> should be assigned a provider specific context to allow
  66 the provider multiple simultaneous uses.
  67 This pointer will be passed to various operation functions offered by
  68 the provider.
  69
  70 One of the functions the provider offers to the OpenSSL libraries is
  71 the central mechanism for the OpenSSL libraries to get access to
  72 operation implementations for diverse algorithms.
  73 Its referred to with the number B<OSSL_FUNC_PROVIDER_QUERY_OPERATION>
  74 and has the following signature:
  75
  76  const OSSL_ALGORITHM *provider_query_operation(void *provctx,
  77                                                 int operation_id,
  78                                                 const int *no_store);
  79
  80 I<provctx> is the provider specific context that was passed back by
  81 the initialization function.
  82
  83 I<operation_id> is an operation identity (see L</Operations> below).
  84
  85 I<no_store> is a flag back to the OpenSSL libraries which, when
  86 nonzero, signifies that the OpenSSL libraries will not store a
  87 reference to the returned data in their internal store of
  88 implementations.
  89
  90 The returned B<OSSL_ALGORITHM> is the foundation of any OpenSSL
  91 library API that uses providers for their implementation, most
  92 commonly in the I<fetching> type of functions
  93 (see L</Fetching algorithms> below).
  94
  95 =head2 Operations
  96
  97 I<NOTE: This section is mostly interesting for provider authors.>
  98
  99 Operations are referred to with numbers, via macros with names
 100 starting with C<OSSL_OP_>.
 101
 102 With each operation comes a set of defined function types that a
 103 provider may or may not offer, depending on its needs.
 104
 105 Currently available operations are:
 106
 107 =over 4
 108
 109 =item Digests
 110
 111 In the OpenSSL libraries, the corresponding method object is
 112 B<EVP_MD>.
 113 The number for this operation is B<OSSL_OP_DIGEST>.
 114 The functions the provider can offer are described in
 115 L<provider-digest(7)>
 116
 117 =item Symmetric ciphers
 118
 119 In the OpenSSL libraries, the corresponding method object is
 120 B<EVP_CIPHER>.
 121 The number for this operation is B<OSSL_OP_CIPHER>.
 122 The functions the provider can offer are described in
 123 L<provider-cipher(7)>
 124
 125 =item Message Authentication Code (MAC)
 126
 127 In the OpenSSL libraries, the corresponding method object is
 128 B<EVP_MAC>.
 129 The number for this operation is B<OSSL_OP_MAC>.
 130 The functions the provider can offer are described in
 131 L<provider-mac(7)>
 132
 133 =item Key Derivation Function (KDF)
 134
 135 In the OpenSSL libraries, the corresponding method object is
 136 B<EVP_KDF>.
 137 The number for this operation is B<OSSL_OP_KDF>.
 138 The functions the provider can offer are described in
 139 L<provider-kdf(7)>
 140
 141 =item Key Exchange
 142
 143 In the OpenSSL libraries, the corresponding method object is
 144 B<EVP_KEYEXCH>.
 145 The number for this operation is B<OSSL_OP_KEYEXCH>.
 146 The functions the provider can offer are described in
 147 L<provider-keyexch(7)>
 148
 149 =item Asymmetric Ciphers
 150
 151 In the OpenSSL libraries, the corresponding method object is
 152 B<EVP_ASYM_CIPHER>.
 153 The number for this operation is B<OSSL_OP_ASYM_CIPHER>.
 154 The functions the provider can offer are described in
 155 L<provider-asym_cipher(7)>
 156
 157 =item Asymmetric Key Encapsulation
 158
 159 In the OpenSSL libraries, the corresponding method object is B<EVP_KEM>.
 160 The number for this operation is B<OSSL_OP_KEM>.
 161 The functions the provider can offer are described in L<provider-kem(7)>
 162
 163 =item Encoding
 164
 165 In the OpenSSL libraries, the corresponding method object is
 166 B<OSSL_ENCODER>.
 167 The number for this operation is B<OSSL_OP_ENCODER>.
 168 The functions the provider can offer are described in
 169 L<provider-encoder(7)>
 170
 171 =back
 172
 173 =head2 Fetching algorithms
 174
 175 =head3 Explicit fetch
 176
 177 I<NOTE: This section is mostly interesting to OpenSSL users.>
 178
 179 Users of the OpenSSL libraries never query the provider directly for
 180 its diverse implementations and dispatch tables.
 181 Instead, the diverse OpenSSL APIs often have fetching functions that
 182 do the work, and they return an appropriate method object back to the
 183 user.
 184 These functions usually have the name C<APINAME_fetch>, where
 185 C<APINAME> is the name of the API, for example L<EVP_MD_fetch(3)>.
 186
 187 These fetching functions follow a fairly common pattern, where three
 188 arguments are passed:
 189
 190 =over 4
 191
 192 =item The library context
 193
 194 See L<OPENSSL_CTX(3)> for a more detailed description.
 195 This may be NULL to signify the default (global) library context, or a
 196 context created by the user.
 197 Only providers loaded in this library context (see
 198 L<OSSL_PROVIDER_load(3)>) will be considered by the fetching
 199 function.
 200
 201 =item An identifier
 202
 203 This is most commonly an algorithm name (this is the case for all EVP
 204 methods), but may also be called something else.
 205
 206 =for comment For example, an OSSL_STORE implementation would use the
 207 URI scheme as an identifier.
 208
 209 =item A property query string
 210
 211 See L<property(7)> for a more detailed description.
 212 This is used to select more exactly which providers will get to offer
 213 an implementation.
 214
 215 =back
 216
 217 The method object that is fetched can then be used with diverse other
 218 functions that use them, for example L<EVP_DigestInit_ex(3)>.
 219
 220 =head3 Implicit fetch
 221
 222 I<NOTE: This section is mostly interesting to OpenSSL users.>
 223
 224 OpenSSL has a number of functions that return a method object with no
 225 associated implementation, such as L<EVP_sha256(3)>,
 226 L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>, which are present for
 227 compatibility with OpenSSL before version 3.0.
 228
 229 When they are used with functions like L<EVP_DigestInit_ex(3)> or
 230 L<EVP_CipherInit_ex(3)>, the actual implementation to be used is
 231 fetched implicitly using default search criteria.
 232
 233 Implicit fetching can also occur when a NULL algorithm parameter is
 234 supplied.
 235 In this case an algorithm implementation is implicitly fetched using
 236 default search criteria and an algorithm name that is consistent with
 237 the type of EVP_PKEY being used.
 238
 239 =head3 Algorithm naming
 240
 241 Algorithm names are case insensitive. Any particular algorithm can have multiple
 242 aliases associated with it. The canonical OpenSSL naming scheme follows this
 243 format:
 244
 245 ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]
 246
 247 VERSION is only present if there are multiple versions of an algorithm (e.g.
 248 MD2, MD4, MD5).  It may be omitted if there is only one version.
 249
 250 SUBNAME may be present where multiple algorithms are combined together,
 251 e.g. MD5-SHA1.
 252
 253 SIZE is only present if multiple versions of an algorithm exist with different
 254 sizes (e.g. AES-128-CBC, AES-256-CBC)
 255
 256 MODE is only present where applicable.
 257
 258 Other aliases may exist for example where standards bodies or common practice
 259 use alternative names or names that OpenSSL has used historically.
 260
 261 =head1 OPENSSL PROVIDERS
 262
 263 OpenSSL comes with a set of providers.
 264
 265 The algorithms available in each of these providers may vary due to build time
 266 configuration options. The L<openssl-list(1)> command can be used to list the
 267 currently available algorithms.
 268
 269 The names of the algorithms shown from L<openssl-list(1)> can be used as an
 270 algorithm identifier to the appropriate fetching function.
 271
 272 =head2 Default provider
 273
 274 The default provider is built in as part of the F<libcrypto> library.
 275 Should it be needed (if other providers are loaded and offer
 276 implementations of the same algorithms), the property "provider=default"
 277 can be used as a search criterion for these implementations.  The default
 278 provider includes all the functionality of the base provider below.
 279
 280 =head2 Base provider
 281
 282 The base provider is built in as part of the F<libcrypto> library.
 283 Should it be needed (if other providers are loaded and offer
 284 implementations of the same algorithms), the property "provider=base"
 285 can be used as a search criterion for these implementations. Some
 286 non-cryptographic algorithms (such as encoders for loading keys and
 287 parameters from files) are not FIPS algorithm implementations in themselves but
 288 support algorithms from the FIPS provider and are allowed for use in "FIPS
 289 mode". The property "fips=yes" can be used to select such algorithms.
 290
 291 =head2 FIPS provider
 292
 293 The FIPS provider is a dynamically loadable module, and must therefore
 294 be loaded explicitly, either in code or through OpenSSL configuration
 295 (see L<config(5)>).
 296 Should it be needed (if other providers are loaded and offer
 297 implementations of the same algorithms), the property "provider=fips" can
 298 be used as a search criterion for these implementations. All approved algorithm
 299 implementations in the FIPS provider can also be selected with the property
 300 "fips=yes". The FIPS provider also contains a number of non-approved algorithm
 301 implementations and these can be selected with the property "fips=no".
 302
 303 =head2 Legacy provider
 304
 305 The legacy provider is a dynamically loadable module, and must therefore
 306 be loaded explicitly, either in code or through OpenSSL configuration
 307 (see L<config(5)>).
 308 Should it be needed (if other providers are loaded and offer
 309 implementations of the same algorithms), the property "provider=legacy" can be
 310 used as a search criterion for these implementations.
 311
 312 =head2 Null provider
 313
 314 The null provider is built in as part of the F<libcrypto> library. It contains
 315 no algorithms in it at all. When fetching algorithms the default provider will
 316 be automatically loaded if no other provider has been explicitly loaded. To
 317 prevent that from happening you can explicitly load the null provider.
 318
 319 =head1 EXAMPLES
 320
 321 =head2 Fetching
 322
 323 Fetch any available implementation of SHA2-256 in the default context:
 324
 325  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
 326  ...
 327  EVP_MD_meth_free(md);
 328
 329 Fetch any available implementation of AES-128-CBC in the default context:
 330
 331  EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
 332  ...
 333  EVP_CIPHER_meth_free(cipher);
 334
 335 Fetch an implementation of SHA2-256 from the default provider in the default
 336 context:
 337
 338  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
 339  ...
 340  EVP_MD_meth_free(md);
 341
 342 Fetch an implementation of SHA2-256 that is not from the default provider in the
 343 default context:
 344
 345  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
 346  ...
 347  EVP_MD_meth_free(md);
 348
 349 Fetch an implementation of SHA2-256 from the default provider in the specified
 350 context:
 351
 352  EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default");
 353  ...
 354  EVP_MD_meth_free(md);
 355
 356 Load the legacy provider into the default context and then fetch an
 357 implementation of WHIRLPOOL from it:
 358
 359  /* This only needs to be done once - usually at application start up */
 360  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 361
 362  EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
 363  ...
 364  EVP_MD_meth_free(md);
 365
 366 Note that in the above example the property string "provider=legacy" is optional
 367 since, assuming no other providers have been loaded, the only implementation of
 368 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
 369 default provider should be explicitly loaded if it is required in addition to
 370 other providers:
 371
 372  /* This only needs to be done once - usually at application start up */
 373  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 374  OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
 375
 376  EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
 377  EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
 378  ...
 379  EVP_MD_meth_free(md_whirlpool);
 380  EVP_MD_meth_free(md_sha256);
 381
 382
 383 =head1 SEE ALSO
 384
 385 L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>,
 386 L<OPENSSL_CTX(3)>,
 387 L<EVP_set_default_properties(3)>,
 388 L<EVP_MD_fetch(3)>,
 389 L<EVP_CIPHER_fetch(3)>,
 390 L<EVP_KEYMGMT_fetch(3)>,
 391 L<openssl-core.h(7)>,
 392 L<provider-base(7)>,
 393 L<provider-digest(7)>,
 394 L<provider-cipher(7)>,
 395 L<provider-keyexch(7)>
 396
 397 =head1 HISTORY
 398
 399 The concept of providers and everything surrounding them was
 400 introduced in OpenSSL 3.0.
 401
 402 =head1 COPYRIGHT
 403
 404 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 405
 406 Licensed under the Apache License 2.0 (the "License").  You may not use
 407 this file except in compliance with the License.  You can obtain a copy
 408 in the file LICENSE in the source distribution or at
 409 L<https://www.openssl.org/source/license.html>.
 410
 411 =cut