1CONFIG(5ossl) OpenSSL CONFIG(5ossl)
2
6 config - OpenSSL CONF library configuration files
7
9 This page documents the syntax of OpenSSL configuration files, as
10 parsed by NCONF_load(3) and related functions. This format is used by
11 many of the OpenSSL commands, and to initialize the libraries when used
12 by any application.
13 The first part describes the general syntax of the configuration files,
15 and subsequent sections describe the semantics of individual modules.
16 Other modules are described in fips_config(5) and x509v3_config(5).
17 The syntax for defining ASN.1 values is described in
18 ASN1_generate_nconf(3).
19
21 A configuration file is a series of lines. Blank lines, and whitespace
22 between the elements of a line, have no significance. A comment starts
23 with a # character; the rest of the line is ignored. If the # is the
24 first non-space character in a line, the entire line is ignored.
25 Directives
27 Two directives can be used to control the parsing of configuration
28 files: .include and .pragma.
29 For compatibility with older versions of OpenSSL, an equal sign after
31 the directive will be ignored. Older versions will treat it as an
32 assignment, so care should be taken if the difference in semantics is
33 important.
34 A file can include other files using the include syntax:
36 .include [=] pathname
38 If pathname is a simple filename, that file is included directly at
40 that point. Included files can have .include statements that specify
41 other files. If pathname is a directory, all files within that
42 directory that have a ".cnf" or ".conf" extension will be included.
43 (This is only available on systems with POSIX IO support.) Any sub-
44 directories found inside the pathname are ignored. Similarly, if a
45 file is opened while scanning a directory, and that file has an
46 .include directive that specifies a directory, that is also ignored.
47 As a general rule, the pathname should be an absolute path; this can be
49 enforced with the abspath and includedir pragmas, described below. The
50 environment variable OPENSSL_CONF_INCLUDE, if it exists, is prepended
51 to all relative pathnames. If the pathname is still relative, it is
52 interpreted based on the current working directory.
53 To require all file inclusions to name absolute paths, use the
55 following directive:
56 .pragma [=] abspath:value
58 The default behavior, where the value is false or off, is to allow
60 relative paths. To require all .include pathnames to be absolute paths,
61 use a value of true or on.
62 In these files, the dollar sign, $, is used to reference a variable, as
64 described below. On some platforms, however, it is common to treat $
65 as a regular character in symbol names. Supporting this behavior can
66 be done with the following directive:
67 .pragma [=] dollarid:value
69 The default behavior, where the value is false or off, is to treat the
71 dollarsign as indicating a variable name; "foo$bar" is interpreted as
72 "foo" followed by the expansion of the variable "bar". If value is true
73 or on, then "foo$bar" is a single seven-character name nad variable
74 expansions must be specified using braces or parentheses.
75 .pragma [=] includedir:value
77 If a relative pathname is specified in the .include directive, and the
79 OPENSSL_CONF_INCLUDE environment variable doesn't exist, then the value
80 of the includedir pragma, if it exists, is prepended to the pathname.
81 Settings
83 A configuration file is divided into a number of sections. A section
84 begins with the section name in square brackets, and ends when a new
85 section starts, or at the end of the file. The section name can
86 consist of alphanumeric characters and underscores. Whitespace between
87 the name and the brackets is removed.
88 The first section of a configuration file is special and is referred to
90 as the default section. This section is usually unnamed and spans from
91 the start of file until the first named section. When a name is being
92 looked up, it is first looked up in the current or named section, and
93 then the default section if necessary.
94 The environment is mapped onto a section called ENV.
96 Within a section are a series of name/value assignments, described in
98 more detail below. As a reminder, the square brackets shown in this
99 example are required, not optional:
100 [ section ]
102 name1 = This is value1
103 name2 = Another value
104 ...
105 [ newsection ]
106 name1 = New value1
107 name3 = Value 3
108 The name can contain any alphanumeric characters as well as a few
110 punctuation symbols such as . , ; and _. Whitespace after the name and
111 before the equal sign is ignored.
112 If a name is repeated in the same section, then all but the last value
114 are ignored. In certain circumstances, such as with Certificate DNs,
115 the same field may occur multiple times. In order to support this,
116 commands like openssl-req(1) ignore any leading text that is preceded
117 with a period. For example:
118 1.OU = First OU
120 2.OU = Second OU
121 The value consists of the string following the = character until end of
123 line with any leading and trailing whitespace removed.
124 The value string undergoes variable expansion. The text $var or
126 "${var}" inserts the value of the named variable from the current
127 section. To use a value from another section use $section::name or
128 "${section::name}". By using $ENV::name, the value of the specified
129 environment variable will be substituted.
130 Variables must be defined before their value is referenced, otherwise
132 an error is flagged and the file will not load. This can be worked
133 around by specifying a default value in the default section before the
134 variable is used.
135 Any name/value settings in an ENV section are available to the
137 configuration file, but are not propagated to the environment.
138 It is an error if the value ends up longer than 64k.
140 It is possible to escape certain characters by using a single ' or
142 double " quote around the value, or using a backslash \ before the
143 character, By making the last character of a line a \ a value string
144 can be spread across multiple lines. In addition the sequences \n, \r,
145 \b and \t are recognized.
146 The expansion and escape rules as described above that apply to value
148 also apply to the pathname of the .include directive.
149
151 The sections below use the informal term module to refer to a part of
152 the OpenSSL functionality. This is not the same as the formal term FIPS
153 module, for example.
154 The OpenSSL configuration looks up the value of openssl_conf in the
156 default section and takes that as the name of a section that specifies
157 how to configure any modules in the library. It is not an error to
158 leave any module in its default configuration. An application can
159 specify a different name by calling CONF_modules_load_file(), for
160 example, directly.
161 OpenSSL also looks up the value of config_diagnostics. If this exists
163 and has a nonzero numeric value, any error suppressing flags passed to
164 CONF_modules_load() will be ignored. This is useful for diagnosing
165 misconfigurations but its use in production requires additional
166 consideration. With this option enabled, a configuration error will
167 completely prevent access to a service. Without this option and in the
168 presence of a configuration error, access will be allowed but the
169 desired configuration will not be used.
170 # These must be in the default section
172 config_diagnostics = 1
173 openssl_conf = openssl_init
174 [openssl_init]
176 oid_section = oids
177 providers = providers
178 alg_section = evp_properties
179 ssl_conf = ssl_configuration
180 engines = engines
181 random = random
182 [oids]
184 ... new oids here ...
185 [providers]
187 ... provider stuff here ...
188 [evp_properties]
190 ... EVP properties here ...
191 [ssl_configuration]
193 ... SSL/TLS configuration properties here ...
194 [engines]
196 ... engine properties here ...
197 [random]
199 ... random properties here ...
200 The semantics of each module are described below. The phrase "in the
202 initialization section" refers to the section identified by the
203 openssl_conf or other name (given as openssl_init in the example
204 above). The examples below assume the configuration above is used to
205 specify the individual sections.
206 ASN.1 Object Identifier Configuration
208 The name oid_section in the initialization section names the section
209 containing name/value pairs of OID's. The name is the short name; the
210 value is an optional long name followed by a comma, and the numeric
211 value. While some OpenSSL commands have their own section for
212 specifying OID's, this section makes them available to all commands and
213 applications.
214 [oids]
216 shortName = a very long OID name, 1.2.3.4
217 newoid1 = 1.2.3.4.1
218 some_other_oid = 1.2.3.5
219 If a full configuration with the above fragment is in the file
221 example.cnf, then the following command line:
222 OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
224 will output:
226 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
228 showing that the OID "newoid1" has been added as "1.2.3.4.1".
230 Provider Configuration
232 The name providers in the initialization section names the section
233 containing cryptographic provider configuration. The name/value
234 assignments in this section each name a provider, and point to the
235 configuration section for that provider. The provider-specific section
236 is used to specify how to load the module, activate it, and set other
237 parameters.
238 Within a provider section, the following names have meaning:
240 identity
242 This is used to specify an alternate name, overriding the default
243 name specified in the list of providers. For example:
244 [providers]
246 foo = foo_provider
247 [foo_provider]
249 identity = my_fips_module
250 module
252 Specifies the pathname of the module (typically a shared library)
253 to load.
254 activate
256 If present, the module is activated. The value assigned to this
257 name is not significant.
258 All parameters in the section as well as sub-sections are made
260 available to the provider.
261 Loading the legacy provider
263 Uncomment the sections that start with ## in openssl.cnf to enable the
265 legacy provider. Note: In general it is not recommended to use the
266 above mentioned algorithms for security critical operations, as they
267 are cryptographically weak or vulnerable to side-channel attacks and as
268 such have been deprecated.
269 Default provider and its activation
271 If no providers are activated explicitly, the default one is activated
273 implicitly. See OSSL_PROVIDER-default(7) for more details.
274 If you add a section explicitly activating any other provider(s), you
276 most probably need to explicitly activate the default provider,
277 otherwise it becomes unavailable in openssl. It may make the system
278 remotely unavailable.
279 EVP Configuration
281 The name alg_section in the initialization section names the section
282 containing algorithmic properties when using the EVP API.
283 Within the algorithm properties section, the following names have
285 meaning:
286 default_properties
288 The value may be anything that is acceptable as a property query
289 string for EVP_set_default_properties().
290 rh-allow-sha1-signatures
292 The value is a boolean that can be yes or no. If the value is not
293 set, it behaves as if it was set to yes.
294 When set to no, any attempt to create or verify a signature with a
296 SHA1 digest will fail. To test whether your software will work
297 with future versions of OpenSSL, set this option to no. This
298 setting also affects TLS, where signature algorithms that use SHA1
299 as digest will no longer be supported if this option is set to no.
300 Because TLS 1.1 or lower use MD5-SHA1 as pseudorandom function
301 (PRF) to derive key material, disabling rh-allow-sha1-signatures
302 requires the use of TLS 1.2 or newer.
303 Note that enabling rh-allow-sha1-signatures will allow TLS
305 signature algorithms that use SHA1 in security level 1, despite the
306 definition of security level 1 of 80 bits of security, which SHA1
307 and MD5-SHA1 do not meet. This allows using SHA1 and MD5-SHA1 in
308 TLS in the LEGACY crypto-policy on Fedora without requiring to set
309 the security level to 0, which would include further insecure
310 algorithms, and thus restores support for TLS 1.0 and 1.1.
311 fips_mode (deprecated)
313 The value is a boolean that can be yes or no. If the value is yes,
314 this is exactly equivalent to:
315 default_properties = fips=yes
317 If the value is no, nothing happens. Using this name is deprecated,
319 and if used, it must be the only name in the section.
320 SSL Configuration
322 The name ssl_conf in the initialization section names the section
323 containing the list of SSL/TLS configurations. As with the providers,
324 each name in this section identifies a section with the configuration
325 for that name. For example:
326 [ssl_configuration]
328 server = server_tls_config
329 client = client_tls_config
330 system_default = tls_system_default
331 [server_tls_config]
333 ... configuration for SSL/TLS servers ...
334 [client_tls_config]
336 ... configuration for SSL/TLS clients ...
337 The configuration name system_default has a special meaning. If it
339 exists, it is applied whenever an SSL_CTX object is created. For
340 example, to impose system-wide minimum TLS and DTLS protocol versions:
341 [tls_system_default]
343 MinProtocol = TLSv1.2
344 MinProtocol = DTLSv1.2
345 The minimum TLS protocol is applied to SSL_CTX objects that are TLS-
347 based, and the minimum DTLS protocol to those are DTLS-based. The same
348 applies also to maximum versions set with MaxProtocol.
349 Each configuration section consists of name/value pairs that are parsed
351 by SSL_CONF_cmd(3), which will be called by SSL_CTX_config() or
352 SSL_config(), appropriately. Note that any characters before an
353 initial dot in the configuration section are ignored, so that the same
354 command can be used multiple times. This probably is most useful for
355 loading different key types, as shown here:
356 [server_tls_config]
358 RSA.Certificate = server-rsa.pem
359 ECDSA.Certificate = server-ecdsa.pem
360 Engine Configuration
362 The name engines in the initialization section names the section
363 containing the list of ENGINE configurations. As with the providers,
364 each name in this section identifies an engine with the configuration
365 for that engine. The engine-specific section is used to specify how to
366 load the engine, activate it, and set other parameters.
367 Within an engine section, the following names have meaning:
369 engine_id
371 This is used to specify an alternate name, overriding the default
372 name specified in the list of engines. If present, it must be
373 first. For example:
374 [engines]
376 foo = foo_engine
377 [foo_engine]
379 engine_id = myfoo
380 dynamic_path
382 This loads and adds an ENGINE from the given path. It is equivalent
383 to sending the ctrls SO_PATH with the path argument followed by
384 LIST_ADD with value 2 and LOAD to the dynamic ENGINE. If this is
385 not the required behaviour then alternative ctrls can be sent
386 directly to the dynamic ENGINE using ctrl commands.
387 init
389 This specifies whether to initialize the ENGINE. If the value is 0
390 the ENGINE will not be initialized, if the value is 1 an attempt is
391 made to initialize the ENGINE immediately. If the init command is
392 not present then an attempt will be made to initialize the ENGINE
393 after all commands in its section have been processed.
394 default_algorithms
396 This sets the default algorithms an ENGINE will supply using the
397 function ENGINE_set_default_string().
398 All other names are taken to be the name of a ctrl command that is sent
400 to the ENGINE, and the value is the argument passed with the command.
401 The special value EMPTY means no value is sent with the command. For
402 example:
403 [engines]
405 foo = foo_engine
406 [foo_engine]
408 dynamic_path = /some/path/fooengine.so
409 some_ctrl = some_value
410 default_algorithms = ALL
411 other_ctrl = EMPTY
412 Random Configuration
414 The name random in the initialization section names the section
415 containing the random number generater settings.
416 Within the random section, the following names have meaning:
418 random
420 This is used to specify the random bit generator. For example:
421 [random]
423 random = CTR-DRBG
424 The available random bit generators are:
426 CTR-DRBG
428 HASH-DRBG
429 HMAC-DRBG
430 cipher
431 This specifies what cipher a CTR-DRBG random bit generator will
432 use. Other random bit generators ignore this name. The default
433 value is AES-256-CTR.
434 digest
436 This specifies what digest the HASH-DRBG or HMAC-DRBG random bit
437 generators will use. Other random bit generators ignore this name.
438 properties
440 This sets the property query used when fetching the random bit
441 generator and any underlying algorithms.
442 seed
444 This sets the randomness source that should be used. By default
445 SEED-SRC will be used outside of the FIPS provider. The FIPS
446 provider uses call backs to access the same randomness sources from
447 outside the validated boundary.
448 seed_properties
450 This sets the property query used when fetching the randomness
451 source.
452
454 This example shows how to use quoting and escaping.
455 # This is the default section.
457 HOME = /temp
458 configdir = $ENV::HOME/config
459 [ section_one ]
461 # Quotes permit leading and trailing whitespace
462 any = " any variable name "
463 other = A string that can \
464 cover several lines \
465 by including \\ characters
466 message = Hello World\n
467 [ section_two ]
469 greeting = $section_one::message
470 This example shows how to expand environment variables safely. In this
472 example, the variable tempfile is intended to refer to a temporary
473 file, and the environment variable TEMP or TMP, if present, specify the
474 directory where the file should be put. Since the default section is
475 checked if a variable does not exist, it is possible to set TMP to
476 default to /tmp, and TEMP to default to TMP.
477 # These two lines must be in the default section.
479 TMP = /tmp
480 TEMP = $ENV::TMP
481 # This can be used anywhere
483 tmpfile = ${ENV::TEMP}/tmp.filename
484 This example shows how to enforce FIPS mode for the application sample.
486 sample = fips_config
488 [fips_config]
490 alg_section = evp_properties
491 [evp_properties]
493 default_properties = "fips=yes"
494
496 OPENSSL_CONF
497 The path to the config file, or the empty string for none. Ignored
498 in set-user-ID and set-group-ID programs.
499 OPENSSL_ENGINES
501 The path to the engines directory. Ignored in set-user-ID and set-
502 group-ID programs.
503 OPENSSL_MODULES
505 The path to the directory with OpenSSL modules, such as providers.
506 Ignored in set-user-ID and set-group-ID programs.
507 OPENSSL_CONF_INCLUDE
509 The optional path to prepend to all .include paths.
510
512 There is no way to include characters using the octal \nnn form.
513 Strings are all null terminated so nulls cannot form part of the value.
514 The escaping isn't quite right: if you want to use sequences like \n
516 you can't use any quote escaping on the same line.
517 The limit that only one directory can be opened and read at a time can
519 be considered a bug and should be fixed.
520
522 An undocumented API, NCONF_WIN32(), used a slightly different set of
523 parsing rules there were intended to be tailored to the Microsoft
524 Windows platform. Specifically, the backslash character was not an
525 escape character and could be used in pathnames, only the double-quote
526 character was recognized, and comments began with a semi-colon. This
527 function was deprecated in OpenSSL 3.0; applications with configuration
528 files using that syntax will have to be modified.
529
531 openssl-x509(1), openssl-req(1), openssl-ca(1), openssl-fipsinstall(1),
532 ASN1_generate_nconf(3), EVP_set_default_properties(3),
533 CONF_modules_load(3), CONF_modules_load_file(3), fips_config(5), and
534 x509v3_config(5).
535
537 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
538 Licensed under the Apache License 2.0 (the "License"). You may not use
540 this file except in compliance with the License. You can obtain a copy
541 in the file LICENSE in the source distribution or at
542 <https://www.openssl.org/source/license.html>.
5433.0.5 2022-07-05 CONFIG(5ossl)