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 =item Serialization
 151
 152 In the OpenSSL libraries, the corresponding method object is
 153 B<OSSL_SERIALIZER>.
 154 The number for this operation is B<OSSL_OP_SERIALIZER>.
 155 The functions the provider can offer are described in
 156 L<provider-serializer(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 =head3 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 =head3 Algorithm naming
 228
 229 Algorithm names are case insensitive. Any particular algorithm can have multiple
 230 aliases associated with it. The canonical OpenSSL naming scheme follows this
 231 format:
 232
 233 ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]
 234
 235 VERSION is only present if there are multiple versions of an algorithm (e.g.
 236 MD2, MD4, MD5).  It may be omitted if there is only one version.
 237
 238 SUBNAME may be present where multiple algorithms are combined together,
 239 e.g. MD5-SHA1.
 240
 241 SIZE is only present if multiple versions of an algorithm exist with different
 242 sizes (e.g. AES-128-CBC, AES-256-CBC)
 243
 244 MODE is only present where applicable.
 245
 246 Other aliases may exist for example where standards bodies or common practice
 247 use alternative names or names that OpenSSL has used historically.
 248
 249 =head1 OPENSSL PROVIDERS
 250
 251 OpenSSL comes with a set of providers.
 252
 253 The algorithms available in each of these providers may vary due to build time
 254 configuration options. The L<openssl-list(1)> command can be used to list the
 255 currently available algorithms.
 256
 257 The names of the algorithms shown from L<openssl-list(1)> can be used as an
 258 algorithm identifier to the appropriate fetching function.
 259
 260 =head2 Default provider
 261
 262 The default provider is built in as part of the F<libcrypto> library.
 263 Should it be needed (if other providers are loaded and offer
 264 implementations of the same algorithms), the property "default=yes"
 265 can be used as a search criterion for these implementations.
 266
 267 =head2 FIPS provider
 268
 269 The FIPS provider is a dynamically loadable module, and must therefore
 270 be loaded explicitly, either in code or through OpenSSL configuration
 271 (see L<config(5)>).
 272 Should it be needed (if other providers are loaded and offer
 273 implementations of the same algorithms), the property "fips=yes" can
 274 be used as a search criterion for these implementations.
 275
 276 =head2 Legacy provider
 277
 278 The legacy provider is a dynamically loadable module, and must therefore
 279 be loaded explicitly, either in code or through OpenSSL configuration
 280 (see L<config(5)>).
 281 Should it be needed (if other providers are loaded and offer
 282 implementations of the same algorithms), the property "legacy=yes" can be
 283 used as a search criterion for these implementations.
 284
 285 =head1 EXAMPLES
 286
 287 =head2 Fetching
 288
 289 Fetch any available implementation of SHA2-256 in the default context:
 290
 291  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
 292  ...
 293  EVP_MD_meth_free(md);
 294
 295 Fetch any available implementation of AES-128-CBC in the default context:
 296
 297  EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
 298  ...
 299  EVP_CIPHER_meth_free(cipher);
 300
 301 Fetch an implementation of SHA2-256 from the default provider in the default
 302 context:
 303
 304  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "default=yes");
 305  ...
 306  EVP_MD_meth_free(md);
 307
 308 Fetch an implementation of SHA2-256 that is not from the default provider in the
 309 default context:
 310
 311  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "default=no");
 312  ...
 313  EVP_MD_meth_free(md);
 314
 315 Fetch an implementation of SHA2-256 from the default provider in the specified
 316 context:
 317
 318  EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "default=yes");
 319  ...
 320  EVP_MD_meth_free(md);
 321
 322 Load the legacy provider into the default context and then fetch an
 323 implementation of WHIRLPOOL from it:
 324
 325  /* This only needs to be done once - usually at application start up */
 326  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 327
 328  EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "legacy=yes");
 329  ...
 330  EVP_MD_meth_free(md);
 331
 332 Note that in the above example the property string "legacy=yes" is optional
 333 since, assuming no other providers have been loaded, the only implementation of
 334 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
 335 default provider should be explicitly loaded if it is required in addition to
 336 other providers:
 337
 338  /* This only needs to be done once - usually at application start up */
 339  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 340  OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
 341
 342  EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
 343  EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
 344  ...
 345  EVP_MD_meth_free(md_whirlpool);
 346  EVP_MD_meth_free(md_sha256);
 347
 348
 349 =head1 SEE ALSO
 350
 351 L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>,
 352 L<EVP_PKEY_derive_init_ex(3)>,
 353 L<OPENSSL_CTX(3)>,
 354 L<EVP_set_default_properties(3)>,
 355 L<EVP_MD_fetch(3)>,
 356 L<EVP_CIPHER_fetch(3)>,
 357 L<EVP_KEYMGMT_fetch(3)>,
 358 L<openssl-core.h(7)>,
 359 L<provider-base(7)>,
 360 L<provider-digest(7)>,
 361 L<provider-cipher(7)>,
 362 L<provider-keyexch(7)>
 363
 364 =head1 HISTORY
 365
 366 The concept of providers and everything surrounding them was
 367 introduced in OpenSSL 3.0.
 368
 369 =head1 COPYRIGHT
 370
 371 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 372
 373 Licensed under the Apache License 2.0 (the "License").  You may not use
 374 this file except in compliance with the License.  You can obtain a copy
 375 in the file LICENSE in the source distribution or at
 376 L<https://www.openssl.org/source/license.html>.
 377
 378 =cut