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