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 92Currently there are two configuration modules. One for ASN1 objects another 93for ENGINE configuration. 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 informations 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=head1 NOTES 195 196If a configuration file attempts to expand a variable that doesn't exist 197then an error is flagged and the file will not load. This can happen 198if an attempt is made to expand an environment variable that doesn't 199exist. For example in a previous version of OpenSSL the default OpenSSL 200master configuration file used the value of B<HOME> which may not be 201defined on non Unix systems and would cause an error. 202 203This can be worked around by including a B<default> section to provide 204a default value: then if the environment lookup fails the default value 205will be used instead. For this to work properly the default value must 206be defined earlier in the configuration file than the expansion. See 207the B<EXAMPLES> section for an example of how to do this. 208 209If the same variable exists in the same section then all but the last 210value will be silently ignored. In certain circumstances such as with 211DNs the same field may occur multiple times. This is usually worked 212around by ignoring any characters before an initial B<.> e.g. 213 214 1.OU="My first OU" 215 2.OU="My Second OU" 216 217=head1 EXAMPLES 218 219Here is a sample configuration file using some of the features 220mentioned above. 221 222 # This is the default section. 223 224 HOME=/temp 225 RANDFILE= ${ENV::HOME}/.rnd 226 configdir=$ENV::HOME/config 227 228 [ section_one ] 229 230 # We are now in section one. 231 232 # Quotes permit leading and trailing whitespace 233 any = " any variable name " 234 235 other = A string that can \ 236 cover several lines \ 237 by including \\ characters 238 239 message = Hello World\n 240 241 [ section_two ] 242 243 greeting = $section_one::message 244 245This next example shows how to expand environment variables safely. 246 247Suppose you want a variable called B<tmpfile> to refer to a 248temporary filename. The directory it is placed in can determined by 249the the B<TEMP> or B<TMP> environment variables but they may not be 250set to any value at all. If you just include the environment variable 251names and the variable doesn't exist then this will cause an error when 252an attempt is made to load the configuration file. By making use of the 253default section both values can be looked up with B<TEMP> taking 254priority and B</tmp> used if neither is defined: 255 256 TMP=/tmp 257 # The above value is used if TMP isn't in the environment 258 TEMP=$ENV::TMP 259 # The above value is used if TEMP isn't in the environment 260 tmpfile=${ENV::TEMP}/tmp.filename 261 262=head1 BUGS 263 264Currently there is no way to include characters using the octal B<\nnn> 265form. Strings are all null terminated so nulls cannot form part of 266the value. 267 268The escaping isn't quite right: if you want to use sequences like B<\n> 269you can't use any quote escaping on the same line. 270 271Files are loaded in a single pass. This means that an variable expansion 272will only work if the variables referenced are defined earlier in the 273file. 274 275=head1 SEE ALSO 276 277L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)> 278 279=cut 280