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 and set to one of the values yes, on, true or 1, then the associated 269provider will be activated. Conversely, setting this value to no, off, false, or 2700 will prevent the provider from being activated. Settings can be given in lower 271or uppercase. Setting activate to any other setting, or omitting a setting 272value will result in an error. 273 274= item B<soft_load> 275 276If enabled, informs the library to clear the error stack on failure to activate 277requested provider. A value of 1, yes, true or on (in lower or uppercase) will 278activate this setting, while a value of 0, no, false, of off (again in lower or 279uppercase) will disable this setting. Any other value will produce an error. 280Note this setting defaults to off if not provided 281 282=back 283 284All parameters in the section as well as sub-sections are made 285available to the provider. 286 287=head3 Default provider and its activation 288 289If no providers are activated explicitly, the default one is activated implicitly. 290See L<OSSL_PROVIDER-default(7)> for more details. 291 292If you add a section explicitly activating any other provider(s), 293you most probably need to explicitly activate the default provider, 294otherwise it becomes unavailable in openssl. It may make the system remotely unavailable. 295 296=head2 EVP Configuration 297 298The name B<alg_section> in the initialization section names the section 299containing algorithmic properties when using the B<EVP> API. 300 301Within the algorithm properties section, the following names have meaning: 302 303=over 4 304 305=item B<default_properties> 306 307The value may be anything that is acceptable as a property query 308string for EVP_set_default_properties(). 309 310=item B<fips_mode> (deprecated) 311 312The value is a boolean that can be B<yes> or B<no>. If the value is 313B<yes>, this is exactly equivalent to: 314 315 default_properties = fips=yes 316 317If the value is B<no>, nothing happens. Using this name is deprecated, and 318if used, it must be the only name in the section. 319 320=back 321 322=head2 SSL Configuration 323 324The name B<ssl_conf> in the initialization section names the section 325containing the list of SSL/TLS configurations. 326As with the providers, each name in this section identifies a 327section with the configuration for that name. For example: 328 329 [ssl_configuration] 330 server = server_tls_config 331 client = client_tls_config 332 system_default = tls_system_default 333 334 [server_tls_config] 335 ... configuration for SSL/TLS servers ... 336 337 [client_tls_config] 338 ... configuration for SSL/TLS clients ... 339 340The configuration name B<system_default> has a special meaning. If it 341exists, it is applied whenever an B<SSL_CTX> object is created. For example, 342to impose system-wide minimum TLS and DTLS protocol versions: 343 344 [tls_system_default] 345 MinProtocol = TLSv1.2 346 MinProtocol = DTLSv1.2 347 348The minimum TLS protocol is applied to B<SSL_CTX> objects that are TLS-based, 349and the minimum DTLS protocol to those are DTLS-based. 350The same applies also to maximum versions set with B<MaxProtocol>. 351 352Each configuration section consists of name/value pairs that are parsed 353by B<SSL_CONF_cmd(3)>, which will be called by SSL_CTX_config() or 354SSL_config(), appropriately. Note that any characters before an initial 355dot in the configuration section are ignored, so that the same command can 356be used multiple times. This probably is most useful for loading different 357key types, as shown here: 358 359 [server_tls_config] 360 RSA.Certificate = server-rsa.pem 361 ECDSA.Certificate = server-ecdsa.pem 362 363=head2 Engine Configuration 364 365The name B<engines> in the initialization section names the section 366containing the list of ENGINE configurations. 367As with the providers, each name in this section identifies an engine 368with the configuration for that engine. 369The engine-specific section is used to specify how to load the engine, 370activate it, and set other parameters. 371 372Within an engine section, the following names have meaning: 373 374=over 4 375 376=item B<engine_id> 377 378This is used to specify an alternate name, overriding the default name 379specified in the list of engines. If present, it must be first. 380For example: 381 382 [engines] 383 foo = foo_engine 384 385 [foo_engine] 386 engine_id = myfoo 387 388=item B<dynamic_path> 389 390This loads and adds an ENGINE from the given path. It is equivalent to 391sending the ctrls B<SO_PATH> with the path argument followed by B<LIST_ADD> 392with value B<2> and B<LOAD> to the dynamic ENGINE. If this is not the 393required behaviour then alternative ctrls can be sent directly to the 394dynamic ENGINE using ctrl commands. 395 396=item B<init> 397 398This specifies whether to initialize the ENGINE. If the value is B<0> the 399ENGINE will not be initialized, if the value is B<1> an attempt is made 400to initialize 401the ENGINE immediately. If the B<init> command is not present then an 402attempt will be made to initialize the ENGINE after all commands in its 403section have been processed. 404 405=item B<default_algorithms> 406 407This sets the default algorithms an ENGINE will supply using the function 408ENGINE_set_default_string(). 409 410=back 411 412All other names are taken to be the name of a ctrl command that is 413sent to the ENGINE, and the value is the argument passed with the command. 414The special value B<EMPTY> means no value is sent with the command. 415For example: 416 417 [engines] 418 foo = foo_engine 419 420 [foo_engine] 421 dynamic_path = /some/path/fooengine.so 422 some_ctrl = some_value 423 default_algorithms = ALL 424 other_ctrl = EMPTY 425 426=head2 Random Configuration 427 428The name B<random> in the initialization section names the section 429containing the random number generator settings. 430 431Within the random section, the following names have meaning: 432 433=over 4 434 435=item B<random> 436 437This is used to specify the random bit generator. 438For example: 439 440 [random] 441 random = CTR-DRBG 442 443The available random bit generators are: 444 445=over 4 446 447=item B<CTR-DRBG> 448 449=item B<HASH-DRBG> 450 451=item B<HMAC-DRBG> 452 453=back 454 455=item B<cipher> 456 457This specifies what cipher a B<CTR-DRBG> random bit generator will use. 458Other random bit generators ignore this name. 459The default value is B<AES-256-CTR>. 460 461=item B<digest> 462 463This specifies what digest the B<HASH-DRBG> or B<HMAC-DRBG> random bit 464generators will use. Other random bit generators ignore this name. 465 466=item B<properties> 467 468This sets the property query used when fetching the random bit generator and 469any underlying algorithms. 470 471=item B<seed> 472 473This sets the randomness source that should be used. By default B<SEED-SRC> 474will be used outside of the FIPS provider. The FIPS provider uses call backs 475to access the same randomness sources from outside the validated boundary. 476 477=item B<seed_properties> 478 479This sets the property query used when fetching the randomness source. 480 481=back 482 483=head1 EXAMPLES 484 485This example shows how to use quoting and escaping. 486 487 # This is the default section. 488 HOME = /temp 489 configdir = $ENV::HOME/config 490 491 [ section_one ] 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 498 499 [ section_two ] 500 greeting = $section_one::message 501 502This example shows how to expand environment variables safely. 503In this example, the variable B<tempfile> is intended to refer 504to a temporary file, and the environment variable B<TEMP> or 505B<TMP>, if present, specify the directory where the file 506should be put. 507Since the default section is checked if a variable does not 508exist, it is possible to set B<TMP> to default to F</tmp>, and 509B<TEMP> to default to B<TMP>. 510 511 # These two lines must be in the default section. 512 TMP = /tmp 513 TEMP = $ENV::TMP 514 515 # This can be used anywhere 516 tmpfile = ${ENV::TEMP}/tmp.filename 517 518This example shows how to enforce FIPS mode for the application 519F<sample>. 520 521 sample = fips_config 522 523 [fips_config] 524 alg_section = evp_properties 525 526 [evp_properties] 527 default_properties = "fips=yes" 528 529=head1 ENVIRONMENT 530 531=over 4 532 533=item B<OPENSSL_CONF> 534 535The path to the config file, or the empty string for none. 536Ignored in set-user-ID and set-group-ID programs. 537 538=item B<OPENSSL_ENGINES> 539 540The path to the engines directory. 541Ignored in set-user-ID and set-group-ID programs. 542 543=item B<OPENSSL_MODULES> 544 545The path to the directory with OpenSSL modules, such as providers. 546Ignored in set-user-ID and set-group-ID programs. 547 548=item B<OPENSSL_CONF_INCLUDE> 549 550The optional path to prepend to all B<.include> paths. 551 552=back 553 554=head1 BUGS 555 556There is no way to include characters using the octal B<\nnn> form. Strings 557are all null terminated so nulls cannot form part of the value. 558 559The escaping isn't quite right: if you want to use sequences like B<\n> 560you can't use any quote escaping on the same line. 561 562The limit that only one directory can be opened and read at a time 563can be considered a bug and should be fixed. 564 565=head1 HISTORY 566 567An undocumented API, NCONF_WIN32(), used a slightly different set 568of parsing rules there were intended to be tailored to 569the Microsoft Windows platform. 570Specifically, the backslash character was not an escape character and 571could be used in pathnames, only the double-quote character was recognized, 572and comments began with a semi-colon. 573This function was deprecated in OpenSSL 3.0; applications with 574configuration files using that syntax will have to be modified. 575 576=head1 SEE ALSO 577 578L<openssl-x509(1)>, L<openssl-req(1)>, L<openssl-ca(1)>, 579L<openssl-fipsinstall(1)>, 580L<ASN1_generate_nconf(3)>, 581L<EVP_set_default_properties(3)>, 582L<CONF_modules_load(3)>, 583L<CONF_modules_load_file(3)>, 584L<fips_config(5)>, and 585L<x509v3_config(5)>. 586 587=head1 COPYRIGHT 588 589Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 590 591Licensed under the Apache License 2.0 (the "License"). You may not use 592this file except in compliance with the License. You can obtain a copy 593in the file LICENSE in the source distribution or at 594L<https://www.openssl.org/source/license.html>. 595 596=cut 597