]>
Commit | Line | Data |
---|---|---|
a0ca1eed DMSP |
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 | ||
a0ca1eed DMSP |
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 | |
af33b200 | 18 | providers distributed with OpenSSL. In the future, we expect third parties to |
a0ca1eed DMSP |
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 | ||
a0ca1eed DMSP |
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 | |
af33b200 TS |
34 | automatically. Therefore, if you want to use it in conjunction with other |
35 | providers, then you must load it explicitly. | |
a0ca1eed | 36 | |
af33b200 | 37 | This is a "built-in" provider, which means that it is compiled and linked |
a0ca1eed DMSP |
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 | ||
af33b200 | 61 | In some cases, there may be minor behavioural differences between algorithm |
a0ca1eed DMSP |
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 | ||
a0ca1eed DMSP |
84 | Loading Providers |
85 | ================= | |
86 | ||
a0ca1eed DMSP |
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 | ||
a0ca1eed DMSP |
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 | ||
a0ca1eed DMSP |
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 | } |