4
=for comment openssl_manual_section:5
8
config - OpenSSL CONF library configuration files
12
The OpenSSL CONF library can be used to read configuration files.
13
It is used for the OpenSSL master configuration file B<openssl.cnf>
14
and in a few other places like B<SPKAC> files and certificate extension
15
files for the B<x509> utility. OpenSSL applications can also use the
16
CONF library for their own purposes.
18
A configuration file is divided into a number of sections. Each section
19
starts with a line B<[ section_name ]> and ends when a new section is
20
started or end of file is reached. A section name can consist of
21
alphanumeric characters and underscores.
23
The first section of a configuration file is special and is referred
24
to as the B<default> section this is usually unnamed and is from the
25
start of file until the first named section. When a name is being looked up
26
it is first looked up in a named section (if any) and then the
29
The environment is mapped onto a section called B<ENV>.
31
Comments can be included by preceding them with the B<#> character
33
Each section in a configuration file consists of a number of name and
34
value pairs of the form B<name=value>
36
The B<name> string can contain any alphanumeric characters as well as
37
a few punctuation symbols such as B<.> B<,> B<;> and B<_>.
39
The B<value> string consists of the string following the B<=> character
40
until end of line with any leading and trailing white space removed.
42
The value string undergoes variable expansion. This can be done by
43
including the form B<$var> or B<${var}>: this will substitute the value
44
of the named variable in the current section. It is also possible to
45
substitute a value from another section using the syntax B<$section::name>
46
or B<${section::name}>. By using the form B<$ENV::name> environment
47
variables can be substituted. It is also possible to assign values to
48
environment variables by using the name B<ENV::name>, this will work
49
if the program looks up environment variables using the B<CONF> library
50
instead of calling B<getenv()> directly.
52
It is possible to escape certain characters by using any kind of quote
53
or the B<\> character. By making the last character of a line a B<\>
54
a B<value> string can be spread across multiple lines. In addition
55
the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
57
=head1 OPENSSL LIBRARY CONFIGURATION
59
In OpenSSL 0.9.7 and later applications can automatically configure certain
60
aspects of OpenSSL using the master OpenSSL configuration file, or optionally
61
an alternative configuration file. The B<openssl> utility includes this
62
functionality: any sub command uses the master OpenSSL configuration file
63
unless an option is used in the sub command to use an alternative configuration
66
To enable library configuration the default section needs to contain an
67
appropriate line which points to the main configuration section. The default
68
name is B<openssl_conf> which is used by the B<openssl> utility. Other
69
applications may use an alternative name such as B<myapplicaton_conf>.
71
The configuration section should consist of a set of name value pairs which
72
contain specific module configuration information. The B<name> represents
73
the name of the I<configuration module> the meaning of the B<value> is
74
module specific: it may, for example, represent a further configuration
75
section containing configuration module specific information. E.g.
77
openssl_conf = openssl_init
81
oid_section = new_oids
82
engines = engine_section
90
... engine stuff here ...
92
Currently there are two configuration modules. One for ASN1 objects another
93
for ENGINE configuration.
95
=head2 ASN1 OBJECT CONFIGURATION MODULE
97
This module has the name B<oid_section>. The value of this variable points
98
to a section containing name value pairs of OIDs: the name is the OID short
99
and long name, the value is the numerical form of the OID. Although some of
100
the B<openssl> utility sub commands already have their own ASN1 OBJECT section
101
functionality not all do. By using the ASN1 OBJECT configuration module
102
B<all> the B<openssl> utility sub commands can see the new objects as well
103
as any compliant applications. For example:
107
some_new_oid = 1.2.3.4
108
some_other_oid = 1.2.3.5
110
In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
111
by a comma and the numerical OID form. For example:
113
shortName = some object long name, 1.2.3.4
115
=head2 ENGINE CONFIGURATION MODULE
117
This ENGINE configuration module has the name B<engines>. The value of this
118
variable points to a section containing further ENGINE configuration
121
The section pointed to by B<engines> is a table of engine names (though see
122
B<engine_id> below) and further sections containing configuration informations
123
specific to each ENGINE.
125
Each ENGINE specific section is used to set default algorithms, load
126
dynamic, perform initialization and send ctrls. The actual operation performed
127
depends on the I<command> name which is the name of the name value pair. The
128
currently supported commands are listed below.
134
# Configure ENGINE named "foo"
136
# Configure ENGINE named "bar"
140
... foo ENGINE specific commands ...
143
... "bar" ENGINE specific commands ...
145
The command B<engine_id> is used to give the ENGINE name. If used this
146
command must be first. For example:
149
# This would normally handle an ENGINE named "foo"
153
# Override default name and use "myfoo" instead.
156
The command B<dynamic_path> loads and adds an ENGINE from the given path. It
157
is equivalent to sending the ctrls B<SO_PATH> with the path argument followed
158
by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is
159
not the required behaviour then alternative ctrls can be sent directly
160
to the dynamic ENGINE using ctrl commands.
162
The command B<init> determines whether to initialize the ENGINE. If the value
163
is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to
164
initialized the ENGINE immediately. If the B<init> command is not present
165
then an attempt will be made to initialize the ENGINE after all commands in
166
its section have been processed.
168
The command B<default_algorithms> sets the default algorithms an ENGINE will
169
supply using the functions B<ENGINE_set_default_string()>
171
If the name matches none of the above command names it is assumed to be a
172
ctrl command which is sent to the ENGINE. The value of the command is the
173
argument to the ctrl command. If the value is the string B<EMPTY> then no
174
value is sent to the command.
181
# Configure ENGINE named "foo"
185
# Load engine from DSO
186
dynamic_path = /some/path/fooengine.so
187
# A foo specific ctrl.
188
some_ctrl = some_value
189
# Another ctrl that doesn't take a value.
191
# Supply all default algorithms
192
default_algorithms = ALL
196
If a configuration file attempts to expand a variable that doesn't exist
197
then an error is flagged and the file will not load. This can happen
198
if an attempt is made to expand an environment variable that doesn't
199
exist. For example in a previous version of OpenSSL the default OpenSSL
200
master configuration file used the value of B<HOME> which may not be
201
defined on non Unix systems and would cause an error.
203
This can be worked around by including a B<default> section to provide
204
a default value: then if the environment lookup fails the default value
205
will be used instead. For this to work properly the default value must
206
be defined earlier in the configuration file than the expansion. See
207
the B<EXAMPLES> section for an example of how to do this.
209
If the same variable exists in the same section then all but the last
210
value will be silently ignored. In certain circumstances such as with
211
DNs the same field may occur multiple times. This is usually worked
212
around by ignoring any characters before an initial B<.> e.g.
219
Here is a sample configuration file using some of the features
222
# This is the default section.
225
RANDFILE= ${ENV::HOME}/.rnd
226
configdir=$ENV::HOME/config
230
# We are now in section one.
232
# Quotes permit leading and trailing whitespace
233
any = " any variable name "
235
other = A string that can \
236
cover several lines \
237
by including \\ characters
239
message = Hello World\n
243
greeting = $section_one::message
245
This next example shows how to expand environment variables safely.
247
Suppose you want a variable called B<tmpfile> to refer to a
248
temporary filename. The directory it is placed in can determined by
249
the the B<TEMP> or B<TMP> environment variables but they may not be
250
set to any value at all. If you just include the environment variable
251
names and the variable doesn't exist then this will cause an error when
252
an attempt is made to load the configuration file. By making use of the
253
default section both values can be looked up with B<TEMP> taking
254
priority and B</tmp> used if neither is defined:
257
# The above value is used if TMP isn't in the environment
259
# The above value is used if TEMP isn't in the environment
260
tmpfile=${ENV::TEMP}/tmp.filename
264
Currently there is no way to include characters using the octal B<\nnn>
265
form. Strings are all null terminated so nulls cannot form part of
268
The escaping isn't quite right: if you want to use sequences like B<\n>
269
you can't use any quote escaping on the same line.
271
Files are loaded in a single pass. This means that an variable expansion
272
will only work if the variables referenced are defined earlier in the
277
L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)>
added
removed
.pc/openssl-pod-misspell.patch/doc/apps/config.pod
