| config.pod (59191) | config.pod (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 | 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 | 13files for the B<x509> utility. OpenSSL applications can also use the 14CONF library for their own purposes. |
| 14 15A configuration file is divided into a number of sections. Each section 16starts with a line B<[ section_name ]> and ends when a new section is 17started or end of file is reached. A section name can consist of 18alphanumeric characters and underscores. 19 20The first section of a configuration file is special and is referred 21to as the B<default> section this is usually unnamed and is from the --- 24 unchanged lines hidden (view full) --- 46if the program looks up environment variables using the B<CONF> library 47instead of calling B<getenv()> directly. 48 49It is possible to escape certain characters by using any kind of quote 50or the B<\> character. By making the last character of a line a B<\> 51a B<value> string can be spread across multiple lines. In addition 52the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. 53 | 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 --- 24 unchanged lines hidden (view full) --- 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 |
|
| 54=head1 NOTES 55 56If a configuration file attempts to expand a variable that doesn't exist 57then an error is flagged and the file will not load. This can happen 58if an attempt is made to expand an environment variable that doesn't | 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 |
| 59exist. For example the default OpenSSL master configuration file used 60the value of B<HOME> which may not be defined on non Unix systems. | 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. |
| 61 62This can be worked around by including a B<default> section to provide 63a default value: then if the environment lookup fails the default value 64will be used instead. For this to work properly the default value must 65be defined earlier in the configuration file than the expansion. See 66the B<EXAMPLES> section for an example of how to do this. 67 68If the same variable exists in the same section then all but the last --- 70 unchanged lines hidden --- | 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 --- 70 unchanged lines hidden --- |