additional configuration documentation

Reviewed-by: Andy Polyakov <appro@openssl.org>
(cherry picked from commit 3d764db7a24e3dca1a3ee57202ce3c818d592141)

2 files changed, 102 insertions, 7 deletions

diff --git a/doc/apps/config.pod b/doc/apps/config.pod
index 25c5381b9d..d5cce54f44 100644
--- a/doc/apps/config.pod
+++ b/doc/apps/config.pod
@@ -89,8 +89,7 @@ section containing configuration module specific information. E.g.
 
  ... engine stuff here ...
 
-Currently there are two configuration modules. One for ASN1 objects another
-for ENGINE configuration.
+The features of each configuration module are described below.
 
 =head2 ASN1 OBJECT CONFIGURATION MODULE
 
@@ -191,6 +190,25 @@ For example:
  # Supply all default algorithms
  default_algorithms = ALL
 
+=head2 EVP CONFIGURATION MODULE
+
+This modules has the name B<alg_section> which points to a section containing
+algorithm commands.
+
+Currently the only algorithm command supported is B<fips_mode> whose
+value should be a boolean string such as B<on> or B<off>. If the value is
+B<on> this attempt to enter FIPS mode. If the call fails or the library is
+not FIPS capable then an error occurs.
+
+For example:
+
+ alg_section = evp_settings
+
+ [evp_settings]
+
+ fips_mode = on
+
+
 =head1 NOTES
 
 If a configuration file attempts to expand a variable that doesn't exist
diff --git a/doc/crypto/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod
index 0c4d926858..cc0b537b8e 100644
--- a/doc/crypto/CONF_modules_load_file.pod
+++ b/doc/crypto/CONF_modules_load_file.pod
@@ -9,9 +9,9 @@
  #include <openssl/conf.h>
 
  int CONF_modules_load_file(const char *filename, const char *appname,
-			   unsigned long flags);
+			                unsigned long flags);
  int CONF_modules_load(const CONF *cnf, const char *appname,
-		      unsigned long flags);
+		               unsigned long flags);
 
 =head1 DESCRIPTION
 
@@ -22,7 +22,7 @@ NULL the standard OpenSSL application name B<openssl_conf> is used.
 The behaviour can be cutomized using B<flags>.
 
 CONF_modules_load() is idential to CONF_modules_load_file() except it
-read configuration information from B<cnf>. 
+reads configuration information from B<cnf>.
 
 =head1 NOTES
 
@@ -30,7 +30,7 @@ The following B<flags> are currently recognized:
 
 B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual
 configuration modules are ignored. If not set the first module error is
-considered fatal and no further modules are loads.
+considered fatal and no further modules are loaded.
 
 Normally any modules errors will add error information to the error queue. If
 B<CONF_MFLAGS_SILENT> is set no error information is added.
@@ -42,7 +42,84 @@ B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
 ignore missing configuration files. Normally a missing configuration file
 return an error.
 
-=head1 RETURN VALUE
+B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
+default section pointed to by B<openssl_conf> if B<appname> does not exist.
+
+Applications should call these functions after loading builtin modules using
+OPENSSL_load_builtin_modules(), any ENGINEs for example using
+ENGINE_load_builtin_engines(), any algorithms for example
+OPENSSL_add_all_algorithms() and (if the application uses libssl)
+SSL_library_init().
+
+By using CONF_modules_load_file() with appropriate flags an application can
+customise application configuration to best suit its needs. In some cases the
+use of a configuration file is optional and its absence is not an error: in
+this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
+
+Errors during configuration may also be handled differently by different
+applications. For example in some cases an error may simply print out a warning
+message and the application continue. In other cases an application might
+consider a configuration file error as fatal and exit immediately.
+
+Applications can use the CONF_modules_load() function if they wish to load a
+configuration file themselves and have finer control over how errors are
+treated.
+
+=head1 EXAMPLES
+
+Load a configuration file and print out any errors and exit (missing file
+considered fatal):
+
+ if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
+    fprintf(stderr, "FATAL: error loading configuration file\n");
+    ERR_print_errors_fp(stderr);
+    exit(1);
+ }
+
+Load default configuration file using the section indicated by "myapp",
+tolerate missing files, but exit on other errors:
+
+ if (CONF_modules_load_file(NULL, "myapp",
+                            CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
+    fprintf(stderr, "FATAL: error loading configuration file\n");
+    ERR_print_errors_fp(stderr);
+    exit(1);
+ }
+
+Load custom configuration file and section, only print warnings on error,
+missing configuration file ignored:
+
+ if (CONF_modules_load_file("/something/app.cnf", "myapp",
+                            CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
+    fprintf(stderr, "WARNING: error loading configuration file\n");
+    ERR_print_errors_fp(stderr);
+ }
+
+Load and parse configuration file manually, custom error handling:
+
+ FILE *fp;
+ CONF *cnf = NULL;
+ long eline;
+ fp = fopen("/somepath/app.cnf", "r");
+ if (fp == NULL) {
+    fprintf(stderr, "Error opening configuration file\n");
+    /* Other missing configuration file behaviour */
+ } else {
+    cnf = NCONF_new(NULL);
+    if (NCONF_load_fp(cnf, fp, &eline) == 0) {
+        fprintf(stderr, "Error on line %ld of configuration file\n", eline);
+        ERR_print_errors_fp(stderr);
+        /* Other malformed configuration file behaviour */
+    } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
+      fprintf(stderr, "Error configuring application\n");
+      ERR_print_errors_fp(stderr);
+      /* Other configuration error behaviour */
+    }
+    fclose(fp);
+    NCONF_free(cnf);
+  }
+
+=head1 RETURN VALUES
 
 These functions return 1 for success and a zero or negative value for
 failure. If module errors are not ignored the return code will reflect the