diff options
| -rw-r--r-- | README-PROVIDERS.md | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/README-PROVIDERS.md b/README-PROVIDERS.md new file mode 100644 index 0000000000..5092d039f3 --- /dev/null +++ b/README-PROVIDERS.md @@ -0,0 +1,151 @@ +Providers +========= + + - [Standard Providers](#standard-providers) + - [The Default Provider](#the-default-provider) + - [The Legacy Provider](#the-legacy-provider) + - [The FIPS Provider](#the-fips-provider) + - [The Base Provider](#the-base-provider) + - [The Null Provider](#the-null-provider) + - [Loading Providers](#loading-providers) + + +Standard Providers +================== + +Providers are containers for algorithm implementations. Whenever a cryptographic +algorithm is used via the high level APIs a provider is selected. It is that +provider implementation that actually does the required work. There are five +providers distributed with OpenSSL. In the future we expect third parties to +distribute their own providers which can be added to OpenSSL dynamically. +Documentation about writing providers is available on the [provider(7)] +manual page. + + [provider(7)]: https://www.openssl.org/docs/manmaster/man7/provider.html + + +The Default Provider +-------------------- + +The default provider collects together all of the standard built-in OpenSSL +algorithm implementations. If an application doesn't specify anything else +explicitly (e.g. in the application or via config), then this is the provider +that will be used. It is loaded automatically the first time that we try to +get an algorithm from a provider if no other provider has been loaded yet. +If another provider has already been loaded then it won't be loaded +automatically. Therefore if you want to use it in conjunction with other +providers then you must load it explicitly. + +This is a "built-in" provider which means that it is compiled and linked +into the libcrypto library and does not exist as a separate standalone module. + +The Legacy Provider +------------------- + +The legacy provider is a collection of legacy algorithms that are either no +longer in common use or considered insecure and strongly discouraged from use. +However, some applications may need to use these algorithms for backwards +compatibility reasons. This provider is **not** loaded by default. +This may mean that some applications upgrading from earlier versions of OpenSSL +may find that some algorithms are no longer available unless they load the +legacy provider explicitly. + +Algorithms in the legacy provider include MD2, MD4, MDC2, RMD160, CAST5, +BF (Blowfish), IDEA, SEED, RC2, RC4, RC5 and DES (but not 3DES). + +The FIPS Provider +----------------- + +The FIPS provider contains a sub-set of the algorithm implementations available +from the default provider, consisting of algorithms conforming to FIPS standards. +It is intended that this provider will be FIPS140-2 validated. + +In some cases there may be minor behavioural differences between algorithm +implementations in this provider compared to the equivalent algorithm in the +default provider. This is typically in order to conform to FIPS standards. + +The Base Provider +----------------- + +The base provider contains a small sub-set of non-cryptographic algorithms +available in the default provider. For example, it contains algorithms to +serialize and deserialize keys to files. If you do not load the default +provider then you should always load this one instead (in particular, if +you are using the FIPS provider). + +The Null Provider +----------------- + +The null provider is "built-in" to libcrypto and contains no algorithm +implementations. In order to guarantee that the default provider is not +automatically loaded, the null provider can be loaded instead. + +This can be useful if you are using non-default library contexts and want +to ensure that the default library context is never used unintentionally. + + +Loading Providers +================= + + +Providers to be loaded can be specified in the OpenSSL config file. +See the [config(5)] manual page for information about how to configure +providers via the config file, and how to automatically activate them. + + [config(5)]: https://www.openssl.org/docs/manmaster/man5/config.html + +The following is a minimal config file example to load and activate both +the legacy and the default provider in the default library context. + + openssl_conf = openssl_init + + [openssl_init] + providers = provider_sect + + [provider_sect] + default = default_sect + legacy = legacy_sect + + [default_sect] + activate = 1 + + [legacy_sect] + activate = 1 + + +It is also possible to load providers programmatically. For example you can +load the legacy provider into the default library context as shown below. +Note that once you have explicitly loaded a provider into the library context +the default provider will no longer be automatically loaded. Therefore you will +often also want to explicitly load the default provider, as is done here: + + + #include <stdio.h> + #include <stdlib.h> + + #include <openssl/provider.h> + + int main(void) + { + OSSL_PROVIDER *legacy; + OSSL_PROVIDER *deflt; + + /* Load Multiple providers into the default (NULL) library context */ + legacy = OSSL_PROVIDER_load(NULL, "legacy"); + if (legacy == NULL) { + printf("Failed to load Legacy provider\n"); + exit(EXIT_FAILURE); + } + deflt = OSSL_PROVIDER_load(NULL, "default"); + if (deflt == NULL) { + printf("Failed to load Default provider\n"); + OSSL_PROVIDER_unload(legacy); + exit(EXIT_FAILURE); + } + + /* Rest of application */ + + OSSL_PROVIDER_unload(legacy); + OSSL_PROVIDER_unload(deflt); + exit(EXIT_SUCCESS); + } |