| blob | de21a5d973ae716fb3738cfceabb29fa998f4823 |
1 .\" $OpenBSD: openssl.cnf.5,v 1.3 2017/07/06 15:42:04 schwarze Exp $
2 .\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3 .\"
4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5 .\" Copyright (c) 1999, 2000, 2004, 2013, 2015, 2016 The OpenSSL Project.
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: July 6 2017 $
53 .Dt OPENSSL.CNF 5
54 .Os
55 .Sh NAME
56 .Nm openssl.cnf
57 .Nd OpenSSL configuration files
58 .Sh DESCRIPTION
59 The OpenSSL CONF library can be used to read configuration files; see
60 .Xr CONF_modules_load_file 3 .
61 It is used for the OpenSSL master configuration file
62 .Pa /etc/ssl/openssl.cnf
63 and in a few other places like
64 .Sy SPKAC
65 files and certificate extension files for the
66 .Xr openssl 1
67 .Cm x509
68 utility.
69 OpenSSL applications can also use the CONF library for their own
70 purposes.
71 .Pp
72 A configuration file is divided into a number of sections.
73 Each section starts with a line
74 .Bq Ar section_name
75 and ends when a new section is started or the end of the file is reached.
76 A section name can consist of alphanumeric characters and underscores.
77 .Pp
78 The first section of a configuration file is special and is referred to
79 as the
80 .Dq default section .
81 It is usually unnamed and extends from the start of file to the
82 first named section.
83 When a name is being looked up, it is first looked up in a named
84 section (if any) and then in the default section.
85 .Pp
86 The environment is mapped onto a section called
87 .Ic ENV .
88 .Pp
89 Comments can be included by preceding them with the
90 .Ql #
91 character.
92 .Pp
93 Each section in a configuration file consists of a number of name and
94 value pairs of the form
95 .Ar name Ns = Ns Ar value .
96 .Pp
97 The
98 .Ar name
99 string can contain any alphanumeric characters as well as a few
100 punctuation symbols such as
101 .Ql \&.
102 .Ql \&,
103 .Ql \&;
104 and
105 .Ql _ .
106 .Pp
107 The
108 .Ar value
109 string consists of the string following the
110 .Ql =
111 character until the end of the line with any leading and trailing
112 whitespace removed.
113 .Pp
114 The value string undergoes variable expansion.
115 This can be done by including substrings of the form
116 .Pf $ Ar name
117 or
118 .Pf $ Brq Ar name :
119 this will substitute the value of the named variable in the current
120 section.
121 It is also possible to substitute a value from another section using the
122 syntax
123 .Pf $ Ar section Ns :: Ns Ar name
124 or
125 .Pf $ Brq Ar section Ns :: Ns Ar name .
126 By using the form
127 .Pf $ Ic ENV Ns :: Ns Ar name ,
128 environment variables can be substituted.
129 It is also possible to assign values to environment variables by using
130 the name
131 .Ic ENV Ns :: Ns Ar name .
132 This will work if the program looks up environment variables using
133 the CONF library instead of calling
134 .Xr getenv 3
135 directly.
136 .Pp
137 It is possible to escape certain characters by using any kind of quote
138 or the
139 .Ql \e
140 character.
141 By making the last character of a line a
142 .Ql \e ,
143 a
144 .Ar value
145 string can be spread across multiple lines.
146 In addition the sequences
147 .Ql \en ,
148 .Ql \er ,
149 .Ql \eb ,
150 and
151 .Ql \et
152 are recognized.
153 .Sh OPENSSL LIBRARY CONFIGURATION
154 Applications can automatically configure certain aspects of OpenSSL
155 using the master OpenSSL configuration file, or optionally an
156 alternative configuration file.
157 The
158 .Xr openssl 1
159 utility includes this functionality: any sub command uses the master
160 OpenSSL configuration file unless an option is used in the sub command
161 to use an alternative configuration file.
162 .Pp
163 To enable library configuration, the default section needs to contain
164 an appropriate line which points to the main configuration section.
165 The default name is
166 .Ic openssl_conf ,
167 which is used by the
168 .Xr openssl 1
169 utility.
170 Other applications may use an alternative name such as
171 .Sy myapplication_conf .
172 .Pp
173 The configuration section should consist of a set of name value pairs
174 which contain specific module configuration information.
175 The
176 .Ar name
177 represents the name of the configuration module.
178 The meaning of the
179 .Ar value
180 is module specific: it may, for example, represent a further
181 configuration section containing configuration module specific
182 information.
183 For example:
184 .Bd -literal -offset indent
185 openssl_conf = openssl_init
187 [openssl_init]
188 oid_section = new_oids
189 engines = engine_section
191 [new_oids]
192 \&... new oids here ...
194 [engine_section]
195 \&... engine stuff here ...
196 .Ed
197 .Pp
198 The features of each configuration module are described below.
199 .Ss ASN1 Object Configuration Module
200 This module has the name
201 .Ic oid_section .
202 The value of this variable points to a section containing name value
203 pairs of OIDs: the name is the OID short and long name, and the value is the
204 numerical form of the OID.
205 Although some of the
206 .Xr openssl 1
207 utility subcommands already have their own ASN1 OBJECT section
208 functionality, not all do.
209 By using the ASN1 OBJECT configuration module, all the
210 .Xr openssl 1
211 utility subcommands can see the new objects as well as any compliant
212 applications.
213 For example:
214 .Bd -literal -offset indent
215 [new_oids]
216 some_new_oid = 1.2.3.4
217 some_other_oid = 1.2.3.5
218 .Ed
219 .Pp
220 It is also possible to set the value to the long name followed by a
221 comma and the numerical OID form.
222 For example:
223 .Pp
224 .Dl shortName = some object long name, 1.2.3.4
225 .Ss Engine Configuration Module
226 This ENGINE configuration module has the name
227 .Ic engines .
228 The value of this variable points to a section containing further ENGINE
229 configuration information.
230 .Pp
231 The section pointed to by
232 .Ic engines
233 is a table of engine names (though see
234 .Ic engine_id
235 below) and further sections containing configuration information
236 specific to each ENGINE.
237 .Pp
238 Each ENGINE specific section is used to set default algorithms, load
239 dynamic ENGINEs, perform initialization and send ctrls.
240 The actual operation performed depends on the command
241 name which is the name of the name value pair.
242 The currently supported commands are listed below.
243 .Pp
244 For example:
245 .Bd -literal -offset indent
246 [engine_section]
247 # Configure ENGINE named "foo"
248 foo = foo_section
249 # Configure ENGINE named "bar"
250 bar = bar_section
252 [foo_section]
253 \&... foo ENGINE specific commands ...
255 [bar_section]
256 \&... "bar" ENGINE specific commands ...
257 .Ed
258 .Pp
259 The command
260 .Ic engine_id
261 is used to give the ENGINE name.
262 If used this command must be first.
263 For example:
264 .Bd -literal -offset indent
265 [engine_section]
266 # This would normally handle an ENGINE named "foo"
267 foo = foo_section
269 [foo_section]
270 # Override default name and use "myfoo" instead.
271 engine_id = myfoo
272 .Ed
273 .Pp
274 The command
275 .Ic dynamic_path
276 loads and adds an ENGINE from the given path.
277 It is equivalent to sending the ctrls
278 .Sy SO_PATH
279 with the path argument followed by
280 .Sy LIST_ADD
281 with value 2 and
282 .Sy LOAD
283 to the dynamic ENGINE.
284 If this is not the required behaviour then alternative ctrls can be sent
285 directly to the dynamic ENGINE using ctrl commands.
286 .Pp
287 The command
288 .Ic init
289 determines whether to initialize the ENGINE.
290 If the value is 0, the ENGINE will not be initialized.
291 If it is 1, an attempt is made to initialized the ENGINE immediately.
292 If the
293 .Ic init
294 command is not present, then an attempt will be made to initialize
295 the ENGINE after all commands in its section have been processed.
296 .Pp
297 The command
298 .Ic default_algorithms
299 sets the default algorithms an ENGINE will supply using the functions
300 .Xr ENGINE_set_default_string 3 .
301 .Pp
302 If the name matches none of the above command names it is assumed
303 to be a ctrl command which is sent to the ENGINE.
304 The value of the command is the argument to the ctrl command.
305 If the value is the string
306 .Cm EMPTY ,
307 then no value is sent to the command.
308 .Pp
309 For example:
310 .Bd -literal -offset indent
311 [engine_section]
312 # Configure ENGINE named "foo"
313 foo = foo_section
315 [foo_section]
316 # Load engine from DSO
317 dynamic_path = /some/path/fooengine.so
318 # A foo specific ctrl.
319 some_ctrl = some_value
320 # Another ctrl that doesn't take a value.
321 other_ctrl = EMPTY
322 # Supply all default algorithms
323 default_algorithms = ALL
324 .Ed
325 .Sh FILES
326 .Bl -tag -width /etc/ssl/openssl.cnf -compact
327 .It Pa /etc/ssl/openssl.cnf
328 standard configuration file
329 .El
330 .Sh EXAMPLES
331 Here is a sample configuration file using some of the features
332 mentioned above:
333 .Bd -literal -offset indent
334 # This is the default section.
335 HOME=/temp
336 RANDFILE= ${ENV::HOME}/.rnd
337 configdir=$ENV::HOME/config
339 [ section_one ]
340 # We are now in section one.
342 # Quotes permit leading and trailing whitespace
343 any = " any variable name "
345 other = A string that can \e
346 cover several lines \e
347 by including \e\e characters
349 message = Hello World\en
351 [ section_two ]
352 greeting = $section_one::message
353 .Ed
354 .Pp
355 This next example shows how to expand environment variables safely.
356 .Pp
357 Suppose you want a variable called
358 .Sy tmpfile
359 to refer to a temporary filename.
360 The directory it is placed in can determined by the
361 .Ev TEMP
362 or
363 .Ev TMP
364 environment variables but they may not be set to any value at all.
365 If you just include the environment variable names and the variable
366 doesn't exist then this will cause an error when an attempt is made to
367 load the configuration file.
368 By making use of the default section both values can be looked up with
369 .Ev TEMP
370 taking priority and
371 .Pa /tmp
372 used if neither is defined:
373 .Bd -literal -offset indent
374 TMP=/tmp
375 # The above value is used if TMP isn't in the environment
376 TEMP=$ENV::TMP
377 # The above value is used if TEMP isn't in the environment
378 tmpfile=${ENV::TEMP}/tmp.filename
379 .Ed
380 .Pp
381 More complex OpenSSL library configuration.
382 Add OID:
383 .Bd -literal -offset indent
384 # Default appname: should match "appname" parameter (if any)
385 # supplied to CONF_modules_load_file et al.
386 openssl_conf = openssl_conf_section
388 [openssl_conf_section]
389 # Configuration module list
390 alg_section = evp_sect
391 oid_section = new_oids
393 [new_oids]
394 # New OID, just short name
395 newoid1 = 1.2.3.4.1
396 # New OID shortname and long name
397 newoid2 = New OID 2 long name, 1.2.3.4.2
398 .Ed
399 .Pp
400 The above examples can be used with any application supporting library
401 configuration if "openssl_conf" is modified to match the appropriate
402 "appname".
403 .Pp
404 For example if the second sample file above is saved to "example.cnf"
405 then the command line:
406 .Pp
407 .Dl OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
408 .Pp
409 will output:
410 .Dl 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
411 .Pp
412 showing that the OID "newoid1" has been added as "1.2.3.4.1".
413 .Sh SEE ALSO
414 .Xr openssl 1 ,
415 .Xr CONF_modules_load_file 3 ,
416 .Xr x509v3.cnf 5
417 .Sh CAVEATS
418 If a configuration file attempts to expand a variable that doesn't
419 exist, then an error is flagged and the file will not load.
420 This can also happen if an attempt is made to expand an environment
421 variable that doesn't exist.
422 For example, in a previous version of OpenSSL the default OpenSSL
423 master configuration file used the value of
424 .Ev HOME
425 which may not be defined on non Unix systems and would cause an error.
426 .Pp
427 This can be worked around by including a default section to provide
428 a default value: then if the environment lookup fails, the default
429 value will be used instead.
430 For this to work properly, the default value must be defined earlier
431 in the configuration file than the expansion.
432 See the
433 .Sx EXAMPLES
434 section for an example of how to do this.
435 .Pp
436 If the same variable is defined more than once in the same section,
437 then all but the last value will be silently ignored.
438 In certain circumstances such as with DNs, the same field may occur
439 multiple times.
440 This is usually worked around by ignoring any characters before an
441 initial
442 .Ql \&. ,
443 for example:
444 .Bd -literal -offset indent
445 1.OU="My first OU"
446 2.OU="My Second OU"
447 .Ed
448 .Sh BUGS
449 Currently there is no way to include characters using the octal
450 .Pf \e Ar nnn
451 form.
452 Strings are all NUL terminated, so NUL bytes cannot form part of
453 the value.
454 .Pp
455 The escaping isn't quite right: if you want to use sequences like
456 .Ql \en ,
457 you can't use any quote escaping on the same line.
458 .Pp
459 Files are loaded in a single pass.
460 This means that an variable expansion will only work if the variables
461 referenced are defined earlier in the file.