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