5 config - OpenSSL CONF library configuration files
9 This page documents the syntax of OpenSSL configuration files,
10 as parsed by L<NCONF_load(3)> and related functions.
11 This format is used by many of the OpenSSL commands, and to
12 initialize the libraries when used by any application.
14 The first part describes the general syntax of the configuration
15 files, and subsequent sections describe the semantics of individual
16 modules. Other modules are described in L<fips_config(5)> and
18 The syntax for defining ASN.1 values is described in
19 L<ASN1_generate_nconf(3)>.
23 A configuration file is a series of lines. Blank lines, and whitespace
24 between the elements of a line, have no significance. A comment starts
25 with a B<#> character; the rest of the line is ignored. If the B<#>
26 is the first non-space character in a line, the entire line is ignored.
30 Two directives can be used to control the parsing of configuration files:
31 B<.include> and B<.pragma>.
33 For compatibility with older versions of OpenSSL, an equal sign after the
34 directive will be ignored. Older versions will treat it as an assignment,
35 so care should be taken if the difference in semantics is important.
37 A file can include other files using the include syntax:
41 If B<pathname> is a simple filename, that file is included directly at
42 that point. Included files can have B<.include> statements that specify
43 other files. If B<pathname> is a directory, all files within that directory
44 that have a C<.cnf> or C<.conf> extension will be included. (This is only
45 available on systems with POSIX IO support.) Any sub-directories found
46 inside the B<pathname> are B<ignored>. Similarly, if a file is opened
47 while scanning a directory, and that file has an B<.include> directive
48 that specifies a directory, that is also ignored.
50 As a general rule, the B<pathname> should be an absolute path; this can
51 be enforced with the B<abspath> and B<includedir> pragmas, described below.
52 The environment variable B<OPENSSL_CONF_INCLUDE>, if it exists,
53 is prepended to all relative pathnames.
54 If the pathname is still relative, it is interpreted based on the
55 current working directory.
57 To require all file inclusions to name absolute paths, use the following
60 .pragma [=] abspath:value
62 The default behavior, where the B<value> is B<false> or B<off>, is to allow
63 relative paths. To require all B<.include> pathnames to be absolute paths,
64 use a B<value> of B<true> or B<on>.
66 In these files, the dollar sign, B<$>, is used to reference a variable, as
67 described below. On some platforms, however, it is common to treat B<$>
68 as a regular character in symbol names. Supporting this behavior can be
69 done with the following directive:
71 .pragma [=] dollarid:value
73 The default behavior, where the B<value> is B<false> or B<off>, is to treat
74 the dollarsign as indicating a variable name; C<foo$bar> is interpreted as
75 C<foo> followed by the expansion of the variable C<bar>. If B<value> is
76 B<true> or B<on>, then C<foo$bar> is a single seven-character name and
77 variable expansions must be specified using braces or parentheses.
79 .pragma [=] includedir:value
81 If a relative pathname is specified in the B<.include> directive, and
82 the B<OPENSSL_CONF_INCLUDE> environment variable doesn't exist, then
83 the value of the B<includedir> pragma, if it exists, is prepended to the
88 A configuration file is divided into a number of I<sections>. A section
89 begins with the section name in square brackets, and ends when a new
90 section starts, or at the end of the file. The section name can consist
91 of alphanumeric characters and underscores.
92 Whitespace between the name and the brackets is removed.
94 The first section of a configuration file is special and is referred to
95 as the B<default> section. This section is usually unnamed and spans from
96 the start of file until the first named section. When a name is being
97 looked up, it is first looked up in the current or named section,
98 and then the default section if necessary.
100 The environment is mapped onto a section called B<ENV>.
102 Within a section are a series of name/value assignments, described in more
103 detail below. As a reminder, the square brackets shown in this example
104 are required, not optional:
107 name1 = This is value1
108 name2 = Another value
114 The B<name> can contain any alphanumeric characters as well as a few
115 punctuation symbols such as B<.> B<,> B<;> and B<_>.
116 Whitespace after the name and before the equal sign is ignored.
118 If a name is repeated in the same section, then all but the last
119 value are ignored. In certain circumstances, such as with
120 Certificate DNs, the same field may occur multiple times.
121 In order to support this, commands like L<openssl-req(1)> ignore any
122 leading text that is preceded with a period. For example:
127 The B<value> consists of the string following the B<=> character until end
128 of line with any leading and trailing whitespace removed.
130 The value string undergoes variable expansion. The text C<$var> or C<${var}>
131 inserts the value of the named variable from the current section.
132 To use a value from another section use C<$section::name>
133 or C<${section::name}>.
134 By using C<$ENV::name>, the value of the specified environment
135 variable will be substituted.
137 Variables must be defined before their value is referenced, otherwise
138 an error is flagged and the file will not load.
139 This can be worked around by specifying a default value in the B<default>
140 section before the variable is used.
142 Any name/value settings in an B<ENV> section are available
143 to the configuration file, but are not propagated to the environment.
145 It is an error if the value ends up longer than 64k.
147 It is possible to escape certain characters by using a single B<'> or
148 double B<"> quote around the value, or using a backslash B<\> before the
150 By making the last character of a line a B<\>
151 a B<value> string can be spread across multiple lines. In addition
152 the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
154 The expansion and escape rules as described above that apply to B<value>
155 also apply to the pathname of the B<.include> directive.
157 =head1 OPENSSL LIBRARY CONFIGURATION
159 The sections below use the informal term I<module> to refer to a part
160 of the OpenSSL functionality. This is not the same as the formal term
161 I<FIPS module>, for example.
163 The OpenSSL configuration looks up the value of B<openssl_conf>
164 in the default section and takes that as the name of a section that specifies
165 how to configure any modules in the library. It is not an error to leave
166 any module in its default configuration. An application can specify a
167 different name by calling CONF_modules_load_file(), for example, directly.
169 OpenSSL also looks up the value of B<config_diagnostics>.
170 If this exists and has a nonzero numeric value, any error suppressing flags
171 passed to CONF_modules_load() will be ignored.
172 This is useful for diagnosing misconfigurations but its use in
173 production requires additional consideration. With this option enabled,
174 a configuration error will completely prevent access to a service.
175 Without this option and in the presence of a configuration error, access
176 will be allowed but the desired configuration will B<not> be used.
178 # These must be in the default section
179 config_diagnostics = 1
180 openssl_conf = openssl_init
184 providers = providers
185 alg_section = evp_properties
186 ssl_conf = ssl_configuration
191 ... new oids here ...
194 ... provider stuff here ...
197 ... EVP properties here ...
200 ... SSL/TLS configuration properties here ...
203 ... engine properties here ...
206 ... random properties here ...
208 The semantics of each module are described below. The phrase "in the
209 initialization section" refers to the section identified by the
210 B<openssl_conf> or other name (given as B<openssl_init> in the
211 example above). The examples below assume the configuration above
212 is used to specify the individual sections.
214 =head2 ASN.1 Object Identifier Configuration
216 The name B<oid_section> in the initialization section names the section
217 containing name/value pairs of OID's.
218 The name is the short name; the value is an optional long name followed
219 by a comma, and the numeric value.
220 While some OpenSSL commands have their own section for specifying OID's,
221 this section makes them available to all commands and applications.
224 shortName = a very long OID name, 1.2.3.4
226 some_other_oid = 1.2.3.5
228 If a full configuration with the above fragment is in the file
229 F<example.cnf>, then the following command line:
231 OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
235 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
237 showing that the OID "newoid1" has been added as "1.2.3.4.1".
239 =head2 Provider Configuration
241 The name B<providers> in the initialization section names the section
242 containing cryptographic provider configuration. The name/value assignments
243 in this section each name a provider, and point to the configuration section
244 for that provider. The provider-specific section is used to specify how
245 to load the module, activate it, and set other parameters.
247 Within a provider section, the following names have meaning:
253 This is used to specify an alternate name, overriding the default name
254 specified in the list of providers. For example:
260 identity = my_fips_module
264 Specifies the pathname of the module (typically a shared library) to load.
268 If present and set to one of the values yes, on, true or 1, then the associated
269 provider will be activated. Conversely, setting this value to no, off, false, or
270 0 will prevent the provider from being activated. Settings can be given in lower
271 or uppercase. Setting activate to any other setting, or omitting a setting
272 value will result in an error.
276 If enabled, informs the library to clear the error stack on failure to activate
277 requested provider. A value of 1, yes, true or on (in lower or uppercase) will
278 activate this setting, while a value of 0, no, false, of off (again in lower or
279 uppercase) will disable this setting. Any other value will produce an error.
280 Note this setting defaults to off if not provided
284 All parameters in the section as well as sub-sections are made
285 available to the provider.
287 =head3 Default provider and its activation
289 If no providers are activated explicitly, the default one is activated implicitly.
290 See L<OSSL_PROVIDER-default(7)> for more details.
292 If you add a section explicitly activating any other provider(s),
293 you most probably need to explicitly activate the default provider,
294 otherwise it becomes unavailable in openssl. It may make the system remotely unavailable.
296 =head2 EVP Configuration
298 The name B<alg_section> in the initialization section names the section
299 containing algorithmic properties when using the B<EVP> API.
301 Within the algorithm properties section, the following names have meaning:
305 =item B<default_properties>
307 The value may be anything that is acceptable as a property query
308 string for EVP_set_default_properties().
310 =item B<fips_mode> (deprecated)
312 The value is a boolean that can be B<yes> or B<no>. If the value is
313 B<yes>, this is exactly equivalent to:
315 default_properties = fips=yes
317 If the value is B<no>, nothing happens. Using this name is deprecated, and
318 if used, it must be the only name in the section.
322 =head2 SSL Configuration
324 The name B<ssl_conf> in the initialization section names the section
325 containing the list of SSL/TLS configurations.
326 As with the providers, each name in this section identifies a
327 section with the configuration for that name. For example:
330 server = server_tls_config
331 client = client_tls_config
332 system_default = tls_system_default
335 ... configuration for SSL/TLS servers ...
338 ... configuration for SSL/TLS clients ...
340 The configuration name B<system_default> has a special meaning. If it
341 exists, it is applied whenever an B<SSL_CTX> object is created. For example,
342 to impose system-wide minimum TLS and DTLS protocol versions:
345 MinProtocol = TLSv1.2
346 MinProtocol = DTLSv1.2
348 The minimum TLS protocol is applied to B<SSL_CTX> objects that are TLS-based,
349 and the minimum DTLS protocol to those are DTLS-based.
350 The same applies also to maximum versions set with B<MaxProtocol>.
352 Each configuration section consists of name/value pairs that are parsed
353 by B<SSL_CONF_cmd(3)>, which will be called by SSL_CTX_config() or
354 SSL_config(), appropriately. Note that any characters before an initial
355 dot in the configuration section are ignored, so that the same command can
356 be used multiple times. This probably is most useful for loading different
357 key types, as shown here:
360 RSA.Certificate = server-rsa.pem
361 ECDSA.Certificate = server-ecdsa.pem
363 =head2 Engine Configuration
365 The name B<engines> in the initialization section names the section
366 containing the list of ENGINE configurations.
367 As with the providers, each name in this section identifies an engine
368 with the configuration for that engine.
369 The engine-specific section is used to specify how to load the engine,
370 activate it, and set other parameters.
372 Within an engine section, the following names have meaning:
378 This is used to specify an alternate name, overriding the default name
379 specified in the list of engines. If present, it must be first.
388 =item B<dynamic_path>
390 This loads and adds an ENGINE from the given path. It is equivalent to
391 sending the ctrls B<SO_PATH> with the path argument followed by B<LIST_ADD>
392 with value B<2> and B<LOAD> to the dynamic ENGINE. If this is not the
393 required behaviour then alternative ctrls can be sent directly to the
394 dynamic ENGINE using ctrl commands.
398 This specifies whether to initialize the ENGINE. If the value is B<0> the
399 ENGINE will not be initialized, if the value is B<1> an attempt is made
401 the ENGINE immediately. If the B<init> command is not present then an
402 attempt will be made to initialize the ENGINE after all commands in its
403 section have been processed.
405 =item B<default_algorithms>
407 This sets the default algorithms an ENGINE will supply using the function
408 ENGINE_set_default_string().
412 All other names are taken to be the name of a ctrl command that is
413 sent to the ENGINE, and the value is the argument passed with the command.
414 The special value B<EMPTY> means no value is sent with the command.
421 dynamic_path = /some/path/fooengine.so
422 some_ctrl = some_value
423 default_algorithms = ALL
426 =head2 Random Configuration
428 The name B<random> in the initialization section names the section
429 containing the random number generator settings.
431 Within the random section, the following names have meaning:
437 This is used to specify the random bit generator.
443 The available random bit generators are:
457 This specifies what cipher a B<CTR-DRBG> random bit generator will use.
458 Other random bit generators ignore this name.
459 The default value is B<AES-256-CTR>.
463 This specifies what digest the B<HASH-DRBG> or B<HMAC-DRBG> random bit
464 generators will use. Other random bit generators ignore this name.
468 This sets the property query used when fetching the random bit generator and
469 any underlying algorithms.
473 This sets the randomness source that should be used. By default B<SEED-SRC>
474 will be used outside of the FIPS provider. The FIPS provider uses call backs
475 to access the same randomness sources from outside the validated boundary.
477 =item B<seed_properties>
479 This sets the property query used when fetching the randomness source.
485 This example shows how to use quoting and escaping.
487 # This is the default section.
489 configdir = $ENV::HOME/config
492 # Quotes permit leading and trailing whitespace
493 any = " any variable name "
494 other = A string that can \
495 cover several lines \
496 by including \\ characters
497 message = Hello World\n
500 greeting = $section_one::message
502 This example shows how to expand environment variables safely.
503 In this example, the variable B<tempfile> is intended to refer
504 to a temporary file, and the environment variable B<TEMP> or
505 B<TMP>, if present, specify the directory where the file
507 Since the default section is checked if a variable does not
508 exist, it is possible to set B<TMP> to default to F</tmp>, and
509 B<TEMP> to default to B<TMP>.
511 # These two lines must be in the default section.
515 # This can be used anywhere
516 tmpfile = ${ENV::TEMP}/tmp.filename
518 This example shows how to enforce FIPS mode for the application
524 alg_section = evp_properties
527 default_properties = "fips=yes"
533 =item B<OPENSSL_CONF>
535 The path to the config file, or the empty string for none.
536 Ignored in set-user-ID and set-group-ID programs.
538 =item B<OPENSSL_ENGINES>
540 The path to the engines directory.
541 Ignored in set-user-ID and set-group-ID programs.
543 =item B<OPENSSL_MODULES>
545 The path to the directory with OpenSSL modules, such as providers.
546 Ignored in set-user-ID and set-group-ID programs.
548 =item B<OPENSSL_CONF_INCLUDE>
550 The optional path to prepend to all B<.include> paths.
556 There is no way to include characters using the octal B<\nnn> form. Strings
557 are all null terminated so nulls cannot form part of the value.
559 The escaping isn't quite right: if you want to use sequences like B<\n>
560 you can't use any quote escaping on the same line.
562 The limit that only one directory can be opened and read at a time
563 can be considered a bug and should be fixed.
567 An undocumented API, NCONF_WIN32(), used a slightly different set
568 of parsing rules there were intended to be tailored to
569 the Microsoft Windows platform.
570 Specifically, the backslash character was not an escape character and
571 could be used in pathnames, only the double-quote character was recognized,
572 and comments began with a semi-colon.
573 This function was deprecated in OpenSSL 3.0; applications with
574 configuration files using that syntax will have to be modified.
578 L<openssl-x509(1)>, L<openssl-req(1)>, L<openssl-ca(1)>,
579 L<openssl-fipsinstall(1)>,
580 L<ASN1_generate_nconf(3)>,
581 L<EVP_set_default_properties(3)>,
582 L<CONF_modules_load(3)>,
583 L<CONF_modules_load_file(3)>,
584 L<fips_config(5)>, and
589 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
591 Licensed under the Apache License 2.0 (the "License"). You may not use
592 this file except in compliance with the License. You can obtain a copy
593 in the file LICENSE in the source distribution or at
594 L<https://www.openssl.org/source/license.html>.