138 lines
4.9 KiB
Text
138 lines
4.9 KiB
Text
|
|
=pod
|
|
|
|
=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.
|
|
|
|
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.
|
|
|
|
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 recognised.
|
|
|
|
=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 the default OpenSSL master configuration file used
|
|
the value of B<HOME> which may not be defined on non Unix systems.
|
|
|
|
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
|
|
|
|
=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
|
|
|
|
x509(1), req(1), ca(1)
|
|
|
|
=cut
|