159191Skris 259191Skris=pod 359191Skris 4160814Ssimon=for comment openssl_manual_section:5 5160814Ssimon 659191Skris=head1 NAME 759191Skris 859191Skrisconfig - OpenSSL CONF library configuration files 959191Skris 1059191Skris=head1 DESCRIPTION 1159191Skris 1259191SkrisThe OpenSSL CONF library can be used to read configuration files. 1359191SkrisIt is used for the OpenSSL master configuration file B<openssl.cnf> 1459191Skrisand in a few other places like B<SPKAC> files and certificate extension 15127128Snectarfiles for the B<x509> utility. OpenSSL applications can also use the 16127128SnectarCONF library for their own purposes. 1759191Skris 1859191SkrisA configuration file is divided into a number of sections. Each section 1959191Skrisstarts with a line B<[ section_name ]> and ends when a new section is 2059191Skrisstarted or end of file is reached. A section name can consist of 2159191Skrisalphanumeric characters and underscores. 2259191Skris 2359191SkrisThe first section of a configuration file is special and is referred 2459191Skristo as the B<default> section this is usually unnamed and is from the 2559191Skrisstart of file until the first named section. When a name is being looked up 2659191Skrisit is first looked up in a named section (if any) and then the 2759191Skrisdefault section. 2859191Skris 2959191SkrisThe environment is mapped onto a section called B<ENV>. 3059191Skris 3159191SkrisComments can be included by preceding them with the B<#> character 3259191Skris 3359191SkrisEach section in a configuration file consists of a number of name and 3459191Skrisvalue pairs of the form B<name=value> 3559191Skris 3659191SkrisThe B<name> string can contain any alphanumeric characters as well as 3759191Skrisa few punctuation symbols such as B<.> B<,> B<;> and B<_>. 3859191Skris 3959191SkrisThe B<value> string consists of the string following the B<=> character 4059191Skrisuntil end of line with any leading and trailing white space removed. 4159191Skris 4259191SkrisThe value string undergoes variable expansion. This can be done by 4359191Skrisincluding the form B<$var> or B<${var}>: this will substitute the value 4459191Skrisof the named variable in the current section. It is also possible to 4559191Skrissubstitute a value from another section using the syntax B<$section::name> 4659191Skrisor B<${section::name}>. By using the form B<$ENV::name> environment 4759191Skrisvariables can be substituted. It is also possible to assign values to 4859191Skrisenvironment variables by using the name B<ENV::name>, this will work 4959191Skrisif the program looks up environment variables using the B<CONF> library 5059191Skrisinstead of calling B<getenv()> directly. 5159191Skris 5259191SkrisIt is possible to escape certain characters by using any kind of quote 5359191Skrisor the B<\> character. By making the last character of a line a B<\> 5459191Skrisa B<value> string can be spread across multiple lines. In addition 5559191Skristhe sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. 5659191Skris 57127128Snectar=head1 OPENSSL LIBRARY CONFIGURATION 58127128Snectar 59127128SnectarIn OpenSSL 0.9.7 and later applications can automatically configure certain 60127128Snectaraspects of OpenSSL using the master OpenSSL configuration file, or optionally 61127128Snectaran alternative configuration file. The B<openssl> utility includes this 62127128Snectarfunctionality: any sub command uses the master OpenSSL configuration file 63127128Snectarunless an option is used in the sub command to use an alternative configuration 64127128Snectarfile. 65127128Snectar 66127128SnectarTo enable library configuration the default section needs to contain an 67127128Snectarappropriate line which points to the main configuration section. The default 68127128Snectarname is B<openssl_conf> which is used by the B<openssl> utility. Other 69127128Snectarapplications may use an alternative name such as B<myapplicaton_conf>. 70127128Snectar 71127128SnectarThe configuration section should consist of a set of name value pairs which 72127128Snectarcontain specific module configuration information. The B<name> represents 73127128Snectarthe name of the I<configuration module> the meaning of the B<value> is 74127128Snectarmodule specific: it may, for example, represent a further configuration 75127128Snectarsection containing configuration module specific information. E.g. 76127128Snectar 77127128Snectar openssl_conf = openssl_init 78127128Snectar 79127128Snectar [openssl_init] 80127128Snectar 81127128Snectar oid_section = new_oids 82127128Snectar engines = engine_section 83127128Snectar 84127128Snectar [new_oids] 85127128Snectar 86127128Snectar ... new oids here ... 87127128Snectar 88127128Snectar [engine_section] 89127128Snectar 90127128Snectar ... engine stuff here ... 91127128Snectar 92280304SjkimThe features of each configuration module are described below. 93127128Snectar 94127128Snectar=head2 ASN1 OBJECT CONFIGURATION MODULE 95127128Snectar 96127128SnectarThis module has the name B<oid_section>. The value of this variable points 97127128Snectarto a section containing name value pairs of OIDs: the name is the OID short 98127128Snectarand long name, the value is the numerical form of the OID. Although some of 99127128Snectarthe B<openssl> utility sub commands already have their own ASN1 OBJECT section 100127128Snectarfunctionality not all do. By using the ASN1 OBJECT configuration module 101127128SnectarB<all> the B<openssl> utility sub commands can see the new objects as well 102127128Snectaras any compliant applications. For example: 103127128Snectar 104127128Snectar [new_oids] 105127128Snectar 106127128Snectar some_new_oid = 1.2.3.4 107127128Snectar some_other_oid = 1.2.3.5 108127128Snectar 109160814SsimonIn OpenSSL 0.9.8 it is also possible to set the value to the long name followed 110160814Ssimonby a comma and the numerical OID form. For example: 111160814Ssimon 112160814Ssimon shortName = some object long name, 1.2.3.4 113160814Ssimon 114127128Snectar=head2 ENGINE CONFIGURATION MODULE 115127128Snectar 116127128SnectarThis ENGINE configuration module has the name B<engines>. The value of this 117127128Snectarvariable points to a section containing further ENGINE configuration 118127128Snectarinformation. 119127128Snectar 120127128SnectarThe section pointed to by B<engines> is a table of engine names (though see 121264331SjkimB<engine_id> below) and further sections containing configuration information 122127128Snectarspecific to each ENGINE. 123127128Snectar 124127128SnectarEach ENGINE specific section is used to set default algorithms, load 125127128Snectardynamic, perform initialization and send ctrls. The actual operation performed 126127128Snectardepends on the I<command> name which is the name of the name value pair. The 127127128Snectarcurrently supported commands are listed below. 128127128Snectar 129127128SnectarFor example: 130127128Snectar 131127128Snectar [engine_section] 132127128Snectar 133127128Snectar # Configure ENGINE named "foo" 134127128Snectar foo = foo_section 135127128Snectar # Configure ENGINE named "bar" 136127128Snectar bar = bar_section 137127128Snectar 138127128Snectar [foo_section] 139127128Snectar ... foo ENGINE specific commands ... 140127128Snectar 141127128Snectar [bar_section] 142127128Snectar ... "bar" ENGINE specific commands ... 143127128Snectar 144127128SnectarThe command B<engine_id> is used to give the ENGINE name. If used this 145127128Snectarcommand must be first. For example: 146127128Snectar 147127128Snectar [engine_section] 148127128Snectar # This would normally handle an ENGINE named "foo" 149127128Snectar foo = foo_section 150127128Snectar 151127128Snectar [foo_section] 152127128Snectar # Override default name and use "myfoo" instead. 153127128Snectar engine_id = myfoo 154127128Snectar 155127128SnectarThe command B<dynamic_path> loads and adds an ENGINE from the given path. It 156127128Snectaris equivalent to sending the ctrls B<SO_PATH> with the path argument followed 157127128Snectarby B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is 158127128Snectarnot the required behaviour then alternative ctrls can be sent directly 159127128Snectarto the dynamic ENGINE using ctrl commands. 160127128Snectar 161127128SnectarThe command B<init> determines whether to initialize the ENGINE. If the value 162127128Snectaris B<0> the ENGINE will not be initialized, if B<1> and attempt it made to 163127128Snectarinitialized the ENGINE immediately. If the B<init> command is not present 164127128Snectarthen an attempt will be made to initialize the ENGINE after all commands in 165127128Snectarits section have been processed. 166127128Snectar 167127128SnectarThe command B<default_algorithms> sets the default algorithms an ENGINE will 168127128Snectarsupply using the functions B<ENGINE_set_default_string()> 169127128Snectar 170127128SnectarIf the name matches none of the above command names it is assumed to be a 171127128Snectarctrl command which is sent to the ENGINE. The value of the command is the 172127128Snectarargument to the ctrl command. If the value is the string B<EMPTY> then no 173127128Snectarvalue is sent to the command. 174127128Snectar 175127128SnectarFor example: 176127128Snectar 177127128Snectar 178127128Snectar [engine_section] 179127128Snectar 180127128Snectar # Configure ENGINE named "foo" 181127128Snectar foo = foo_section 182127128Snectar 183127128Snectar [foo_section] 184127128Snectar # Load engine from DSO 185127128Snectar dynamic_path = /some/path/fooengine.so 186127128Snectar # A foo specific ctrl. 187127128Snectar some_ctrl = some_value 188127128Snectar # Another ctrl that doesn't take a value. 189127128Snectar other_ctrl = EMPTY 190127128Snectar # Supply all default algorithms 191127128Snectar default_algorithms = ALL 192127128Snectar 193280304Sjkim=head2 EVP CONFIGURATION MODULE 194280304Sjkim 195280304SjkimThis modules has the name B<alg_section> which points to a section containing 196280304Sjkimalgorithm commands. 197280304Sjkim 198280304SjkimCurrently the only algorithm command supported is B<fips_mode> whose 199280304Sjkimvalue should be a boolean string such as B<on> or B<off>. If the value is 200280304SjkimB<on> this attempt to enter FIPS mode. If the call fails or the library is 201280304Sjkimnot FIPS capable then an error occurs. 202280304Sjkim 203280304SjkimFor example: 204280304Sjkim 205280304Sjkim alg_section = evp_settings 206280304Sjkim 207280304Sjkim [evp_settings] 208280304Sjkim 209280304Sjkim fips_mode = on 210280304Sjkim 211280304Sjkim 21259191Skris=head1 NOTES 21359191Skris 21459191SkrisIf a configuration file attempts to expand a variable that doesn't exist 21559191Skristhen an error is flagged and the file will not load. This can happen 21659191Skrisif an attempt is made to expand an environment variable that doesn't 217127128Snectarexist. For example in a previous version of OpenSSL the default OpenSSL 218127128Snectarmaster configuration file used the value of B<HOME> which may not be 219127128Snectardefined on non Unix systems and would cause an error. 22059191Skris 22159191SkrisThis can be worked around by including a B<default> section to provide 22259191Skrisa default value: then if the environment lookup fails the default value 22359191Skriswill be used instead. For this to work properly the default value must 22459191Skrisbe defined earlier in the configuration file than the expansion. See 22559191Skristhe B<EXAMPLES> section for an example of how to do this. 22659191Skris 22759191SkrisIf the same variable exists in the same section then all but the last 22859191Skrisvalue will be silently ignored. In certain circumstances such as with 22959191SkrisDNs the same field may occur multiple times. This is usually worked 23059191Skrisaround by ignoring any characters before an initial B<.> e.g. 23159191Skris 23259191Skris 1.OU="My first OU" 23359191Skris 2.OU="My Second OU" 23459191Skris 23559191Skris=head1 EXAMPLES 23659191Skris 23759191SkrisHere is a sample configuration file using some of the features 23859191Skrismentioned above. 23959191Skris 24059191Skris # This is the default section. 24159191Skris 24259191Skris HOME=/temp 24359191Skris RANDFILE= ${ENV::HOME}/.rnd 24459191Skris configdir=$ENV::HOME/config 24559191Skris 24659191Skris [ section_one ] 24759191Skris 24859191Skris # We are now in section one. 24959191Skris 25059191Skris # Quotes permit leading and trailing whitespace 25159191Skris any = " any variable name " 25259191Skris 25359191Skris other = A string that can \ 25459191Skris cover several lines \ 25559191Skris by including \\ characters 25659191Skris 25759191Skris message = Hello World\n 25859191Skris 25959191Skris [ section_two ] 26059191Skris 26159191Skris greeting = $section_one::message 26259191Skris 26359191SkrisThis next example shows how to expand environment variables safely. 26459191Skris 26559191SkrisSuppose you want a variable called B<tmpfile> to refer to a 26659191Skristemporary filename. The directory it is placed in can determined by 267238405Sjkimthe B<TEMP> or B<TMP> environment variables but they may not be 26859191Skrisset to any value at all. If you just include the environment variable 26959191Skrisnames and the variable doesn't exist then this will cause an error when 27059191Skrisan attempt is made to load the configuration file. By making use of the 27159191Skrisdefault section both values can be looked up with B<TEMP> taking 27259191Skrispriority and B</tmp> used if neither is defined: 27359191Skris 27459191Skris TMP=/tmp 27559191Skris # The above value is used if TMP isn't in the environment 27659191Skris TEMP=$ENV::TMP 27759191Skris # The above value is used if TEMP isn't in the environment 27859191Skris tmpfile=${ENV::TEMP}/tmp.filename 27959191Skris 280284285SjkimSimple OpenSSL library configuration example to enter FIPS mode: 281284285Sjkim 282284285Sjkim # Default appname: should match "appname" parameter (if any) 283284285Sjkim # supplied to CONF_modules_load_file et al. 284284285Sjkim openssl_conf = openssl_conf_section 285284285Sjkim 286284285Sjkim [openssl_conf_section] 287284285Sjkim # Configuration module list 288284285Sjkim alg_section = evp_sect 289284285Sjkim 290284285Sjkim [evp_sect] 291284285Sjkim # Set to "yes" to enter FIPS mode if supported 292284285Sjkim fips_mode = yes 293284285Sjkim 294284285SjkimNote: in the above example you will get an error in non FIPS capable versions 295284285Sjkimof OpenSSL. 296284285Sjkim 297284285SjkimMore complex OpenSSL library configuration. Add OID and don't enter FIPS mode: 298284285Sjkim 299284285Sjkim # Default appname: should match "appname" parameter (if any) 300284285Sjkim # supplied to CONF_modules_load_file et al. 301284285Sjkim openssl_conf = openssl_conf_section 302284285Sjkim 303284285Sjkim [openssl_conf_section] 304284285Sjkim # Configuration module list 305284285Sjkim alg_section = evp_sect 306284285Sjkim oid_section = new_oids 307284285Sjkim 308284285Sjkim [evp_sect] 309284285Sjkim # This will have no effect as FIPS mode is off by default. 310284285Sjkim # Set to "yes" to enter FIPS mode, if supported 311284285Sjkim fips_mode = no 312284285Sjkim 313284285Sjkim [new_oids] 314284285Sjkim # New OID, just short name 315284285Sjkim newoid1 = 1.2.3.4.1 316284285Sjkim # New OID shortname and long name 317284285Sjkim newoid2 = New OID 2 long name, 1.2.3.4.2 318284285Sjkim 319284285SjkimThe above examples can be used with with any application supporting library 320284285Sjkimconfiguration if "openssl_conf" is modified to match the appropriate "appname". 321284285Sjkim 322284285SjkimFor example if the second sample file above is saved to "example.cnf" then 323284285Sjkimthe command line: 324284285Sjkim 325284285Sjkim OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1 326284285Sjkim 327284285Sjkimwill output: 328284285Sjkim 329284285Sjkim 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1 330284285Sjkim 331284285Sjkimshowing that the OID "newoid1" has been added as "1.2.3.4.1". 332284285Sjkim 33359191Skris=head1 BUGS 33459191Skris 33559191SkrisCurrently there is no way to include characters using the octal B<\nnn> 33659191Skrisform. Strings are all null terminated so nulls cannot form part of 33759191Skristhe value. 33859191Skris 33959191SkrisThe escaping isn't quite right: if you want to use sequences like B<\n> 34059191Skrisyou can't use any quote escaping on the same line. 34159191Skris 34259191SkrisFiles are loaded in a single pass. This means that an variable expansion 34359191Skriswill only work if the variables referenced are defined earlier in the 34459191Skrisfile. 34559191Skris 34659191Skris=head1 SEE ALSO 34759191Skris 34859191SkrisL<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)> 34959191Skris 35059191Skris=cut 351