Configuration file examples.

[openssl.git] / doc / apps / config.pod

diff --git a/doc/apps/config.pod b/doc/apps/config.pod
index 2158cf4253961c16ec80ecabd658a18d1bacc13a..e12591528c0cd8061d0e28b424756fa08c60a08e 100644 (file)
--- a/doc/apps/config.pod
+++ b/doc/apps/config.pod
@@ -1,6 +1,8 @@
 
 =pod
 
+=for comment openssl_manual_section:5
+
 =head1 NAME
 
 config - OpenSSL CONF library configuration files
@@ -87,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
 
@@ -117,7 +118,7 @@ variable points to a section containing further ENGINE configuration
 information.
 
 The section pointed to by B<engines> is a table of engine names (though see
-B<engine_id> below) and further sections containing configuration informations
+B<engine_id> below) and further sections containing configuration information
 specific to each ENGINE.
 
 Each ENGINE specific section is used to set default algorithms, load
@@ -189,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
@@ -257,6 +277,59 @@ priority and B</tmp> used if neither is defined:
  # The above value is used if TEMP isn't in the environment
  tmpfile=${ENV::TEMP}/tmp.filename
 
+Simple OpenSSL library configuration example to enter FIPS mode:
+
+ # Default appname: should match "appname" parameter (if any)
+ # supplied to CONF_modules_load_file et al.
+ openssl_conf = openssl_conf_section
+
+ [openssl_conf_section]
+ # Configuration module list
+ alg_section = evp_sect
+
+ [evp_sect]
+ # Set to "yes" to enter FIPS mode if supported
+ fips_mode = yes
+
+Note: in the above example you will get an error in non FIPS capable versions
+of OpenSSL.
+
+More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
+
+ # Default appname: should match "appname" parameter (if any)
+ # supplied to CONF_modules_load_file et al.
+ openssl_conf = openssl_conf_section
+
+ [openssl_conf_section]
+ # Configuration module list
+ alg_section = evp_sect
+ oid_section = new_oids
+
+ [evp_sect]
+ # This will have no effect as FIPS mode is off by default.
+ # Set to "yes" to enter FIPS mode, if supported
+ fips_mode = no
+
+ [new_oids]
+ # New OID, just short name
+ newoid1 = 1.2.3.4.1
+ # New OID shortname and long name
+ newoid2 = New OID 2 long name, 1.2.3.4.2
+
+The above examples can be used with with any application supporting library
+configuration if "openssl_conf" is modified to match the appropriate "appname".
+
+For example if the second sample file above is saved to "example.cnf" then
+the command line:
+
+ OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
+
+will output:
+
+    0:d=0  hl=2 l=   4 prim: OBJECT            :newoid1
+
+showing that the OID "newoid1" has been added as "1.2.3.4.1".
+
 =head1 BUGS
 
 Currently there is no way to include characters using the octal B<\nnn>