config.pod revision 160815
1157299Smarcel 2157299Smarcel=pod 3157299Smarcel 4157299Smarcel=for comment openssl_manual_section:5 5157299Smarcel 6157299Smarcel=head1 NAME 7157299Smarcel 8157299Smarcelconfig - OpenSSL CONF library configuration files 9157299Smarcel 10157299Smarcel=head1 DESCRIPTION 11157299Smarcel 12157299SmarcelThe OpenSSL CONF library can be used to read configuration files. 13157299SmarcelIt is used for the OpenSSL master configuration file B<openssl.cnf> 14157299Smarceland in a few other places like B<SPKAC> files and certificate extension 15157299Smarcelfiles for the B<x509> utility. OpenSSL applications can also use the 16157299SmarcelCONF library for their own purposes. 17157299Smarcel 18157299SmarcelA configuration file is divided into a number of sections. Each section 19157299Smarcelstarts with a line B<[ section_name ]> and ends when a new section is 20157299Smarcelstarted or end of file is reached. A section name can consist of 21157299Smarcelalphanumeric characters and underscores. 22157299Smarcel 23157299SmarcelThe first section of a configuration file is special and is referred 24157299Smarcelto as the B<default> section this is usually unnamed and is from the 25157299Smarcelstart of file until the first named section. When a name is being looked up 26157299Smarcelit is first looked up in a named section (if any) and then the 27157299Smarceldefault section. 28157299Smarcel 29157299SmarcelThe environment is mapped onto a section called B<ENV>. 30157299Smarcel 31157299SmarcelComments can be included by preceding them with the B<#> character 32157299Smarcel 33157299SmarcelEach section in a configuration file consists of a number of name and 34157299Smarcelvalue pairs of the form B<name=value> 35157299Smarcel 36157299SmarcelThe B<name> string can contain any alphanumeric characters as well as 37157299Smarcela few punctuation symbols such as B<.> B<,> B<;> and B<_>. 38157299Smarcel 39157299SmarcelThe B<value> string consists of the string following the B<=> character 40157299Smarceluntil end of line with any leading and trailing white space removed. 41157299Smarcel 42157299SmarcelThe value string undergoes variable expansion. This can be done by 43157299Smarcelincluding the form B<$var> or B<${var}>: this will substitute the value 44157299Smarcelof the named variable in the current section. It is also possible to 45157351Smarcelsubstitute a value from another section using the syntax B<$section::name> 46157351Smarcelor B<${section::name}>. By using the form B<$ENV::name> environment 47157351Smarcelvariables can be substituted. It is also possible to assign values to 48157299Smarcelenvironment variables by using the name B<ENV::name>, this will work 49157299Smarcelif the program looks up environment variables using the B<CONF> library 50157299Smarcelinstead of calling B<getenv()> directly. 51157299Smarcel 52157299SmarcelIt is possible to escape certain characters by using any kind of quote 53157299Smarcelor the B<\> character. By making the last character of a line a B<\> 54157299Smarcela B<value> string can be spread across multiple lines. In addition 55157299Smarcelthe sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. 56157299Smarcel 57157299Smarcel=head1 OPENSSL LIBRARY CONFIGURATION 58157299Smarcel 59221960SmariusIn OpenSSL 0.9.7 and later applications can automatically configure certain 60221960Smariusaspects of OpenSSL using the master OpenSSL configuration file, or optionally 61157299Smarcelan alternative configuration file. The B<openssl> utility includes this 62157299Smarcelfunctionality: any sub command uses the master OpenSSL configuration file 63167822Smarcelunless an option is used in the sub command to use an alternative configuration 64157299Smarcelfile. 65157299Smarcel 66157299SmarcelTo enable library configuration the default section needs to contain an 67157299Smarcelappropriate line which points to the main configuration section. The default 68178600Smarcelname is B<openssl_conf> which is used by the B<openssl> utility. Other 69178600Smarcelapplications may use an alternative name such as B<myapplicaton_conf>. 70178600Smarcel 71178600SmarcelThe configuration section should consist of a set of name value pairs which 72178600Smarcelcontain specific module configuration information. The B<name> represents 73178600Smarcelthe name of the I<configuration module> the meaning of the B<value> is 74178600Smarcelmodule specific: it may, for example, represent a further configuration 75157299Smarcelsection containing configuration module specific information. E.g. 76157299Smarcel 77157299Smarcel openssl_conf = openssl_init 78178600Smarcel 79157299Smarcel [openssl_init] 80157299Smarcel 81157299Smarcel oid_section = new_oids 82157299Smarcel engines = engine_section 83157299Smarcel 84157299Smarcel [new_oids] 85157299Smarcel 86157299Smarcel ... new oids here ... 87227843Smarius 88227843Smarius [engine_section] 89157299Smarcel 90157299Smarcel ... engine stuff here ... 91157299Smarcel 92157299SmarcelCurrently there are two configuration modules. One for ASN1 objects another 93157299Smarcelfor ENGINE configuration. 94157299Smarcel 95157299Smarcel=head2 ASN1 OBJECT CONFIGURATION MODULE 96157299Smarcel 97253900SmariusThis 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