]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | =pod |
2 | ||
401ee37a DSH |
3 | =for comment openssl_manual_section:5 |
4 | ||
aba3e65f DSH |
5 | =head1 NAME |
6 | ||
19d2bb57 | 7 | config - OpenSSL CONF library configuration files |
aba3e65f DSH |
8 | |
9 | =head1 DESCRIPTION | |
10 | ||
19d2bb57 | 11 | The OpenSSL CONF library can be used to read configuration files. |
aba3e65f DSH |
12 | It is used for the OpenSSL master configuration file B<openssl.cnf> |
13 | and in a few other places like B<SPKAC> files and certificate extension | |
a30af36c DSH |
14 | files for the B<x509> utility. OpenSSL applications can also use the |
15 | CONF library for their own purposes. | |
aba3e65f DSH |
16 | |
17 | A configuration file is divided into a number of sections. Each section | |
18 | starts with a line B<[ section_name ]> and ends when a new section is | |
19 | started or end of file is reached. A section name can consist of | |
20 | alphanumeric characters and underscores. | |
21 | ||
22 | The first section of a configuration file is special and is referred | |
23 | to as the B<default> section this is usually unnamed and is from the | |
24 | start of file until the first named section. When a name is being looked up | |
25 | it is first looked up in a named section (if any) and then the | |
26 | default section. | |
27 | ||
28 | The environment is mapped onto a section called B<ENV>. | |
29 | ||
30 | Comments can be included by preceding them with the B<#> character | |
31 | ||
32 | Each section in a configuration file consists of a number of name and | |
33 | value pairs of the form B<name=value> | |
34 | ||
35 | The B<name> string can contain any alphanumeric characters as well as | |
36 | a few punctuation symbols such as B<.> B<,> B<;> and B<_>. | |
37 | ||
38 | The B<value> string consists of the string following the B<=> character | |
39 | until end of line with any leading and trailing white space removed. | |
40 | ||
41 | The value string undergoes variable expansion. This can be done by | |
42 | including the form B<$var> or B<${var}>: this will substitute the value | |
43 | of the named variable in the current section. It is also possible to | |
44 | substitute a value from another section using the syntax B<$section::name> | |
19d2bb57 | 45 | or B<${section::name}>. By using the form B<$ENV::name> environment |
aba3e65f DSH |
46 | variables can be substituted. It is also possible to assign values to |
47 | environment variables by using the name B<ENV::name>, this will work | |
48 | if the program looks up environment variables using the B<CONF> library | |
35cb565a | 49 | instead of calling getenv() directly. |
aba3e65f DSH |
50 | |
51 | It is possible to escape certain characters by using any kind of quote | |
52 | or the B<\> character. By making the last character of a line a B<\> | |
53 | a B<value> string can be spread across multiple lines. In addition | |
657e60fa | 54 | the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. |
aba3e65f | 55 | |
a30af36c DSH |
56 | =head1 OPENSSL LIBRARY CONFIGURATION |
57 | ||
a528d4f0 | 58 | Applications can automatically configure certain |
a30af36c DSH |
59 | aspects of OpenSSL using the master OpenSSL configuration file, or optionally |
60 | an alternative configuration file. The B<openssl> utility includes this | |
61 | functionality: any sub command uses the master OpenSSL configuration file | |
62 | unless an option is used in the sub command to use an alternative configuration | |
63 | file. | |
64 | ||
1bc74519 | 65 | To enable library configuration the default section needs to contain an |
a30af36c DSH |
66 | appropriate line which points to the main configuration section. The default |
67 | name is B<openssl_conf> which is used by the B<openssl> utility. Other | |
68 | applications may use an alternative name such as B<myapplicaton_conf>. | |
69 | ||
70 | The configuration section should consist of a set of name value pairs which | |
71 | contain specific module configuration information. The B<name> represents | |
1bc74519 | 72 | the name of the I<configuration module> the meaning of the B<value> is |
a30af36c DSH |
73 | module specific: it may, for example, represent a further configuration |
74 | section containing configuration module specific information. E.g. | |
75 | ||
76 | openssl_conf = openssl_init | |
77 | ||
78 | [openssl_init] | |
79 | ||
80 | oid_section = new_oids | |
81 | engines = engine_section | |
82 | ||
83 | [new_oids] | |
84 | ||
85 | ... new oids here ... | |
86 | ||
87 | [engine_section] | |
88 | ||
89 | ... engine stuff here ... | |
90 | ||
3d764db7 | 91 | The features of each configuration module are described below. |
a30af36c DSH |
92 | |
93 | =head2 ASN1 OBJECT CONFIGURATION MODULE | |
94 | ||
95 | This module has the name B<oid_section>. The value of this variable points | |
96 | to a section containing name value pairs of OIDs: the name is the OID short | |
97 | and long name, the value is the numerical form of the OID. Although some of | |
98 | the B<openssl> utility sub commands already have their own ASN1 OBJECT section | |
99 | functionality not all do. By using the ASN1 OBJECT configuration module | |
100 | B<all> the B<openssl> utility sub commands can see the new objects as well | |
101 | as any compliant applications. For example: | |
102 | ||
103 | [new_oids] | |
1bc74519 | 104 | |
a30af36c DSH |
105 | some_new_oid = 1.2.3.4 |
106 | some_other_oid = 1.2.3.5 | |
107 | ||
a528d4f0 | 108 | It is also possible to set the value to the long name followed |
6446e0c3 DSH |
109 | by a comma and the numerical OID form. For example: |
110 | ||
111 | shortName = some object long name, 1.2.3.4 | |
112 | ||
a30af36c DSH |
113 | =head2 ENGINE CONFIGURATION MODULE |
114 | ||
f2c18125 DSH |
115 | This ENGINE configuration module has the name B<engines>. The value of this |
116 | variable points to a section containing further ENGINE configuration | |
117 | information. | |
118 | ||
119 | The section pointed to by B<engines> is a table of engine names (though see | |
2b4ffc65 | 120 | B<engine_id> below) and further sections containing configuration information |
f2c18125 DSH |
121 | specific to each ENGINE. |
122 | ||
123 | Each ENGINE specific section is used to set default algorithms, load | |
124 | dynamic, perform initialization and send ctrls. The actual operation performed | |
125 | depends on the I<command> name which is the name of the name value pair. The | |
126 | currently supported commands are listed below. | |
127 | ||
128 | For example: | |
129 | ||
130 | [engine_section] | |
131 | ||
132 | # Configure ENGINE named "foo" | |
133 | foo = foo_section | |
134 | # Configure ENGINE named "bar" | |
135 | bar = bar_section | |
136 | ||
137 | [foo_section] | |
138 | ... foo ENGINE specific commands ... | |
139 | ||
140 | [bar_section] | |
141 | ... "bar" ENGINE specific commands ... | |
142 | ||
1bc74519 | 143 | The command B<engine_id> is used to give the ENGINE name. If used this |
f2c18125 DSH |
144 | command must be first. For example: |
145 | ||
146 | [engine_section] | |
147 | # This would normally handle an ENGINE named "foo" | |
148 | foo = foo_section | |
149 | ||
150 | [foo_section] | |
151 | # Override default name and use "myfoo" instead. | |
152 | engine_id = myfoo | |
153 | ||
154 | The command B<dynamic_path> loads and adds an ENGINE from the given path. It | |
155 | is equivalent to sending the ctrls B<SO_PATH> with the path argument followed | |
156 | by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is | |
157 | not the required behaviour then alternative ctrls can be sent directly | |
158 | to the dynamic ENGINE using ctrl commands. | |
159 | ||
160 | The command B<init> determines whether to initialize the ENGINE. If the value | |
161 | is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to | |
162 | initialized the ENGINE immediately. If the B<init> command is not present | |
163 | then an attempt will be made to initialize the ENGINE after all commands in | |
164 | its section have been processed. | |
165 | ||
166 | The command B<default_algorithms> sets the default algorithms an ENGINE will | |
35cb565a | 167 | supply using the functions ENGINE_set_default_string(). |
f2c18125 DSH |
168 | |
169 | If the name matches none of the above command names it is assumed to be a | |
1bc74519 | 170 | ctrl command which is sent to the ENGINE. The value of the command is the |
f2c18125 DSH |
171 | argument to the ctrl command. If the value is the string B<EMPTY> then no |
172 | value is sent to the command. | |
173 | ||
174 | For example: | |
175 | ||
176 | ||
177 | [engine_section] | |
178 | ||
179 | # Configure ENGINE named "foo" | |
180 | foo = foo_section | |
181 | ||
182 | [foo_section] | |
183 | # Load engine from DSO | |
184 | dynamic_path = /some/path/fooengine.so | |
185 | # A foo specific ctrl. | |
186 | some_ctrl = some_value | |
187 | # Another ctrl that doesn't take a value. | |
188 | other_ctrl = EMPTY | |
189 | # Supply all default algorithms | |
190 | default_algorithms = ALL | |
a30af36c | 191 | |
3d764db7 DSH |
192 | =head2 EVP CONFIGURATION MODULE |
193 | ||
194 | This modules has the name B<alg_section> which points to a section containing | |
195 | algorithm commands. | |
196 | ||
197 | Currently the only algorithm command supported is B<fips_mode> whose | |
198 | value should be a boolean string such as B<on> or B<off>. If the value is | |
199 | B<on> this attempt to enter FIPS mode. If the call fails or the library is | |
200 | not FIPS capable then an error occurs. | |
201 | ||
202 | For example: | |
203 | ||
204 | alg_section = evp_settings | |
205 | ||
206 | [evp_settings] | |
207 | ||
208 | fips_mode = on | |
209 | ||
913592d2 DSH |
210 | =head2 SSL CONFIGURATION MODULE |
211 | ||
212 | This module has the name B<ssl_conf> which points to a section containing | |
213 | SSL configurations. | |
214 | ||
215 | Each line in the SSL configuration section contains the name of the | |
216 | configuration and the section containing it. | |
217 | ||
218 | Each configuration section consists of command value pairs for B<SSL_CONF>. | |
219 | Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls | |
220 | SSL_CTX_config() or SSL_config() with the appropriate configuration name. | |
221 | ||
222 | Note: any characters before an initial dot in the configuration section are | |
223 | ignored so the same command can be used multiple times. | |
224 | ||
225 | For example: | |
226 | ||
227 | ssl_conf = ssl_sect | |
228 | ||
229 | [ssl_sect] | |
230 | ||
231 | server = server_section | |
232 | ||
233 | [server_section] | |
234 | ||
235 | RSA.Certificate = server-rsa.pem | |
236 | ECDSA.Certificate = server-ecdsa.pem | |
237 | Ciphers = ALL:!RC4 | |
3d764db7 | 238 | |
aba3e65f DSH |
239 | =head1 NOTES |
240 | ||
19d2bb57 | 241 | If a configuration file attempts to expand a variable that doesn't exist |
aba3e65f DSH |
242 | then an error is flagged and the file will not load. This can happen |
243 | if an attempt is made to expand an environment variable that doesn't | |
a30af36c DSH |
244 | exist. For example in a previous version of OpenSSL the default OpenSSL |
245 | master configuration file used the value of B<HOME> which may not be | |
246 | defined on non Unix systems and would cause an error. | |
aba3e65f DSH |
247 | |
248 | This can be worked around by including a B<default> section to provide | |
249 | a default value: then if the environment lookup fails the default value | |
250 | will be used instead. For this to work properly the default value must | |
251 | be defined earlier in the configuration file than the expansion. See | |
252 | the B<EXAMPLES> section for an example of how to do this. | |
253 | ||
254 | If the same variable exists in the same section then all but the last | |
255 | value will be silently ignored. In certain circumstances such as with | |
256 | DNs the same field may occur multiple times. This is usually worked | |
257 | around by ignoring any characters before an initial B<.> e.g. | |
258 | ||
259 | 1.OU="My first OU" | |
260 | 2.OU="My Second OU" | |
261 | ||
262 | =head1 EXAMPLES | |
263 | ||
264 | Here is a sample configuration file using some of the features | |
265 | mentioned above. | |
266 | ||
267 | # This is the default section. | |
1bc74519 | 268 | |
aba3e65f DSH |
269 | HOME=/temp |
270 | RANDFILE= ${ENV::HOME}/.rnd | |
271 | configdir=$ENV::HOME/config | |
272 | ||
273 | [ section_one ] | |
274 | ||
275 | # We are now in section one. | |
276 | ||
277 | # Quotes permit leading and trailing whitespace | |
278 | any = " any variable name " | |
279 | ||
280 | other = A string that can \ | |
281 | cover several lines \ | |
282 | by including \\ characters | |
283 | ||
284 | message = Hello World\n | |
285 | ||
286 | [ section_two ] | |
287 | ||
288 | greeting = $section_one::message | |
289 | ||
290 | This next example shows how to expand environment variables safely. | |
291 | ||
292 | Suppose you want a variable called B<tmpfile> to refer to a | |
293 | temporary filename. The directory it is placed in can determined by | |
35ed393e | 294 | the B<TEMP> or B<TMP> environment variables but they may not be |
aba3e65f DSH |
295 | set to any value at all. If you just include the environment variable |
296 | names and the variable doesn't exist then this will cause an error when | |
297 | an attempt is made to load the configuration file. By making use of the | |
1bc74519 | 298 | default section both values can be looked up with B<TEMP> taking |
aba3e65f DSH |
299 | priority and B</tmp> used if neither is defined: |
300 | ||
301 | TMP=/tmp | |
302 | # The above value is used if TMP isn't in the environment | |
303 | TEMP=$ENV::TMP | |
304 | # The above value is used if TEMP isn't in the environment | |
305 | tmpfile=${ENV::TEMP}/tmp.filename | |
306 | ||
7b68c30d DSH |
307 | Simple OpenSSL library configuration example to enter FIPS mode: |
308 | ||
309 | # Default appname: should match "appname" parameter (if any) | |
310 | # supplied to CONF_modules_load_file et al. | |
311 | openssl_conf = openssl_conf_section | |
312 | ||
313 | [openssl_conf_section] | |
314 | # Configuration module list | |
315 | alg_section = evp_sect | |
316 | ||
317 | [evp_sect] | |
318 | # Set to "yes" to enter FIPS mode if supported | |
319 | fips_mode = yes | |
320 | ||
321 | Note: in the above example you will get an error in non FIPS capable versions | |
322 | of OpenSSL. | |
323 | ||
324 | More complex OpenSSL library configuration. Add OID and don't enter FIPS mode: | |
325 | ||
326 | # Default appname: should match "appname" parameter (if any) | |
327 | # supplied to CONF_modules_load_file et al. | |
328 | openssl_conf = openssl_conf_section | |
329 | ||
330 | [openssl_conf_section] | |
331 | # Configuration module list | |
332 | alg_section = evp_sect | |
333 | oid_section = new_oids | |
334 | ||
335 | [evp_sect] | |
336 | # This will have no effect as FIPS mode is off by default. | |
337 | # Set to "yes" to enter FIPS mode, if supported | |
338 | fips_mode = no | |
339 | ||
340 | [new_oids] | |
341 | # New OID, just short name | |
342 | newoid1 = 1.2.3.4.1 | |
343 | # New OID shortname and long name | |
344 | newoid2 = New OID 2 long name, 1.2.3.4.2 | |
345 | ||
35ed393e | 346 | The above examples can be used with any application supporting library |
7b68c30d DSH |
347 | configuration if "openssl_conf" is modified to match the appropriate "appname". |
348 | ||
349 | For example if the second sample file above is saved to "example.cnf" then | |
350 | the command line: | |
351 | ||
352 | OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1 | |
353 | ||
354 | will output: | |
355 | ||
356 | 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1 | |
357 | ||
358 | showing that the OID "newoid1" has been added as "1.2.3.4.1". | |
359 | ||
aba3e65f DSH |
360 | =head1 BUGS |
361 | ||
362 | Currently there is no way to include characters using the octal B<\nnn> | |
363 | form. Strings are all null terminated so nulls cannot form part of | |
364 | the value. | |
365 | ||
366 | The escaping isn't quite right: if you want to use sequences like B<\n> | |
367 | you can't use any quote escaping on the same line. | |
368 | ||
369 | Files are loaded in a single pass. This means that an variable expansion | |
370 | will only work if the variables referenced are defined earlier in the | |
371 | file. | |
372 | ||
373 | =head1 SEE ALSO | |
374 | ||
9b86974e | 375 | L<x509(1)>, L<req(1)>, L<ca(1)> |
aba3e65f DSH |
376 | |
377 | =cut | |
e2f92610 RS |
378 | |
379 | =head1 COPYRIGHT | |
380 | ||
381 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
382 | ||
383 | Licensed under the OpenSSL license (the "License"). You may not use | |
384 | this file except in compliance with the License. You can obtain a copy | |
385 | in the file LICENSE in the source distribution or at | |
386 | L<https://www.openssl.org/source/license.html>. | |
387 | ||
388 | =cut |