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