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