Handle negative reply for NNTP STARTTLS in s_client
[openssl.git] / doc / man5 / config.pod
1 =pod
2
3 =head1 NAME
4
5 config - OpenSSL CONF library configuration files
6
7 =head1 DESCRIPTION
8
9 The OpenSSL CONF library can be used to read configuration files.
10 It is used for the OpenSSL master configuration file B<openssl.cnf>
11 and in a few other places like B<SPKAC> files and certificate extension
12 files for the B<x509> utility. OpenSSL applications can also use the
13 CONF library for their own purposes.
14
15 A configuration file is divided into a number of sections. Each section
16 starts with a line B<[ section_name ]> and ends when a new section is
17 started or end of file is reached. A section name can consist of
18 alphanumeric characters and underscores.
19
20 The first section of a configuration file is special and is referred
21 to as the B<default> section this is usually unnamed and is from the
22 start of file until the first named section. When a name is being looked up
23 it is first looked up in a named section (if any) and then the
24 default section.
25
26 The environment is mapped onto a section called B<ENV>.
27
28 Comments can be included by preceding them with the B<#> character
29
30 Each section in a configuration file consists of a number of name and
31 value pairs of the form B<name=value>
32
33 The B<name> string can contain any alphanumeric characters as well as
34 a few punctuation symbols such as B<.> B<,> B<;> and B<_>.
35
36 The B<value> string consists of the string following the B<=> character
37 until end of line with any leading and trailing white space removed.
38
39 The value string undergoes variable expansion. This can be done by
40 including the form B<$var> or B<${var}>: this will substitute the value
41 of the named variable in the current section. It is also possible to
42 substitute a value from another section using the syntax B<$section::name>
43 or B<${section::name}>. By using the form B<$ENV::name> environment
44 variables can be substituted. It is also possible to assign values to
45 environment variables by using the name B<ENV::name>, this will work
46 if the program looks up environment variables using the B<CONF> library
47 instead of calling getenv() directly.
48
49 It is possible to escape certain characters by using any kind of quote
50 or the B<\> character. By making the last character of a line a B<\>
51 a B<value> string can be spread across multiple lines. In addition
52 the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
53
54 =head1 OPENSSL LIBRARY CONFIGURATION
55
56 Applications can automatically configure certain
57 aspects of OpenSSL using the master OpenSSL configuration file, or optionally
58 an alternative configuration file. The B<openssl> utility includes this
59 functionality: any sub command uses the master OpenSSL configuration file
60 unless an option is used in the sub command to use an alternative configuration
61 file.
62
63 To enable library configuration the default section needs to contain an
64 appropriate line which points to the main configuration section. The default
65 name is B<openssl_conf> which is used by the B<openssl> utility. Other
66 applications may use an alternative name such as B<myapplicaton_conf>.
67
68 The configuration section should consist of a set of name value pairs which
69 contain specific module configuration information. The B<name> represents
70 the name of the I<configuration module> the meaning of the B<value> is
71 module specific: it may, for example, represent a further configuration
72 section containing configuration module specific information. E.g.
73
74  openssl_conf = openssl_init
75
76  [openssl_init]
77
78  oid_section = new_oids
79  engines = engine_section
80
81  [new_oids]
82
83  ... new oids here ...
84
85  [engine_section]
86
87  ... engine stuff here ...
88
89 The features of each configuration module are described below.
90
91 =head2 ASN1 Object Configuration Module
92
93 This module has the name B<oid_section>. The value of this variable points
94 to a section containing name value pairs of OIDs: the name is the OID short
95 and long name, the value is the numerical form of the OID. Although some of
96 the B<openssl> utility sub commands already have their own ASN1 OBJECT section
97 functionality not all do. By using the ASN1 OBJECT configuration module
98 B<all> the B<openssl> utility sub commands can see the new objects as well
99 as any compliant applications. For example:
100
101  [new_oids]
102
103  some_new_oid = 1.2.3.4
104  some_other_oid = 1.2.3.5
105
106 It is also possible to set the value to the long name followed
107 by a comma and the numerical OID form. For example:
108
109  shortName = some object long name, 1.2.3.4
110
111 =head2 Engine Configuration Module
112
113 This ENGINE configuration module has the name B<engines>. The value of this
114 variable points to a section containing further ENGINE configuration
115 information.
116
117 The section pointed to by B<engines> is a table of engine names (though see
118 B<engine_id> below) and further sections containing configuration information
119 specific to each ENGINE.
120
121 Each ENGINE specific section is used to set default algorithms, load
122 dynamic, perform initialization and send ctrls. The actual operation performed
123 depends on the I<command> name which is the name of the name value pair. The
124 currently supported commands are listed below.
125
126 For example:
127
128  [engine_section]
129
130  # Configure ENGINE named "foo"
131  foo = foo_section
132  # Configure ENGINE named "bar"
133  bar = bar_section
134
135  [foo_section]
136  ... foo ENGINE specific commands ...
137
138  [bar_section]
139  ... "bar" ENGINE specific commands ...
140
141 The command B<engine_id> is used to give the ENGINE name. If used this
142 command must be first. For example:
143
144  [engine_section]
145  # This would normally handle an ENGINE named "foo"
146  foo = foo_section
147
148  [foo_section]
149  # Override default name and use "myfoo" instead.
150  engine_id = myfoo
151
152 The command B<dynamic_path> loads and adds an ENGINE from the given path. It
153 is equivalent to sending the ctrls B<SO_PATH> with the path argument followed
154 by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is
155 not the required behaviour then alternative ctrls can be sent directly
156 to the dynamic ENGINE using ctrl commands.
157
158 The command B<init> determines whether to initialize the ENGINE. If the value
159 is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to
160 initialized the ENGINE immediately. If the B<init> command is not present
161 then an attempt will be made to initialize the ENGINE after all commands in
162 its section have been processed.
163
164 The command B<default_algorithms> sets the default algorithms an ENGINE will
165 supply using the functions ENGINE_set_default_string().
166
167 If the name matches none of the above command names it is assumed to be a
168 ctrl command which is sent to the ENGINE. The value of the command is the
169 argument to the ctrl command. If the value is the string B<EMPTY> then no
170 value is sent to the command.
171
172 For example:
173
174
175  [engine_section]
176
177  # Configure ENGINE named "foo"
178  foo = foo_section
179
180  [foo_section]
181  # Load engine from DSO
182  dynamic_path = /some/path/fooengine.so
183  # A foo specific ctrl.
184  some_ctrl = some_value
185  # Another ctrl that doesn't take a value.
186  other_ctrl = EMPTY
187  # Supply all default algorithms
188  default_algorithms = ALL
189
190 =head2 EVP Configuration Module
191
192 This modules has the name B<alg_section> which points to a section containing
193 algorithm commands.
194
195 Currently the only algorithm command supported is B<fips_mode> whose
196 value should be a boolean string such as B<on> or B<off>. If the value is
197 B<on> this attempt to enter FIPS mode. If the call fails or the library is
198 not FIPS capable then an error occurs.
199
200 For example:
201
202  alg_section = evp_settings
203
204  [evp_settings]
205
206  fips_mode = on
207
208 =head2 SSL Configuration Module
209
210 This module has the name B<ssl_conf> which points to a section containing
211 SSL configurations.
212
213 Each line in the SSL configuration section contains the name of the
214 configuration and the section containing it.
215
216 Each configuration section consists of command value pairs for B<SSL_CONF>.
217 Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls
218 SSL_CTX_config() or SSL_config() with the appropriate configuration name.
219
220 Note: any characters before an initial dot in the configuration section are
221 ignored so the same command can be used multiple times.
222
223 For example:
224
225  ssl_conf = ssl_sect
226
227  [ssl_sect]
228
229  server = server_section
230
231  [server_section]
232
233  RSA.Certificate = server-rsa.pem
234  ECDSA.Certificate = server-ecdsa.pem
235  Ciphers = ALL:!RC4
236
237 =head1 NOTES
238
239 If a configuration file attempts to expand a variable that doesn't exist
240 then an error is flagged and the file will not load. This can happen
241 if an attempt is made to expand an environment variable that doesn't
242 exist. For example in a previous version of OpenSSL the default OpenSSL
243 master configuration file used the value of B<HOME> which may not be
244 defined on non Unix systems and would cause an error.
245
246 This can be worked around by including a B<default> section to provide
247 a default value: then if the environment lookup fails the default value
248 will be used instead. For this to work properly the default value must
249 be defined earlier in the configuration file than the expansion. See
250 the B<EXAMPLES> section for an example of how to do this.
251
252 If the same variable exists in the same section then all but the last
253 value will be silently ignored. In certain circumstances such as with
254 DNs the same field may occur multiple times. This is usually worked
255 around by ignoring any characters before an initial B<.> e.g.
256
257  1.OU="My first OU"
258  2.OU="My Second OU"
259
260 =head1 EXAMPLES
261
262 Here is a sample configuration file using some of the features
263 mentioned above.
264
265  # This is the default section.
266
267  HOME=/temp
268  RANDFILE= ${ENV::HOME}/.rnd
269  configdir=$ENV::HOME/config
270
271  [ section_one ]
272
273  # We are now in section one.
274
275  # Quotes permit leading and trailing whitespace
276  any = " any variable name "
277
278  other = A string that can \
279  cover several lines \
280  by including \\ characters
281
282  message = Hello World\n
283
284  [ section_two ]
285
286  greeting = $section_one::message
287
288 This next example shows how to expand environment variables safely.
289
290 Suppose you want a variable called B<tmpfile> to refer to a
291 temporary filename. The directory it is placed in can determined by
292 the B<TEMP> or B<TMP> environment variables but they may not be
293 set to any value at all. If you just include the environment variable
294 names and the variable doesn't exist then this will cause an error when
295 an attempt is made to load the configuration file. By making use of the
296 default section both values can be looked up with B<TEMP> taking
297 priority and B</tmp> used if neither is defined:
298
299  TMP=/tmp
300  # The above value is used if TMP isn't in the environment
301  TEMP=$ENV::TMP
302  # The above value is used if TEMP isn't in the environment
303  tmpfile=${ENV::TEMP}/tmp.filename
304
305 Simple OpenSSL library configuration example to enter FIPS mode:
306
307  # Default appname: should match "appname" parameter (if any)
308  # supplied to CONF_modules_load_file et al.
309  openssl_conf = openssl_conf_section
310
311  [openssl_conf_section]
312  # Configuration module list
313  alg_section = evp_sect
314
315  [evp_sect]
316  # Set to "yes" to enter FIPS mode if supported
317  fips_mode = yes
318
319 Note: in the above example you will get an error in non FIPS capable versions
320 of OpenSSL.
321
322 More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
323
324  # Default appname: should match "appname" parameter (if any)
325  # supplied to CONF_modules_load_file et al.
326  openssl_conf = openssl_conf_section
327
328  [openssl_conf_section]
329  # Configuration module list
330  alg_section = evp_sect
331  oid_section = new_oids
332
333  [evp_sect]
334  # This will have no effect as FIPS mode is off by default.
335  # Set to "yes" to enter FIPS mode, if supported
336  fips_mode = no
337
338  [new_oids]
339  # New OID, just short name
340  newoid1 = 1.2.3.4.1
341  # New OID shortname and long name
342  newoid2 = New OID 2 long name, 1.2.3.4.2
343
344 The above examples can be used with any application supporting library
345 configuration if "openssl_conf" is modified to match the appropriate "appname".
346
347 For example if the second sample file above is saved to "example.cnf" then
348 the command line:
349
350  OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
351
352 will output:
353
354     0:d=0  hl=2 l=   4 prim: OBJECT            :newoid1
355
356 showing that the OID "newoid1" has been added as "1.2.3.4.1".
357
358 =head1 BUGS
359
360 Currently there is no way to include characters using the octal B<\nnn>
361 form. Strings are all null terminated so nulls cannot form part of
362 the value.
363
364 The escaping isn't quite right: if you want to use sequences like B<\n>
365 you can't use any quote escaping on the same line.
366
367 Files are loaded in a single pass. This means that an variable expansion
368 will only work if the variables referenced are defined earlier in the
369 file.
370
371 =head1 SEE ALSO
372
373 L<x509(1)>, L<req(1)>, L<ca(1)>
374
375 =head1 COPYRIGHT
376
377 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
378
379 Licensed under the OpenSSL license (the "License").  You may not use
380 this file except in compliance with the License.  You can obtain a copy
381 in the file LICENSE in the source distribution or at
382 L<https://www.openssl.org/source/license.html>.
383
384 =cut