A local copy of OpenSSL from GitHub
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

151 lines
5.4 KiB

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