Update README.md with openssl.cnf instructions

Signed-off-by: Steve Linsell <stevenx.linsell@intel.com>

Author: stevelinsell

README.md

@@ -118,7 +118,7 @@ copy files to. Please see the OpenSSL\* INSTALL file for full details on
 usage of the `--prefix` option.
 
 The following example is assuming:
- 
+
 * The OpenSSL\* source was cloned from Github\* to its own location at
   the root of the drive: `/`.
 * You want OpenSSL\* to be installed to `/usr/local/ssl`.
@@ -145,18 +145,18 @@ the engine is used.
 Further information on building OpenSSL\* can be found in the INSTALL
 file distributed with the OpenSSL\* source code or on the official
 OpenSSL\* Wiki in the Compilation and Installation section:
-https://wiki.openssl.org/index.php/Compilation_and_Installation
+<https://wiki.openssl.org/index.php/Compilation_and_Installation>
 
 ### Clone the Intel&reg; Quickassist Technology OpenSSL\* Engine
 
 Clone the Github\* repository containing the Intel&reg; Quickassist
 Technology OpenSSL\* Engine:
 
     git clone https://github.com/01org/QAT_Engine.git
-    
+
 The repository can be cloned to either a subdirectory within the OpenSSL\*
-repository, for instance if the OpenSSL\* source is located at 
-`/openssl` then the engine could be cloned at `/openssl/engines`, 
+repository, for instance if the OpenSSL\* source is located at
+`/openssl` then the engine could be cloned at `/openssl/engines`,
 or to its own unique location on the file system, for instance within
 `/`. In either case the engine will not be built as part of the OpenSSL\*
 build and will require building manually.
@@ -204,9 +204,9 @@ As an alternative the Upstream Intel&reg; QuickAssist Technology Driver comes
 with its own contiguous pinned memory driver that is compatible with the
 Intel&reg; QuickAssist Technology OpenSSL\* Engine. The USDM component is of
 a higher quality than the qat\_contig\_mem driver, and is the preferred option.
-Unfortunately the USDM component may not be available if using older 
+Unfortunately the USDM component may not be available if using older
 Intel&reg; QuickAssist Technology Driver versions. The USDM component is used
-by the Upstream Intel&reg; QuickAssist Technology Driver itself, and also 
+by the Upstream Intel&reg; QuickAssist Technology Driver itself, and also
 has the following additional features:
 
 * Support for virtualization
@@ -273,7 +273,7 @@ options that may be required:
   component and that the link should be configured to link in the
   userspace library of the usdm component.
 
-An example to build and install the Intel&reg; Quickassist Technology 
+An example to build and install the Intel&reg; Quickassist Technology
 OpenSSL\* Engine based on the example above, but building against the
 Upstream Intel&reg; Quickassist Technology Driver, and using the USDM
 component would be as follows:
@@ -289,7 +289,7 @@ component would be as follows:
     make
     make install
 ```
- 
+
 ### Copy the correct Intel&reg; Quickassist Technology Driver config files
 
 The Intel&reg; Quickassist Technology OpenSSL\* Engine comes with some example
@@ -444,7 +444,7 @@ installed. To resolve this it is recommended to add the /lib64
 folder to the LD_LIBRARY_PATH environment variable as follows:
 
     export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib64
-    
+
 If linking against the Upstream Intel&reg; Quickassist
 Technology Driver then ensure that the mandatory parameter
 `--enable-upstream_driver` has been specified when running
@@ -645,13 +645,13 @@ OpenSSL\* Engine:
 
     Mandatory (when using the Upstream Intel&reg; Quickassist Technology
     Driver)
-    
+
     --enable-upstream_driver/--disable-upsteam_driver
         Enable/Disable linking against the Upstream Intel&reg; Quickassist
         Technology Driver. If linking against the Upstream Intel&reg;
         Quickassist Driver then this option must be enabled (disabled by
         default).
-    
+
     Optional
 
     --with-qat_build_dir=/path/to/qat_driver/build
@@ -661,16 +661,16 @@ OpenSSL\* Engine:
         Quickassist Technology Driver. The default if not specified is to
         use the path specified by --with-qat_dir with '/build' appended.
         You only need to specify this parameter if the driver library
-        files have been built somewhere other than the default. 
-        
+        files have been built somewhere other than the default.
+
     --enable-usdm/--disable-usdm
         Enable/Disable compiling against the USDM component and that the
         link should be configured to link in the userspace library of the
         USDM component. The USDM component is a pinned contiguous memory
         driver that is distributed with the Upstream Intel&reg;
         Quickassist Technology Driver. It can be used instead of the
         supplied qat_contig_mem memory driver (disabled by default).
-        
+
     --with-usdm_dir=/path/to/usdm/directory
         Specify the path to the location of the USDM component.
         The default if not specified is to use the path specified by
@@ -763,6 +763,135 @@ OpenSSL\* Engine:
         Sets additional parameters that will be used during linking.
 ```
 
