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