Config docs.

4 files changed, 167 insertions, 4 deletions

diff --git a/doc/crypto/CONF_modules_free.pod b/doc/crypto/CONF_modules_free.pod
new file mode 100644
index 0000000000..af8ae6a5c9
--- /dev/null
+++ b/doc/crypto/CONF_modules_free.pod
@@ -0,0 +1,47 @@
+=pod
+
+=head1 NAME
+
+ CONF_modules_free, CONF_modules_load, CONF_modules_unload -
+ OpenSSL configuration cleanup functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ void CONF_modules_free(void);
+ void CONF_modules_unload(int all);
+ void CONF_modules_finish(void);
+
+=head1 DESCRIPTION
+
+CONF_modules_free() closes down and frees up all memory allocated by all
+configuration modules.
+
+CONF_modules_finish() calls each configuration modules B<finish> handler
+to free up any configuration that module may have performed.
+
+CONF_modules_unload() finishes and unloads configuration modules. If
+B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
+B<all> is B<1> all modules, including builtin modules will be unloaded.
+
+=head1 NOTES
+
+Normally applications will only call CONF_modules_free() at application to
+tidy up any configuration performed.
+
+=head1 RETURN VALUE
+
+None of the functions return a value.
+
+=head1 SEE ALSO
+
+L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
+L<CONF_modules_load_file(3), CONF_modules_load_file(3)>
+
+=head1 HISTORY
+
+CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish()
+first appeared in OpenSSL 0.9.7.
+
+=cut
diff --git a/doc/crypto/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod
new file mode 100644
index 0000000000..9965d69bf2
--- /dev/null
+++ b/doc/crypto/CONF_modules_load_file.pod
@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+ CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ int CONF_modules_load_file(const char *filename, const char *appname,
+			   unsigned long flags);
+ int CONF_modules_load(const CONF *cnf, const char *appname,
+		      unsigned long flags);
+
+=head1 DESCRIPTION
+
+The function CONF_modules_load_file() configures OpenSSL using file
+B<filename> and application name B<appname>. If B<filename> is NULL
+the standard OpenSSL configuration file is used. If B<appname> is
+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>. 
+
+=head1 NOTES
+
+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.
+
+Normally any modules errors will add error information to the error queue. If
+B<CONF_MFLAGS_SILENT> is set no error information is added.
+
+If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is
+disabled.
+
+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
+
+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
+return value of the failing module (this will always be zero or negative).
+
+=head1 SEE ALSO
+
+L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
+L<CONF_free(3), CONF_free(3)>, L<err(3),err(3)>
+
+=head1 HISTORY
+
+CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7.
+
+=cut
diff --git a/doc/crypto/OPENSSL_config.pod b/doc/crypto/OPENSSL_config.pod
index 18da16f3c3..16600620cc 100644
--- a/doc/crypto/OPENSSL_config.pod
+++ b/doc/crypto/OPENSSL_config.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-OPENSSL_config, OPENSSL_no_config - minimal OpenSSL configuration
+OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions
 
 =head1 SYNOPSIS
 
@@ -32,7 +32,8 @@ and some new functionality can be supported automatically.
 
 It is also possible to automatically call OPENSSL_config() when an application
 calls OPENSSL_add_all_algorithms() by compiling an application with the
-preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd.
+preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. In this way configuration
+can be added without source changes.
 
 The environment variable B<OPENSSL_CONFIG> can be set to specify the location
 of the configuration file.
@@ -51,6 +52,9 @@ application calls OPENSSL_config() it doesn't need to know or care about
 ENGINE control operations because they can be performed by editing a
 configuration file.
 
+Applications should free up configuration at application closedown by calling
+CONF_modules_free().
+
 =head1 RESTRICTIONS
 
 The OPENSSL_config() function is designed to be a very simple "call it and
@@ -59,7 +63,7 @@ all errors silently and it can only load from the standard configuration file
 location for example.
 
 It is however B<much> better than nothing. Applications which need finer
-control over the configuration functionality should use the configuration
+control over their configuration functionality should use the configuration
 functions such as CONF_load_modules() directly.
 
 =head1 RETURN VALUES
@@ -68,7 +72,8 @@ Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
 
 =head1 SEE ALSO
 
-L<conf(5)|conf(5)>
+L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>,
+L<CONF_modules_free(3),CONF_modules_free(3)>
 
 =head1 HISTORY
 
diff --git a/doc/crypto/OPENSSL_load_builtin_modules.pod b/doc/crypto/OPENSSL_load_builtin_modules.pod
new file mode 100644
index 0000000000..f14dfaf005
--- /dev/null
+++ b/doc/crypto/OPENSSL_load_builtin_modules.pod
@@ -0,0 +1,51 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_load_builtin_modules - add standard configuration modules
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ void OPENSSL_load_builtin_modules(void);
+ void ASN1_add_oid_module(void);
+ ENGINE_add_conf_module();
+
+=head1 DESCRIPTION
+
+The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL
+configuration modules to the internal list. They can then be used by the
+OpenSSL configuration code.
+
+ASN1_add_oid_module() adds just the ASN1 OBJECT module.
+
+ENGINE_add_conf_module() adds just the ENGINE configuration module.
+
+=head1 NOTES
+
+If the simple configuration function OPENSSL_config() is called then 
+OPENSSL_load_builtin_modules() is called automatically.
+
+Applications which use the configuration functions directly will need to
+call OPENSSL_load_builtin_modules() themselves I<before> any other 
+configuration code.
+
+Applications should call OPENSSL_load_builtin_modules() to load all
+configuration modules instead of adding modules selectively: otherwise 
+functionality may be missing from the application if an when new
+modules are added.
+
+=head1 RETURN VALUE
+
+None of the functions return a value.
+
+=head1 SEE ALSO
+
+L<conf(3)|conf(3)>, L<OPENSSL_config(3)|OPENSSL_config(3)>
+
+=head1 HISTORY
+
+These functions first appeared in OpenSSL 0.9.7.
+
+=cut