config.pod revision 280304
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 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 280=head1 BUGS 281 282Currently there is no way to include characters using the octal B<\nnn> 283form. Strings are all null terminated so nulls cannot form part of 284the value. 285 286The escaping isn't quite right: if you want to use sequences like B<\n> 287you can't use any quote escaping on the same line. 288 289Files are loaded in a single pass. This means that an variable expansion 290will only work if the variables referenced are defined earlier in the 291file. 292 293=head1 SEE ALSO 294 295L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)> 296 297=cut 298