+## Using the OpenSSL\* Configuration File to Load/Initialize Engines
+
+OpenSSL\* includes support for loading and initializing engines via the
+openssl.cnf file. The openssl.cnf file is contained in the `ssl`
+subdirectory of the path you install OpenSSL\* to.
+By default OpenSSL\* does not load the openssl.cnf file at initialization
+time. In order to load the file you need to make the following function
+call from your application as the first call to the OpenSSL\* library:
+
+```
+    OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL);
+```
+
+The second parameter determines the name of the section containing the
+application specific initialization settings. If you set the parameter
+to NULL as in the example above it will default to look for the
+`openssl_conf` section. If you want to use your own section you should
+declare a structure of type `OPENSSL_INIT_SETTINGS` and set the `appname`
+field to a string containing the section name you wish to use. The example
+config file sections below assume you are using the default `openssl_conf`
+section name.
+
+If converting an existing application to use the Intel&reg; Quickassist
+Technology OpenSSL\* Engine you may find that the application instead
+makes the now deprecated call to:
+
+```
+    OPENSSL_config(NULL);
+```
+
+Where the parameter is a const char* pointer to the `appname` section
+you want to use, or NULL to use the default `openssl_conf` section.
+
+Currently this will give the same behaviour as the
+`OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL)` call but as it is
+deprecated it should not be relied upon for future use.
+
+For further details on using the OPENSSL_init_crypto
+function please see the OpenSSL\* online documentation located at:
+<https://www.openssl.org/docs/man1.1.0/crypto/OPENSSL_init_crypto.html>
+
+In order to start using the openssl.cnf file it needs some additional
+lines adding. You should add the following statement in the global section
+(this is the section before the first bracketed section header):
+
+```
+    openssl_conf = openssl_init
+```
+
+The string `openssl_init` is the name of the section in the configuration
+file which describes the application specific settings. You do not need
+to stick to the naming convention here if you prefer to use a different
+name.
+
+The `openssl_init` section can be located at the end of the global
+section (as the first bracketed section), or further down the
+configuration file. It should have the following added:
+
+```
+    [ openssl_init ]
+    engines = engine_section
+```
+
+The `engines` string is a keyword that OpenSSL\* recognises as a
+configuration module. It should be set to a string which is the
+section name containing a list of the engines to be
+loaded. So for the Intel&reg; Quickassist Technology OpenSSL\*
+Engine the section should contain:
+
+```
+    [ engine_section ]
+    qat = qat_section
+```
+
+The `qat_section` contains all the settings relating to that
+particular engine. For instance it may contain:
+
+```
+    [ qat_section ]
+    engine_id = qat
+    dynamic_path = /usr/local/ssl/lib/engines_1_1/qat.so
+    default_algorithms = ALL
+```
+
+Where `engine_id` specifies the name of engine to load (should be `qat`).
+
+Where `dynamic_path` is the location of the loadable shared library
+implementing the engine. There is no need to specify this line if the engine
+is located within the standard path that OpenSSL\* was installed to.
+
+Where `default_algorithms` specifies which algorithms supplied by the engine
+should be used by default. Specify `ALL` to make all algorithms supplied
+by the engine be used by default.
+
+In addition the `qat_section` may contain settings that call custom
+engine specific messages. For instance:
+
+```
+    ENABLE_EVENT_DRIVEN_MODE = EMPTY
+```
+
+is functionally equivalent of making the following engine specific
+message function call:
+
+```
+    ENGINE_ctrl_cmd(e, "ENABLE_EVENT_DRIVEN_MODE", 0, NULL, NULL, 0);
+```
+
+You should set the setting to `EMPTY` if there are no parameters to pass,
+or assign the value that would be passed as the 4th parameter of the
+equivalent ENGINE_ctrl_cmd call. It should be noted that this mechanism
+is only useful for passing simple values at engine initialization time.
+You cannot pass 3rd parameter values, pass complex structures or deal
+with return values via this mechanism. Engine specific messages should
+be specified before the `default_algorithms` setting or incorrect
+behaviour may result. By default the engine will get initialized at the
+end of this section (after all the custom engine specific messages have
+been sent). This can be controlled via an additional `init` setting that
+is out of scope of the documentation here.
+
+For further details on using the OpenSSL\* configuration file please
+see the OpenSSL\* online documentation located at:
+<https://www.openssl.org/docs/man1.1.0/apps/config.html>
+
+By setting up the configuration file as above it is possible for instance
+to run the OpenSSL\* speed application to use the Intel&reg; Quickassist
+Technology OpenSSL\* Engine without needing to specify `-engine qat` as
+a command line option.
+
 ## Legal
 
 Intel, and Intel Atom are trademarks of