Add a skeleton README-PROVIDERS file

The current content of this README file are just meant to be a
starting point and an incentive to add more. Most of the text
was borrowed from the [OpenSSL 3.0 Wiki], which is the reason
why a added Matt as co-author. To be continued...

[OpenSSL 3.0 Wiki]: https://wiki.openssl.org/index.php/OpenSSL_3.0

Co-authored-by: Matt Caswell <matt@openssl.org>

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14042)

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);
+    }