]>
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 | ||
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 | } |