From b6670f690c4244e63dbc02a2ba25061f9c53945f Mon Sep 17 00:00:00 2001
From: Richard Levitte <levitte@openssl.org>
Date: Sat, 30 Mar 2019 22:25:00 +0100
Subject: [PATCH] Replumbing: add documentation for the provider configuration
 module

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/8549)
---
 doc/man5/config.pod | 61 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index 3d0842c4e2..985b07ff3b 100644
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -106,6 +106,7 @@ section containing configuration module specific information. E.g.:
 
  oid_section = new_oids
  engines = engine_section
+ providers = provider_section
 
  [new_oids]
 
@@ -115,6 +116,10 @@ section containing configuration module specific information. E.g.:
 
  ... engine stuff here ...
 
+ [provider_section]
+
+ ... provider stuff here ...
+
 The features of each configuration module are described below.
 
 =head2 ASN1 Object Configuration Module
@@ -216,6 +221,57 @@ For example:
  # Supply all default algorithms
  default_algorithms = ALL
 
+=head2 Provider Configuration Module
+
+This provider configuration module has the name B<providers>. The
+value of this variable points to a section containing further provider
+configuration information.
+
+The section pointed to by B<providers> is a table of provider names
+(though see B<identity> below) and further sections containing
+configuration information specific to each provider module.
+
+Each provider specific section is used to load its module, perform
+activation and set parameters to pass to the provider on demand. The
+actual operation performed depends on the name of the name value pair.
+The currently supported commands are listed below.
+
+For example:
+
+ [provider_section]
+
+ # Configure provider named "foo"
+ foo = foo_section
+ # Configure provider named "bar"
+ bar = bar_section
+
+ [foo_section]
+ ... "foo" provider specific parameters ...
+
+ [bar_section]
+ ... "bar" provider specific parameters ...
+
+The command B<identity> is used to give the provider name. For example:
+
+ [provider_section]
+ # This would normally handle a provider named "foo"
+ foo = foo_section
+
+ [foo_section]
+ # Override default name and use "myfoo" instead.
+ identity = myfoo
+
+The parameter B<module> loads and adds a provider module from the
+given module path.  That path may be a simple file name, a relative
+path or an absolute path.
+
+The parameter B<activate> determines whether to activate the
+provider. The value has no importance, the presence of the parameter
+is enough for activation to take place.
+
+All parameters in the section as well as sub-sections are made
+available to the provider.
+
 =head2 EVP Configuration Module
 
 This modules has the name B<alg_section> which points to a section containing
@@ -405,6 +461,11 @@ Ignored in set-user-ID and set-group-ID programs.
 The path to the engines directory.
 Ignored in set-user-ID and set-group-ID programs.
 
+=item B<OPENSSL_MODULES>
+
+The path to the directory with OpenSSL modules, such as providers.
+Ignored in set-user-ID and set-group-ID programs.
+
 =back
 
 =head1 BUGS
-- 
2.34.1