1CONFIG(5) OpenSSL CONFIG(5)
2
6 config - OpenSSL CONF library configuration files
7
9 The OpenSSL CONF library can be used to read configuration files. It
10 is used for the OpenSSL master configuration file openssl.cnf and in a
11 few other places like SPKAC files and certificate extension files for
12 the x509 utility. OpenSSL applications can also use the CONF library
13 for their own purposes.
14 A configuration file is divided into a number of sections. Each section
16 starts with a line [ 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 The first section of a configuration file is special and is referred to
21 as the default section. This section is usually unnamed and spans from
22 the start of file until the first named section. When a name is being
23 looked up it is first looked up in a named section (if any) and then
24 the default section.
25 The environment is mapped onto a section called ENV.
27 Comments can be included by preceding them with the # character
29 Other files can be included using the .include directive followed by a
31 path. If the path points to a directory all files with names ending
32 with .cnf or .conf are included from the directory. Recursive
33 inclusion of directories from files in such directory is not supported.
34 That means the files in the included directory can also contain
35 .include directives but only inclusion of regular files is supported
36 there. The inclusion of directories is not supported on systems without
37 POSIX IO support.
38 It is strongly recommended to use absolute paths with the .include
40 directive. Relative paths are evaluated based on the application
41 current working directory so unless the configuration file containing
42 the .include directive is application specific the inclusion will not
43 work as expected.
44 Each section in a configuration file consists of a number of name and
46 value pairs of the form name=value
47 The name string can contain any alphanumeric characters as well as a
49 few punctuation symbols such as . , ; and _.
50 The value string consists of the string following the = character until
52 end of line with any leading and trailing white space removed.
53 The value string undergoes variable expansion. This can be done by
55 including the form $var or ${var}: this will substitute the value of
56 the named variable in the current section. It is also possible to
57 substitute a value from another section using the syntax $section::name
58 or ${section::name}. By using the form $ENV::name environment variables
59 can be substituted. It is also possible to assign values to environment
60 variables by using the name ENV::name, this will work if the program
61 looks up environment variables using the CONF library instead of
62 calling getenv() directly. The value string must not exceed 64k in
63 length after variable expansion. Otherwise an error will occur.
64 It is possible to escape certain characters by using any kind of quote
66 or the \ character. By making the last character of a line a \ a value
67 string can be spread across multiple lines. In addition the sequences
68 \n, \r, \b and \t are recognized.
69 All expansion and escape rules as described above that apply to value
71 also apply to the path of the .include directive.
72
74 Applications can automatically configure certain aspects of OpenSSL
75 using the master OpenSSL configuration file, or optionally an
76 alternative configuration file. The openssl utility includes this
77 functionality: any sub command uses the master OpenSSL configuration
78 file unless an option is used in the sub command to use an alternative
79 configuration file.
80 To enable library configuration the default section needs to contain an
82 appropriate line which points to the main configuration section. The
83 default name is openssl_conf which is used by the openssl utility.
84 Other applications may use an alternative name such as
85 myapplication_conf. All library configuration lines appear in the
86 default section at the start of the configuration file.
87 The configuration section should consist of a set of name value pairs
89 which contain specific module configuration information. The name
90 represents the name of the configuration module. The meaning of the
91 value is module specific: it may, for example, represent a further
92 configuration section containing configuration module specific
93 information. E.g.:
94 # This must be in the default section
96 openssl_conf = openssl_init
97 [openssl_init]
99 oid_section = new_oids
101 engines = engine_section
102 [new_oids]
104 ... new oids here ...
106 [engine_section]
108 ... engine stuff here ...
110 The features of each configuration module are described below.
112 ASN1 Object Configuration Module
114 This module has the name oid_section. The value of this variable points
115 to a section containing name value pairs of OIDs: the name is the OID
116 short and long name, the value is the numerical form of the OID.
117 Although some of the openssl utility sub commands already have their
118 own ASN1 OBJECT section functionality not all do. By using the ASN1
119 OBJECT configuration module all the openssl utility sub commands can
120 see the new objects as well as any compliant applications. For example:
121 [new_oids]
123 some_new_oid = 1.2.3.4
125 some_other_oid = 1.2.3.5
126 It is also possible to set the value to the long name followed by a
128 comma and the numerical OID form. For example:
129 shortName = some object long name, 1.2.3.4
131 Engine Configuration Module
133 This ENGINE configuration module has the name engines. The value of
134 this variable points to a section containing further ENGINE
135 configuration information.
136 The section pointed to by engines is a table of engine names (though
138 see engine_id below) and further sections containing configuration
139 information specific to each ENGINE.
140 Each ENGINE specific section is used to set default algorithms, load
142 dynamic, perform initialization and send ctrls. The actual operation
143 performed depends on the command name which is the name of the name
144 value pair. The currently supported commands are listed below.
145 For example:
147 [engine_section]
149 # Configure ENGINE named "foo"
151 foo = foo_section
152 # Configure ENGINE named "bar"
153 bar = bar_section
154 [foo_section]
156 ... foo ENGINE specific commands ...
157 [bar_section]
159 ... "bar" ENGINE specific commands ...
160 The command engine_id is used to give the ENGINE name. If used this
162 command must be first. For example:
163 [engine_section]
165 # This would normally handle an ENGINE named "foo"
166 foo = foo_section
167 [foo_section]
169 # Override default name and use "myfoo" instead.
170 engine_id = myfoo
171 The command dynamic_path loads and adds an ENGINE from the given path.
173 It is equivalent to sending the ctrls SO_PATH with the path argument
174 followed by LIST_ADD with value 2 and LOAD to the dynamic ENGINE. If
175 this is not the required behaviour then alternative ctrls can be sent
176 directly to the dynamic ENGINE using ctrl commands.
177 The command init determines whether to initialize the ENGINE. If the
179 value is 0 the ENGINE will not be initialized, if 1 and attempt it made
180 to initialized the ENGINE immediately. If the init command is not
181 present then an attempt will be made to initialize the ENGINE after all
182 commands in its section have been processed.
183 The command default_algorithms sets the default algorithms an ENGINE
185 will supply using the functions ENGINE_set_default_string().
186 If the name matches none of the above command names it is assumed to be
188 a ctrl command which is sent to the ENGINE. The value of the command is
189 the argument to the ctrl command. If the value is the string EMPTY then
190 no value is sent to the command.
191 For example:
193 [engine_section]
195 # Configure ENGINE named "foo"
197 foo = foo_section
198 [foo_section]
200 # Load engine from DSO
201 dynamic_path = /some/path/fooengine.so
202 # A foo specific ctrl.
203 some_ctrl = some_value
204 # Another ctrl that doesn't take a value.
205 other_ctrl = EMPTY
206 # Supply all default algorithms
207 default_algorithms = ALL
208 EVP Configuration Module
210 This modules has the name alg_section which points to a section
211 containing algorithm commands.
212 Currently the only algorithm command supported is fips_mode whose value
214 can only be the boolean string off. If fips_mode is set to on, an error
215 occurs as this library version is not FIPS capable.
216 SSL Configuration Module
218 This module has the name ssl_conf which points to a section containing
219 SSL configurations.
220 Each line in the SSL configuration section contains the name of the
222 configuration and the section containing it.
223 Each configuration section consists of command value pairs for
225 SSL_CONF. Each pair will be passed to a SSL_CTX or SSL structure if it
226 calls SSL_CTX_config() or SSL_config() with the appropriate
227 configuration name.
228 Note: any characters before an initial dot in the configuration section
230 are ignored so the same command can be used multiple times.
231 For example:
233 ssl_conf = ssl_sect
235 [ssl_sect]
237 server = server_section
239 [server_section]
241 RSA.Certificate = server-rsa.pem
243 ECDSA.Certificate = server-ecdsa.pem
244 Ciphers = ALL:!RC4
245 The system default configuration with name system_default if present
247 will be applied during any creation of the SSL_CTX structure.
248 Example of a configuration with the system default:
250 ssl_conf = ssl_sect
252 [ssl_sect]
254 system_default = system_default_sect
256 [system_default_sect]
258 MinProtocol = TLSv1.2
260
262 If a configuration file attempts to expand a variable that doesn't
263 exist then an error is flagged and the file will not load. This can
264 happen if an attempt is made to expand an environment variable that
265 doesn't exist. For example in a previous version of OpenSSL the default
266 OpenSSL master configuration file used the value of HOME which may not
267 be defined on non Unix systems and would cause an error.
268 This can be worked around by including a default section to provide a
270 default value: then if the environment lookup fails the default value
271 will be used instead. For this to work properly the default value must
272 be defined earlier in the configuration file than the expansion. See
273 the EXAMPLES section for an example of how to do this.
274 If the same variable exists in the same section then all but the last
276 value will be silently ignored. In certain circumstances such as with
277 DNs the same field may occur multiple times. This is usually worked
278 around by ignoring any characters before an initial . e.g.
279 1.OU="My first OU"
281 2.OU="My Second OU"
282
284 Here is a sample configuration file using some of the features
285 mentioned above.
286 # This is the default section.
288 HOME=/temp
290 RANDFILE= ${ENV::HOME}/.rnd
291 configdir=$ENV::HOME/config
292 [ section_one ]
294 # We are now in section one.
296 # Quotes permit leading and trailing whitespace
298 any = " any variable name "
299 other = A string that can \
301 cover several lines \
302 by including \\ characters
303 message = Hello World\n
305 [ section_two ]
307 greeting = $section_one::message
309 This next example shows how to expand environment variables safely.
311 Suppose you want a variable called tmpfile to refer to a temporary
313 filename. The directory it is placed in can determined by the TEMP or
314 TMP environment variables but they may not be set to any value at all.
315 If you just include the environment variable names and the variable
316 doesn't exist then this will cause an error when an attempt is made to
317 load the configuration file. By making use of the default section both
318 values can be looked up with TEMP taking priority and /tmp used if
319 neither is defined:
320 TMP=/tmp
322 # The above value is used if TMP isn't in the environment
323 TEMP=$ENV::TMP
324 # The above value is used if TEMP isn't in the environment
325 tmpfile=${ENV::TEMP}/tmp.filename
326 Simple OpenSSL library configuration example to enter FIPS mode:
328 # Default appname: should match "appname" parameter (if any)
330 # supplied to CONF_modules_load_file et al.
331 openssl_conf = openssl_conf_section
332 [openssl_conf_section]
334 # Configuration module list
335 alg_section = evp_sect
336 [evp_sect]
338 # Set to "yes" to enter FIPS mode if supported
339 fips_mode = yes
340 Note: in the above example you will get an error in non FIPS capable
342 versions of OpenSSL.
343 More complex OpenSSL library configuration. Add OID and don't enter
345 FIPS mode:
346 # Default appname: should match "appname" parameter (if any)
348 # supplied to CONF_modules_load_file et al.
349 openssl_conf = openssl_conf_section
350 [openssl_conf_section]
352 # Configuration module list
353 alg_section = evp_sect
354 oid_section = new_oids
355 [evp_sect]
357 # This will have no effect as FIPS mode is off by default.
358 # Set to "yes" to enter FIPS mode, if supported
359 fips_mode = no
360 [new_oids]
362 # New OID, just short name
363 newoid1 = 1.2.3.4.1
364 # New OID shortname and long name
365 newoid2 = New OID 2 long name, 1.2.3.4.2
366 The above examples can be used with any application supporting library
368 configuration if "openssl_conf" is modified to match the appropriate
369 "appname".
370 For example if the second sample file above is saved to "example.cnf"
372 then the command line:
373 OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
375 will output:
377 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
379 showing that the OID "newoid1" has been added as "1.2.3.4.1".
381
383 OPENSSL_CONF
384 The path to the config file. Ignored in set-user-ID and set-group-
385 ID programs.
386 OPENSSL_ENGINES
388 The path to the engines directory. Ignored in set-user-ID and set-
389 group-ID programs.
390
392 Currently there is no way to include characters using the octal \nnn
393 form. Strings are all null terminated so nulls cannot form part of the
394 value.
395 The escaping isn't quite right: if you want to use sequences like \n
397 you can't use any quote escaping on the same line.
398 Files are loaded in a single pass. This means that an variable
400 expansion will only work if the variables referenced are defined
401 earlier in the file.
402
404 x509(1), req(1), ca(1)
405
407 Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
408 Licensed under the OpenSSL license (the "License"). You may not use
410 this file except in compliance with the License. You can obtain a copy
411 in the file LICENSE in the source distribution or at
412 <https://www.openssl.org/source/license.html>.
4131.1.1 2018-09-11 CONFIG(5)