X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fapps%2Fconfig.pod;h=22bb6c50a8cefd80f0dc0bc688f764727af6ec38;hb=035014cd22c502bca93c73e6475da73ee31f1078;hp=8f823fa6d69d1dfc1aaaa00ee107a378a014b414;hpb=f2c18125607f0871df4cb5dfbeaf830f57811184;p=openssl.git

diff --git a/doc/apps/config.pod b/doc/apps/config.pod
index 8f823fa6d6..22bb6c50a8 100644
--- 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
 
@@ -105,6 +106,11 @@ as any compliant applications. For example:
  some_new_oid = 1.2.3.4
  some_other_oid = 1.2.3.5
 
+In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
+by a comma and the numerical OID form. For example:
+
+ shortName = some object long name, 1.2.3.4
+
 =head2 ENGINE CONFIGURATION MODULE
 
 This ENGINE configuration module has the name B<engines>. The value of this
@@ -112,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
@@ -184,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
@@ -252,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>
@@ -267,6 +345,6 @@ file.
 
 =head1 SEE ALSO
 
-L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)>
+L<x509(1)>, L<req(1)>, L<ca(1)>
 
 =cut