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