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