xref: /openssl/README-PROVIDERS.md (revision 3e3ad3c5) 
1Providers
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
12Standard Providers
13==================
14
15Providers are containers for algorithm implementations. Whenever a cryptographic
16algorithm is used via the high level APIs a provider is selected. It is that
17provider implementation that actually does the required work. There are five
18providers distributed with OpenSSL. In the future we expect third parties to
19distribute their own providers which can be added to OpenSSL dynamically.
20Documentation about writing providers is available on the [provider(7)]
21manual page.
22
23 [provider(7)]: https://www.openssl.org/docs/manmaster/man7/provider.html
24
25The Default Provider
26--------------------
27
28The default provider collects together all of the standard built-in OpenSSL
29algorithm implementations. If an application doesn't specify anything else
30explicitly (e.g. in the application or via config), then this is the provider
31that will be used. It is loaded automatically the first time that we try to
32get an algorithm from a provider if no other provider has been loaded yet.
33If another provider has already been loaded then it won't be loaded
34automatically. Therefore if you want to use it in conjunction with other
35providers then you must load it explicitly.
36
37This is a "built-in" provider which means that it is compiled and linked
38into the libcrypto library and does not exist as a separate standalone module.
39
40The Legacy Provider
41-------------------
42
43The legacy provider is a collection of legacy algorithms that are either no
44longer in common use or considered insecure and strongly discouraged from use.
45However, some applications may need to use these algorithms for backwards
46compatibility reasons. This provider is **not** loaded by default.
47This may mean that some applications upgrading from earlier versions of OpenSSL
48may find that some algorithms are no longer available unless they load the
49legacy provider explicitly.
50
51Algorithms in the legacy provider include MD2, MD4, MDC2, RMD160, CAST5,
52BF (Blowfish), IDEA, SEED, RC2, RC4, RC5 and DES (but not 3DES).
53
54The FIPS Provider
55-----------------
56
57The FIPS provider contains a sub-set of the algorithm implementations available
58from the default provider, consisting of algorithms conforming to FIPS standards.
59It is intended that this provider will be FIPS140-2 validated.
60
61In some cases there may be minor behavioural differences between algorithm
62implementations in this provider compared to the equivalent algorithm in the
63default provider. This is typically in order to conform to FIPS standards.
64
65The Base Provider
66-----------------
67
68The base provider contains a small sub-set of non-cryptographic algorithms
69available in the default provider. For example, it contains algorithms to
70serialize and deserialize keys to files. If you do not load the default
71provider then you should always load this one instead (in particular, if
72you are using the FIPS provider).
73
74The Null Provider
75-----------------
76
77The null provider is "built-in" to libcrypto and contains no algorithm
78implementations. In order to guarantee that the default provider is not
79automatically loaded, the null provider can be loaded instead.
80
81This can be useful if you are using non-default library contexts and want
82to ensure that the default library context is never used unintentionally.
83
84Loading Providers
85=================
86
87Providers to be loaded can be specified in the OpenSSL config file.
88See the [config(5)] manual page for information about how to configure
89providers via the config file, and how to automatically activate them.
90
91 [config(5)]: https://www.openssl.org/docs/manmaster/man5/config.html
92
93The following is a minimal config file example to load and activate both
94the 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
111It is also possible to load providers programmatically. For example you can
112load the legacy provider into the default library context as shown below.
113Note that once you have explicitly loaded a provider into the library context
114the default provider will no longer be automatically loaded. Therefore you will
115often 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    }
146