config.pod revision 160814
1154941Sjhb 2154941Sjhb=pod 3154941Sjhb 4154941Sjhb=for comment openssl_manual_section:5 5154941Sjhb 6154941Sjhb=head1 NAME 7154941Sjhb 8154941Sjhbconfig - OpenSSL CONF library configuration files 9154941Sjhb 10154941Sjhb=head1 DESCRIPTION 11154941Sjhb 12154941SjhbThe OpenSSL CONF library can be used to read configuration files. 13154941SjhbIt is used for the OpenSSL master configuration file B<openssl.cnf> 14154941Sjhband in a few other places like B<SPKAC> files and certificate extension 15154941Sjhbfiles for the B<x509> utility. OpenSSL applications can also use the 16154941SjhbCONF library for their own purposes. 17154941Sjhb 18154941SjhbA configuration file is divided into a number of sections. Each section 19154941Sjhbstarts with a line B<[ section_name ]> and ends when a new section is 20154941Sjhbstarted or end of file is reached. A section name can consist of 21154941Sjhbalphanumeric characters and underscores. 22154941Sjhb 23154941SjhbThe first section of a configuration file is special and is referred 24154941Sjhbto as the B<default> section this is usually unnamed and is from the 25154941Sjhbstart of file until the first named section. When a name is being looked up 26154941Sjhbit is first looked up in a named section (if any) and then the 27154941Sjhbdefault section. 28154941Sjhb 29154941SjhbThe environment is mapped onto a section called B<ENV>. 30154941Sjhb 31154941SjhbComments can be included by preceding them with the B<#> character 32154941Sjhb 33154941SjhbEach section in a configuration file consists of a number of name and 34154941Sjhbvalue pairs of the form B<name=value> 35154941Sjhb 36154941SjhbThe B<name> string can contain any alphanumeric characters as well as 37154941Sjhba few punctuation symbols such as B<.> B<,> B<;> and B<_>. 38167801Sjhb 39154941SjhbThe B<value> string consists of the string following the B<=> character 40154941Sjhbuntil end of line with any leading and trailing white space removed. 41154941Sjhb 42177912SjeffThe value string undergoes variable expansion. This can be done by 43154941Sjhbincluding the form B<$var> or B<${var}>: this will substitute the value 44154941Sjhbof the named variable in the current section. It is also possible to 45154941Sjhbsubstitute a value from another section using the syntax B<$section::name> 46154941Sjhbor B<${section::name}>. By using the form B<$ENV::name> environment 47177912Sjeffvariables can be substituted. It is also possible to assign values to 48154941Sjhbenvironment variables by using the name B<ENV::name>, this will work 49154941Sjhbif the program looks up environment variables using the B<CONF> library 50171516Sattilioinstead of calling B<getenv()> directly. 51154941Sjhb 52154941SjhbIt is possible to escape certain characters by using any kind of quote 53171052Sattilioor the B<\> character. By making the last character of a line a B<\> 54171052Sattilioa B<value> string can be spread across multiple lines. In addition 55167801Sjhbthe sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. 56167801Sjhb 57167801Sjhb=head1 OPENSSL LIBRARY CONFIGURATION 58167801Sjhb 59177912SjeffIn OpenSSL 0.9.7 and later applications can automatically configure certain 60177912Sjeffaspects of OpenSSL using the master OpenSSL configuration file, or optionally 61177912Sjeffan alternative configuration file. The B<openssl> utility includes this 62177912Sjefffunctionality: any sub command uses the master OpenSSL configuration file 63177912Sjeffunless an option is used in the sub command to use an alternative configuration 64177912Sjefffile. 65177912Sjeff 66177912SjeffTo enable library configuration the default section needs to contain an 67154941Sjhbappropriate line which points to the main configuration section. The default 68154941Sjhbname is B<openssl_conf> which is used by the B<openssl> utility. Other 69154941Sjhbapplications may use an alternative name such as B<myapplicaton_conf>. 70154941Sjhb 71154941SjhbThe configuration section should consist of a set of name value pairs which 72173733Sattiliocontain specific module configuration information. The B<name> represents 73167368Sjhbthe name of the I<configuration module> the meaning of the B<value> is 74167368Sjhbmodule specific: it may, for example, represent a further configuration 75154941Sjhbsection containing configuration module specific information. E.g. 76154941Sjhb 77167365Sjhb openssl_conf = openssl_init 78167365Sjhb 79173733Sattilio [openssl_init] 80154941Sjhb 81167365Sjhb oid_section = new_oids 82154941Sjhb engines = engine_section 83167368Sjhb 84167368Sjhb [new_oids] 85154941Sjhb 86154941Sjhb ... new oids here ... 87157826Sjhb 88157826Sjhb [engine_section] 89157826Sjhb 90157826Sjhb ... engine stuff here ... 91157826Sjhb 92154941SjhbCurrently there are two configuration modules. One for ASN1 objects another 93154941Sjhbfor ENGINE configuration. 94154941Sjhb 95157826Sjhb=head2 ASN1 OBJECT CONFIGURATION MODULE 96171052Sattilio 97171052SattilioThis module has the name B<oid_section>. The value of this variable points 98171052Sattilioto a section containing name value pairs of OIDs: the name is the OID short 99171052Sattilioand long name, the value is the numerical form of the OID. Although some of 100171052Sattiliothe B<openssl> utility sub commands already have their own ASN1 OBJECT section 101171052Sattiliofunctionality not all do. By using the ASN1 OBJECT configuration module 102171052SattilioB<all> the B<openssl> utility sub commands can see the new objects as well 103171052Sattilioas any compliant applications. For example: 104171052Sattilio 105171052Sattilio [new_oids] 106171052Sattilio 107157826Sjhb some_new_oid = 1.2.3.4 108157826Sjhb some_other_oid = 1.2.3.5 109157826Sjhb 110157826SjhbIn OpenSSL 0.9.8 it is also possible to set the value to the long name followed 111157826Sjhbby a comma and the numerical OID form. For example: 112157826Sjhb 113154941Sjhb shortName = some object long name, 1.2.3.4 114154941Sjhb 115154941Sjhb=head2 ENGINE CONFIGURATION MODULE 116154941Sjhb 117154941SjhbThis ENGINE configuration module has the name B<engines>. The value of this 118173733Sattiliovariable points to a section containing further ENGINE configuration 119173733Sattilioinformation. 120173733Sattilio 121173733SattilioThe section pointed to by B<engines> is a table of engine names (though see 122173733SattilioB<engine_id> below) and further sections containing configuration informations 123173733Sattiliospecific to each ENGINE. 124173733Sattilio 125167368SjhbEach ENGINE specific section is used to set default algorithms, load 126167368Sjhbdynamic, perform initialization and send ctrls. The actual operation performed 127167368Sjhbdepends on the I<command> name which is the name of the name value pair. The 128167368Sjhbcurrently supported commands are listed below. 129167368Sjhb 130167368SjhbFor example: 131167368Sjhb 132167368Sjhb [engine_section] 133167368Sjhb 134167368Sjhb # Configure ENGINE named "foo" 135167368Sjhb foo = foo_section 136167368Sjhb # Configure ENGINE named "bar" 137167368Sjhb bar = bar_section 138167368Sjhb 139167368Sjhb [foo_section] 140167368Sjhb ... foo ENGINE specific commands ... 141167368Sjhb 142167368Sjhb [bar_section] 143167368Sjhb ... "bar" ENGINE specific commands ... 144167368Sjhb 145167368SjhbThe command B<engine_id> is used to give the ENGINE name. If used this 146167368Sjhbcommand must be first. For example: 147167368Sjhb 148167368Sjhb [engine_section] 149167368Sjhb # This would normally handle an ENGINE named "foo" 150167368Sjhb foo = foo_section 151167368Sjhb 152167368Sjhb [foo_section] 153171052Sattilio # Override default name and use "myfoo" instead. 154154941Sjhb engine_id = myfoo 155171052Sattilio 156154941SjhbThe command B<dynamic_path> loads and adds an ENGINE from the given path. It 157171052Sattiliois equivalent to sending the ctrls B<SO_PATH> with the path argument followed 158171052Sattilioby B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is 159171052Sattilionot the required behaviour then alternative ctrls can be sent directly 160171052Sattilioto the dynamic ENGINE using ctrl commands. 161171052Sattilio 162171052SattilioThe command B<init> determines whether to initialize the ENGINE. If the value 163171052Sattiliois B<0> the ENGINE will not be initialized, if B<1> and attempt it made to 164171052Sattilioinitialized the ENGINE immediately. If the B<init> command is not present 165171052Sattiliothen an attempt will be made to initialize the ENGINE after all commands in 166171052Sattilioits section have been processed. 167171052Sattilio 168171052SattilioThe command B<default_algorithms> sets the default algorithms an ENGINE will 169171052Sattiliosupply using the functions B<ENGINE_set_default_string()> 170171052Sattilio 171154941SjhbIf the name matches none of the above command names it is assumed to be a 172171052Sattilioctrl command which is sent to the ENGINE. The value of the command is the 173171052Sattilioargument to the ctrl command. If the value is the string B<EMPTY> then no 174154941Sjhbvalue is sent to the command. 175154941Sjhb 176154941SjhbFor example: 177154941Sjhb 178154941Sjhb 179154941Sjhb [engine_section] 180154941Sjhb 181171052Sattilio # Configure ENGINE named "foo" 182169394Sjhb foo = foo_section 183167787Sjhb 184154941Sjhb [foo_section] 185154941Sjhb # Load engine from DSO 186154941Sjhb dynamic_path = /some/path/fooengine.so 187154941Sjhb # A foo specific ctrl. 188154941Sjhb some_ctrl = some_value 189154941Sjhb # Another ctrl that doesn't take a value. 190154941Sjhb other_ctrl = EMPTY 191154941Sjhb # Supply all default algorithms 192154941Sjhb default_algorithms = ALL 193154941Sjhb 194167024Srwatson=head1 NOTES 195167024Srwatson 196167024SrwatsonIf a configuration file attempts to expand a variable that doesn't exist 197167024Srwatsonthen an error is flagged and the file will not load. This can happen 198167024Srwatsonif an attempt is made to expand an environment variable that doesn't 199167024Srwatsonexist. For example in a previous version of OpenSSL the default OpenSSL 200167024Srwatsonmaster configuration file used the value of B<HOME> which may not be 201154941Sjhbdefined on non Unix systems and would cause an error. 202154941Sjhb 203154941SjhbThis can be worked around by including a B<default> section to provide 204154941Sjhba default value: then if the environment lookup fails the default value 205154941Sjhbwill be used instead. For this to work properly the default value must 206169394Sjhbbe defined earlier in the configuration file than the expansion. See 207169394Sjhbthe B<EXAMPLES> section for an example of how to do this. 208167787Sjhb 209182914SjhbIf the same variable exists in the same section then all but the last 210154941Sjhbvalue will be silently ignored. In certain circumstances such as with 211171052SattilioDNs the same field may occur multiple times. This is usually worked 212167787Sjhbaround by ignoring any characters before an initial B<.> e.g. 213160771Sjhb 214154941Sjhb 1.OU="My first OU" 215154941Sjhb 2.OU="My Second OU" 216177843Sattilio 217177843Sattilio=head1 EXAMPLES 218177843Sattilio 219177843SattilioHere is a sample configuration file using some of the features 220177843Sattiliomentioned above. 221177843Sattilio 222177843Sattilio # This is the default section. 223177843Sattilio 224177843Sattilio HOME=/temp 225177843Sattilio RANDFILE= ${ENV::HOME}/.rnd 226177843Sattilio configdir=$ENV::HOME/config 227177843Sattilio 228177843Sattilio [ section_one ] 229177843Sattilio 230177843Sattilio # We are now in section one. 231177843Sattilio 232177843Sattilio # Quotes permit leading and trailing whitespace 233177843Sattilio any = " any variable name " 234177843Sattilio 235177843Sattilio other = A string that can \ 236177843Sattilio cover several lines \ 237177843Sattilio by including \\ characters 238177843Sattilio 239177843Sattilio message = Hello World\n 240154941Sjhb 241154941Sjhb [ section_two ] 242154941Sjhb 243154941Sjhb greeting = $section_one::message 244154941Sjhb 245169394SjhbThis next example shows how to expand environment variables safely. 246169394Sjhb 247154941SjhbSuppose you want a variable called B<tmpfile> to refer to a 248160771Sjhbtemporary filename. The directory it is placed in can determined by 249167787Sjhbthe the B<TEMP> or B<TMP> environment variables but they may not be 250171052Sattilioset to any value at all. If you just include the environment variable 251171052Sattilionames and the variable doesn't exist then this will cause an error when 252171052Sattilioan attempt is made to load the configuration file. By making use of the 253171052Sattiliodefault section both values can be looked up with B<TEMP> taking 254154941Sjhbpriority and B</tmp> used if neither is defined: 255154941Sjhb 256176017Sjeff TMP=/tmp 257176017Sjeff # The above value is used if TMP isn't in the environment 258176017Sjeff TEMP=$ENV::TMP 259176017Sjeff # The above value is used if TEMP isn't in the environment 260176017Sjeff tmpfile=${ENV::TEMP}/tmp.filename 261176017Sjeff 262176017Sjeff=head1 BUGS 263176017Sjeff 264176017SjeffCurrently there is no way to include characters using the octal B<\nnn> 265176017Sjeffform. Strings are all null terminated so nulls cannot form part of 266176017Sjeffthe value. 267154941Sjhb 268154941SjhbThe escaping isn't quite right: if you want to use sequences like B<\n> 269154941Sjhbyou can't use any quote escaping on the same line. 270154941Sjhb 271170295SjeffFiles are loaded in a single pass. This means that an variable expansion 272167801Sjhbwill only work if the variables referenced are defined earlier in the 273157846Sjhbfile. 274177912Sjeff 275177912Sjeff=head1 SEE ALSO 276157851Swkoszek 277167307SjhbL<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)> 278167054Skmacy 279176017Sjeff=cut 280154941Sjhb