-
=pod
+=for comment openssl_manual_section:5
+
=head1 NAME
config - OpenSSL CONF library configuration files
variables can be substituted. It is also possible to assign values to
environment variables by using the name B<ENV::name>, this will work
if the program looks up environment variables using the B<CONF> library
-instead of calling B<getenv()> directly.
+instead of calling getenv() directly.
It is possible to escape certain characters by using any kind of quote
or the B<\> character. By making the last character of a line a B<\>
=head1 OPENSSL LIBRARY CONFIGURATION
-In OpenSSL 0.9.7 and later applications can automatically configure certain
+Applications can automatically configure certain
aspects of OpenSSL using the master OpenSSL configuration file, or optionally
an alternative configuration file. The B<openssl> utility includes this
functionality: any sub command uses the master OpenSSL configuration file
unless an option is used in the sub command to use an alternative configuration
file.
-To enable library configuration the default section needs to contain an
+To enable library configuration the default section needs to contain an
appropriate line which points to the main configuration section. The default
name is B<openssl_conf> which is used by the B<openssl> utility. Other
applications may use an alternative name such as B<myapplicaton_conf>.
The configuration section should consist of a set of name value pairs which
contain specific module configuration information. The B<name> represents
-the name of the I<configuration module> the meaning of the B<value> is
+the name of the I<configuration module> the meaning of the B<value> is
module specific: it may, for example, represent a further configuration
section containing configuration module specific information. E.g.
... engine stuff here ...
-Currently there are two supported configuration modules supported. One for
-ASN1 objects another for ENGINE configuration.
+The features of each configuration module are described below.
-=head2 ASN1 OBJECT CONFIGURATION MODULE
+=head2 ASN1 Object Configuration Module
This module has the name B<oid_section>. The value of this variable points
to a section containing name value pairs of OIDs: the name is the OID short
as any compliant applications. For example:
[new_oids]
-
+
some_new_oid = 1.2.3.4
some_other_oid = 1.2.3.5
-=head2 ENGINE CONFIGURATION MODULE
+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
+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 information
+specific to each ENGINE.
+
+Each ENGINE specific section is used to set default algorithms, load
+dynamic, perform initialization and send ctrls. The actual operation performed
+depends on the I<command> name which is the name of the name value pair. The
+currently supported commands are listed below.
+
+For example:
+
+ [engine_section]
+
+ # Configure ENGINE named "foo"
+ foo = foo_section
+ # Configure ENGINE named "bar"
+ bar = bar_section
+
+ [foo_section]
+ ... foo ENGINE specific commands ...
+
+ [bar_section]
+ ... "bar" ENGINE specific commands ...
+
+The command B<engine_id> is used to give the ENGINE name. If used this
+command must be first. For example:
+
+ [engine_section]
+ # This would normally handle an ENGINE named "foo"
+ foo = foo_section
+
+ [foo_section]
+ # Override default name and use "myfoo" instead.
+ engine_id = myfoo
+
+The command B<dynamic_path> loads and adds an ENGINE from the given path. It
+is equivalent to sending the ctrls B<SO_PATH> with the path argument followed
+by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is
+not the required behaviour then alternative ctrls can be sent directly
+to the dynamic ENGINE using ctrl commands.
+
+The command B<init> determines whether to initialize the ENGINE. If the value
+is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to
+initialized the ENGINE immediately. If the B<init> command is not present
+then an attempt will be made to initialize the ENGINE after all commands in
+its section have been processed.
+
+The command B<default_algorithms> sets the default algorithms an ENGINE will
+supply using the functions ENGINE_set_default_string().
+
+If the name matches none of the above command names it is assumed to be a
+ctrl command which is sent to the ENGINE. The value of the command is the
+argument to the ctrl command. If the value is the string B<EMPTY> then no
+value is sent to the command.
+
+For example:
+
+
+ [engine_section]
+
+ # Configure ENGINE named "foo"
+ foo = foo_section
+
+ [foo_section]
+ # Load engine from DSO
+ dynamic_path = /some/path/fooengine.so
+ # A foo specific ctrl.
+ some_ctrl = some_value
+ # Another ctrl that doesn't take a value.
+ other_ctrl = EMPTY
+ # 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]
-To be continued...
+ fips_mode = on
+
+=head2 SSL Configuration Module
+
+This module has the name B<ssl_conf> which points to a section containing
+SSL configurations.
+
+Each line in the SSL configuration section contains the name of the
+configuration and the section containing it.
+
+Each configuration section consists of command value pairs for B<SSL_CONF>.
+Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls
+SSL_CTX_config() or SSL_config() with the appropriate configuration name.
+
+Note: any characters before an initial dot in the configuration section are
+ignored so the same command can be used multiple times.
+
+For example:
+
+ ssl_conf = ssl_sect
+
+ [ssl_sect]
+
+ server = server_section
+
+ [server_section]
+
+ RSA.Certificate = server-rsa.pem
+ ECDSA.Certificate = server-ecdsa.pem
+ Ciphers = ALL:!RC4
=head1 NOTES
mentioned above.
# This is the default section.
-
+
HOME=/temp
RANDFILE= ${ENV::HOME}/.rnd
configdir=$ENV::HOME/config
Suppose you want a variable called B<tmpfile> to refer to a
temporary filename. The directory it is placed in can determined by
-the the B<TEMP> or B<TMP> environment variables but they may not be
+the B<TEMP> or B<TMP> environment variables but they may not be
set to any value at all. If you just include the environment variable
names and the variable doesn't exist then this will cause an error when
an attempt is made to load the configuration file. By making use of the
-default section both values can be looked up with B<TEMP> taking
+default section both values can be looked up with B<TEMP> taking
priority and B</tmp> used if neither is defined:
TMP=/tmp
# 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 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>
=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)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
=cut
projects / oweals / openssl.git / blobdiff