README-PROVIDERS.md

   1 Providers
   2 =========
   3
   4  - [Standard Providers](#standard-providers)
   5     - [The Default Provider](#the-default-provider)
   6     - [The Legacy Provider](#the-legacy-provider)
   7     - [The FIPS Provider](#the-fips-provider)
   8     - [The Base Provider](#the-base-provider)
   9     - [The Null Provider](#the-null-provider)
  10  - [Loading Providers](#loading-providers)
  11
  12 Standard Providers
  13 ==================
  14
  15 Providers are containers for algorithm implementations. Whenever a cryptographic
  16 algorithm is used via the high level APIs a provider is selected. It is that
  17 provider implementation that actually does the required work. There are five
  18 providers distributed with OpenSSL. In the future we expect third parties to
  19 distribute their own providers which can be added to OpenSSL dynamically.
  20 Documentation about writing providers is available on the [provider(7)]
  21 manual page.
  22
  23  [provider(7)]: https://www.openssl.org/docs/manmaster/man7/provider.html
  24
  25 The Default Provider
  26 --------------------
  27
  28 The default provider collects together all of the standard built-in OpenSSL
  29 algorithm implementations. If an application doesn't specify anything else
  30 explicitly (e.g. in the application or via config), then this is the provider
  31 that will be used. It is loaded automatically the first time that we try to
  32 get an algorithm from a provider if no other provider has been loaded yet.
  33 If another provider has already been loaded then it won't be loaded
  34 automatically. Therefore if you want to use it in conjunction with other
  35 providers then you must load it explicitly.
  36
  37 This is a "built-in" provider which means that it is compiled and linked
  38 into the libcrypto library and does not exist as a separate standalone module.
  39
  40 The Legacy Provider
  41 -------------------
  42
  43 The legacy provider is a collection of legacy algorithms that are either no
  44 longer in common use or considered insecure and strongly discouraged from use.
  45 However, some applications may need to use these algorithms for backwards
  46 compatibility reasons. This provider is **not** loaded by default.
  47 This may mean that some applications upgrading from earlier versions of OpenSSL
  48 may find that some algorithms are no longer available unless they load the
  49 legacy provider explicitly.
  50
  51 Algorithms in the legacy provider include MD2, MD4, MDC2, RMD160, CAST5,
  52 BF (Blowfish), IDEA, SEED, RC2, RC4, RC5 and DES (but not 3DES).
  53
  54 The FIPS Provider
  55 -----------------
  56
  57 The FIPS provider contains a sub-set of the algorithm implementations available
  58 from the default provider, consisting of algorithms conforming to FIPS standards.
  59 It is intended that this provider will be FIPS140-2 validated.
  60
  61 In some cases there may be minor behavioural differences between algorithm
  62 implementations in this provider compared to the equivalent algorithm in the
  63 default provider. This is typically in order to conform to FIPS standards.
  64
  65 The Base Provider
  66 -----------------
  67
  68 The base provider contains a small sub-set of non-cryptographic algorithms
  69 available in the default provider. For example, it contains algorithms to
  70 serialize and deserialize keys to files. If you do not load the default
  71 provider then you should always load this one instead (in particular, if
  72 you are using the FIPS provider).
  73
  74 The Null Provider
  75 -----------------
  76
  77 The null provider is "built-in" to libcrypto and contains no algorithm
  78 implementations. In order to guarantee that the default provider is not
  79 automatically loaded, the null provider can be loaded instead.
  80
  81 This can be useful if you are using non-default library contexts and want
  82 to ensure that the default library context is never used unintentionally.
  83
  84 Loading Providers
  85 =================
  86
  87 Providers to be loaded can be specified in the OpenSSL config file.
  88 See the [config(5)] manual page for information about how to configure
  89 providers via the config file, and how to automatically activate them.
  90
  91  [config(5)]: https://www.openssl.org/docs/manmaster/man5/config.html
  92
  93 The following is a minimal config file example to load and activate both
  94 the legacy and the default provider in the default library context.
  95
  96     openssl_conf = openssl_init
  97
  98     [openssl_init]
  99     providers = provider_sect
 100
 101     [provider_sect]
 102     default = default_sect
 103     legacy = legacy_sect
 104
 105     [default_sect]
 106     activate = 1
 107
 108     [legacy_sect]
 109     activate = 1
 110
 111 It is also possible to load providers programmatically. For example you can
 112 load the legacy provider into the default library context as shown below.
 113 Note that once you have explicitly loaded a provider into the library context
 114 the default provider will no longer be automatically loaded. Therefore you will
 115 often also want to explicitly load the default provider, as is done here:
 116
 117     #include <stdio.h>
 118     #include <stdlib.h>
 119
 120     #include <openssl/provider.h>
 121
 122     int main(void)
 123     {
 124         OSSL_PROVIDER *legacy;
 125         OSSL_PROVIDER *deflt;
 126
 127         /* Load Multiple providers into the default (NULL) library context */
 128         legacy = OSSL_PROVIDER_load(NULL, "legacy");
 129         if (legacy == NULL) {
 130             printf("Failed to load Legacy provider\n");
 131             exit(EXIT_FAILURE);
 132         }
 133         deflt = OSSL_PROVIDER_load(NULL, "default");
 134         if (deflt == NULL) {
 135             printf("Failed to load Default provider\n");
 136             OSSL_PROVIDER_unload(legacy);
 137             exit(EXIT_FAILURE);
 138         }
 139
 140         /* Rest of application */
 141
 142         OSSL_PROVIDER_unload(legacy);
 143         OSSL_PROVIDER_unload(deflt);
 144         exit(EXIT_SUCCESS);
 145     }