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