diff options
Diffstat (limited to 'doc/apps/config.pod')
| -rw-r--r-- | doc/apps/config.pod | 351 |
1 files changed, 0 insertions, 351 deletions
diff --git a/doc/apps/config.pod b/doc/apps/config.pod deleted file mode 100644 index 3f607d3b5fc8..000000000000 --- a/doc/apps/config.pod +++ /dev/null @@ -1,351 +0,0 @@ - -=pod - -=for comment openssl_manual_section:5 - -=head1 NAME - -config - OpenSSL CONF library configuration files - -=head1 DESCRIPTION - -The OpenSSL CONF library can be used to read configuration files. -It is used for the OpenSSL master configuration file B<openssl.cnf> -and in a few other places like B<SPKAC> files and certificate extension -files for the B<x509> utility. OpenSSL applications can also use the -CONF library for their own purposes. - -A configuration file is divided into a number of sections. Each section -starts with a line B<[ section_name ]> and ends when a new section is -started or end of file is reached. A section name can consist of -alphanumeric characters and underscores. - -The first section of a configuration file is special and is referred -to as the B<default> section this is usually unnamed and is from the -start of file until the first named section. When a name is being looked up -it is first looked up in a named section (if any) and then the -default section. - -The environment is mapped onto a section called B<ENV>. - -Comments can be included by preceding them with the B<#> character - -Each section in a configuration file consists of a number of name and -value pairs of the form B<name=value> - -The B<name> string can contain any alphanumeric characters as well as -a few punctuation symbols such as B<.> B<,> B<;> and B<_>. - -The B<value> string consists of the string following the B<=> character -until end of line with any leading and trailing white space removed. - -The value string undergoes variable expansion. This can be done by -including the form B<$var> or B<${var}>: this will substitute the value -of the named variable in the current section. It is also possible to -substitute a value from another section using the syntax B<$section::name> -or B<${section::name}>. By using the form B<$ENV::name> environment -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. The value string must not exceed 64k in -length after variable expansion. Otherwise an error will occur. - -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<\> -a B<value> string can be spread across multiple lines. In addition -the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. - -=head1 OPENSSL LIBRARY CONFIGURATION - -In OpenSSL 0.9.7 and later 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 -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 -module specific: it may, for example, represent a further configuration -section containing configuration module specific information. E.g. - - openssl_conf = openssl_init - - [openssl_init] - - oid_section = new_oids - engines = engine_section - - [new_oids] - - ... new oids here ... - - [engine_section] - - ... engine stuff here ... - -The features of each configuration module are described below. - -=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 -and long name, the value is the numerical form of the OID. Although some of -the B<openssl> utility sub commands already have their own ASN1 OBJECT section -functionality not all do. By using the ASN1 OBJECT configuration module -B<all> the B<openssl> utility sub commands can see the new objects as well -as any compliant applications. For example: - - [new_oids] - - 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 -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 B<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] - - fips_mode = on - - -=head1 NOTES - -If a configuration file attempts to expand a variable that doesn't exist -then an error is flagged and the file will not load. This can happen -if an attempt is made to expand an environment variable that doesn't -exist. For example in a previous version of OpenSSL the default OpenSSL -master configuration file used the value of B<HOME> which may not be -defined on non Unix systems and would cause an error. - -This can be worked around by including a B<default> section to provide -a default value: then if the environment lookup fails the default value -will be used instead. For this to work properly the default value must -be defined earlier in the configuration file than the expansion. See -the B<EXAMPLES> section for an example of how to do this. - -If the same variable exists in the same section then all but the last -value will be silently ignored. In certain circumstances such as with -DNs the same field may occur multiple times. This is usually worked -around by ignoring any characters before an initial B<.> e.g. - - 1.OU="My first OU" - 2.OU="My Second OU" - -=head1 EXAMPLES - -Here is a sample configuration file using some of the features -mentioned above. - - # This is the default section. - - HOME=/temp - RANDFILE= ${ENV::HOME}/.rnd - configdir=$ENV::HOME/config - - [ section_one ] - - # We are now in section one. - - # Quotes permit leading and trailing whitespace - any = " any variable name " - - other = A string that can \ - cover several lines \ - by including \\ characters - - message = Hello World\n - - [ section_two ] - - greeting = $section_one::message - -This next example shows how to expand environment variables safely. - -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 -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 -priority and B</tmp> used if neither is defined: - - TMP=/tmp - # The above value is used if TMP isn't in the environment - TEMP=$ENV::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 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> -form. Strings are all null terminated so nulls cannot form part of -the value. - -The escaping isn't quite right: if you want to use sequences like B<\n> -you can't use any quote escaping on the same line. - -Files are loaded in a single pass. This means that an variable expansion -will only work if the variables referenced are defined earlier in the -file. - -=head1 SEE ALSO - -L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)> - -=cut |