Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / usr.bin / openssl / man / config.5
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
984263bc
MD
2.\"
3.\" Standard preamble:
a561f9ff 4.\" ========================================================================
984263bc
MD
5.de Sh \" Subsection heading
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
13.de Sp \" Vertical space (when we can't use .PP)
14.if t .sp .5v
15.if n .sp
16..
984263bc
MD
17.de Vb \" Begin verbatim text
18.ft CW
19.nf
20.ne \\$1
21..
22.de Ve \" End verbatim text
23.ft R
984263bc
MD
24.fi
25..
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
aac4ff6f
PA
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
984263bc
MD
33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34.ie n \{\
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
43'br\}
44.el\{\
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
49'br\}
50.\"
a561f9ff
SS
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
984263bc
MD
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
58..
59. nr % 0
60. rr F
61.\}
62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
984263bc
MD
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
984263bc
MD
70. \" fudge factors for nroff and troff
71.if n \{\
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
77.\}
78.if t \{\
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
84.\}
85. \" simple accents for nroff and troff
86.if n \{\
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
93.\}
94.if t \{\
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101.\}
102. \" troff and (daisy-wheel) nroff accents
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
112. \" corrections for vroff
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115. \" for low resolution devices (crt and lpr)
116.if \n(.H>23 .if \n(.V>19 \
117\{\
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
127.\}
128.rm #[ #] #H #V #F C
a561f9ff 129.\" ========================================================================
984263bc 130.\"
a561f9ff 131.IX Title "CONFIG 5"
aac4ff6f 132.TH CONFIG 5 "2008-09-06" "0.9.8h" "OpenSSL"
984263bc 133.SH "NAME"
a561f9ff 134config \- OpenSSL CONF library configuration files
984263bc
MD
135.SH "DESCRIPTION"
136.IX Header "DESCRIPTION"
137The OpenSSL \s-1CONF\s0 library can be used to read configuration files.
138It is used for the OpenSSL master configuration file \fBopenssl.cnf\fR
139and in a few other places like \fB\s-1SPKAC\s0\fR files and certificate extension
a561f9ff
SS
140files for the \fBx509\fR utility. OpenSSL applications can also use the
141\&\s-1CONF\s0 library for their own purposes.
984263bc
MD
142.PP
143A configuration file is divided into a number of sections. Each section
144starts with a line \fB[ section_name ]\fR and ends when a new section is
145started or end of file is reached. A section name can consist of
146alphanumeric characters and underscores.
147.PP
148The first section of a configuration file is special and is referred
149to as the \fBdefault\fR section this is usually unnamed and is from the
150start of file until the first named section. When a name is being looked up
151it is first looked up in a named section (if any) and then the
152default section.
153.PP
154The environment is mapped onto a section called \fB\s-1ENV\s0\fR.
155.PP
156Comments can be included by preceding them with the \fB#\fR character
157.PP
158Each section in a configuration file consists of a number of name and
159value pairs of the form \fBname=value\fR
160.PP
161The \fBname\fR string can contain any alphanumeric characters as well as
162a few punctuation symbols such as \fB.\fR \fB,\fR \fB;\fR and \fB_\fR.
163.PP
164The \fBvalue\fR string consists of the string following the \fB=\fR character
165until end of line with any leading and trailing white space removed.
166.PP
167The value string undergoes variable expansion. This can be done by
aac4ff6f 168including the form \fB$var\fR or \fB${var}\fR: this will substitute the value
984263bc 169of the named variable in the current section. It is also possible to
aac4ff6f
PA
170substitute a value from another section using the syntax \fB$section::name\fR
171or \fB${section::name}\fR. By using the form \fB$ENV::name\fR environment
984263bc 172variables can be substituted. It is also possible to assign values to
a561f9ff 173environment variables by using the name \fBENV::name\fR, this will work
984263bc
MD
174if the program looks up environment variables using the \fB\s-1CONF\s0\fR library
175instead of calling \fB\f(BIgetenv()\fB\fR directly.
176.PP
177It is possible to escape certain characters by using any kind of quote
178or the \fB\e\fR character. By making the last character of a line a \fB\e\fR
179a \fBvalue\fR string can be spread across multiple lines. In addition
180the sequences \fB\en\fR, \fB\er\fR, \fB\eb\fR and \fB\et\fR are recognized.
a561f9ff
SS
181.SH "OPENSSL LIBRARY CONFIGURATION"
182.IX Header "OPENSSL LIBRARY CONFIGURATION"
183In OpenSSL 0.9.7 and later applications can automatically configure certain
184aspects of OpenSSL using the master OpenSSL configuration file, or optionally
185an alternative configuration file. The \fBopenssl\fR utility includes this
186functionality: any sub command uses the master OpenSSL configuration file
187unless an option is used in the sub command to use an alternative configuration
188file.
189.PP
190To enable library configuration the default section needs to contain an
191appropriate line which points to the main configuration section. The default
192name is \fBopenssl_conf\fR which is used by the \fBopenssl\fR utility. Other
193applications may use an alternative name such as \fBmyapplicaton_conf\fR.
194.PP
195The configuration section should consist of a set of name value pairs which
196contain specific module configuration information. The \fBname\fR represents
197the name of the \fIconfiguration module\fR the meaning of the \fBvalue\fR is
198module specific: it may, for example, represent a further configuration
199section containing configuration module specific information. E.g.
200.PP
201.Vb 1
202\& openssl_conf = openssl_init
aac4ff6f
PA
203.Ve
204.PP
205.Vb 1
a561f9ff 206\& [openssl_init]
aac4ff6f
PA
207.Ve
208.PP
209.Vb 2
a561f9ff
SS
210\& oid_section = new_oids
211\& engines = engine_section
aac4ff6f
PA
212.Ve
213.PP
214.Vb 1
a561f9ff 215\& [new_oids]
aac4ff6f
PA
216.Ve
217.PP
218.Vb 1
a561f9ff 219\& ... new oids here ...
aac4ff6f
PA
220.Ve
221.PP
222.Vb 1
a561f9ff 223\& [engine_section]
aac4ff6f
PA
224.Ve
225.PP
226.Vb 1
a561f9ff
SS
227\& ... engine stuff here ...
228.Ve
229.PP
230Currently there are two configuration modules. One for \s-1ASN1\s0 objects another
231for \s-1ENGINE\s0 configuration.
232.Sh "\s-1ASN1\s0 \s-1OBJECT\s0 \s-1CONFIGURATION\s0 \s-1MODULE\s0"
233.IX Subsection "ASN1 OBJECT CONFIGURATION MODULE"
234This module has the name \fBoid_section\fR. The value of this variable points
235to a section containing name value pairs of OIDs: the name is the \s-1OID\s0 short
236and long name, the value is the numerical form of the \s-1OID\s0. Although some of
237the \fBopenssl\fR utility sub commands already have their own \s-1ASN1\s0 \s-1OBJECT\s0 section
238functionality not all do. By using the \s-1ASN1\s0 \s-1OBJECT\s0 configuration module
239\&\fBall\fR the \fBopenssl\fR utility sub commands can see the new objects as well
240as any compliant applications. For example:
241.PP
242.Vb 1
243\& [new_oids]
aac4ff6f
PA
244.Ve
245.PP
246.Vb 2
a561f9ff
SS
247\& some_new_oid = 1.2.3.4
248\& some_other_oid = 1.2.3.5
249.Ve
250.PP
251In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
252by a comma and the numerical \s-1OID\s0 form. For example:
253.PP
254.Vb 1
255\& shortName = some object long name, 1.2.3.4
256.Ve
257.Sh "\s-1ENGINE\s0 \s-1CONFIGURATION\s0 \s-1MODULE\s0"
258.IX Subsection "ENGINE CONFIGURATION MODULE"
259This \s-1ENGINE\s0 configuration module has the name \fBengines\fR. The value of this
260variable points to a section containing further \s-1ENGINE\s0 configuration
261information.
262.PP
263The section pointed to by \fBengines\fR is a table of engine names (though see
264\&\fBengine_id\fR below) and further sections containing configuration informations
265specific to each \s-1ENGINE\s0.
266.PP
267Each \s-1ENGINE\s0 specific section is used to set default algorithms, load
268dynamic, perform initialization and send ctrls. The actual operation performed
269depends on the \fIcommand\fR name which is the name of the name value pair. The
270currently supported commands are listed below.
271.PP
272For example:
273.PP
274.Vb 1
275\& [engine_section]
aac4ff6f
PA
276.Ve
277.PP
278.Vb 4
a561f9ff
SS
279\& # Configure ENGINE named "foo"
280\& foo = foo_section
281\& # Configure ENGINE named "bar"
282\& bar = bar_section
aac4ff6f
PA
283.Ve
284.PP
285.Vb 2
a561f9ff
SS
286\& [foo_section]
287\& ... foo ENGINE specific commands ...
aac4ff6f
PA
288.Ve
289.PP
290.Vb 2
a561f9ff
SS
291\& [bar_section]
292\& ... "bar" ENGINE specific commands ...
293.Ve
294.PP
295The command \fBengine_id\fR is used to give the \s-1ENGINE\s0 name. If used this
296command must be first. For example:
297.PP
298.Vb 3
299\& [engine_section]
300\& # This would normally handle an ENGINE named "foo"
301\& foo = foo_section
aac4ff6f
PA
302.Ve
303.PP
304.Vb 3
a561f9ff
SS
305\& [foo_section]
306\& # Override default name and use "myfoo" instead.
307\& engine_id = myfoo
308.Ve
309.PP
310The command \fBdynamic_path\fR loads and adds an \s-1ENGINE\s0 from the given path. It
311is equivalent to sending the ctrls \fB\s-1SO_PATH\s0\fR with the path argument followed
312by \fB\s-1LIST_ADD\s0\fR with value 2 and \fB\s-1LOAD\s0\fR to the dynamic \s-1ENGINE\s0. If this is
313not the required behaviour then alternative ctrls can be sent directly
314to the dynamic \s-1ENGINE\s0 using ctrl commands.
315.PP
316The command \fBinit\fR determines whether to initialize the \s-1ENGINE\s0. If the value
317is \fB0\fR the \s-1ENGINE\s0 will not be initialized, if \fB1\fR and attempt it made to
318initialized the \s-1ENGINE\s0 immediately. If the \fBinit\fR command is not present
319then an attempt will be made to initialize the \s-1ENGINE\s0 after all commands in
320its section have been processed.
321.PP
322The command \fBdefault_algorithms\fR sets the default algorithms an \s-1ENGINE\s0 will
323supply using the functions \fB\f(BIENGINE_set_default_string()\fB\fR
324.PP
325If the name matches none of the above command names it is assumed to be a
326ctrl command which is sent to the \s-1ENGINE\s0. The value of the command is the
327argument to the ctrl command. If the value is the string \fB\s-1EMPTY\s0\fR then no
328value is sent to the command.
329.PP
330For example:
331.PP
332.Vb 1
333\& [engine_section]
aac4ff6f
PA
334.Ve
335.PP
336.Vb 2
a561f9ff
SS
337\& # Configure ENGINE named "foo"
338\& foo = foo_section
aac4ff6f
PA
339.Ve
340.PP
341.Vb 9
a561f9ff
SS
342\& [foo_section]
343\& # Load engine from DSO
344\& dynamic_path = /some/path/fooengine.so
345\& # A foo specific ctrl.
346\& some_ctrl = some_value
347\& # Another ctrl that doesn't take a value.
348\& other_ctrl = EMPTY
349\& # Supply all default algorithms
350\& default_algorithms = ALL
351.Ve
984263bc
MD
352.SH "NOTES"
353.IX Header "NOTES"
354If a configuration file attempts to expand a variable that doesn't exist
355then an error is flagged and the file will not load. This can happen
356if an attempt is made to expand an environment variable that doesn't
a561f9ff
SS
357exist. For example in a previous version of OpenSSL the default OpenSSL
358master configuration file used the value of \fB\s-1HOME\s0\fR which may not be
359defined on non Unix systems and would cause an error.
984263bc
MD
360.PP
361This can be worked around by including a \fBdefault\fR section to provide
362a default value: then if the environment lookup fails the default value
363will be used instead. For this to work properly the default value must
364be defined earlier in the configuration file than the expansion. See
365the \fB\s-1EXAMPLES\s0\fR section for an example of how to do this.
366.PP
367If the same variable exists in the same section then all but the last
368value will be silently ignored. In certain circumstances such as with
369DNs the same field may occur multiple times. This is usually worked
370around by ignoring any characters before an initial \fB.\fR e.g.
371.PP
372.Vb 2
373\& 1.OU="My first OU"
374\& 2.OU="My Second OU"
375.Ve
376.SH "EXAMPLES"
377.IX Header "EXAMPLES"
378Here is a sample configuration file using some of the features
379mentioned above.
380.PP
381.Vb 1
382\& # This is the default section.
aac4ff6f
PA
383.Ve
384.PP
385.Vb 3
984263bc
MD
386\& HOME=/temp
387\& RANDFILE= ${ENV::HOME}/.rnd
388\& configdir=$ENV::HOME/config
aac4ff6f
PA
389.Ve
390.PP
391.Vb 1
984263bc 392\& [ section_one ]
aac4ff6f
PA
393.Ve
394.PP
395.Vb 1
984263bc 396\& # We are now in section one.
aac4ff6f
PA
397.Ve
398.PP
399.Vb 2
984263bc
MD
400\& # Quotes permit leading and trailing whitespace
401\& any = " any variable name "
aac4ff6f
PA
402.Ve
403.PP
404.Vb 3
984263bc
MD
405\& other = A string that can \e
406\& cover several lines \e
407\& by including \e\e characters
aac4ff6f
PA
408.Ve
409.PP
410.Vb 1
984263bc 411\& message = Hello World\en
aac4ff6f
PA
412.Ve
413.PP
414.Vb 1
984263bc 415\& [ section_two ]
aac4ff6f
PA
416.Ve
417.PP
418.Vb 1
984263bc
MD
419\& greeting = $section_one::message
420.Ve
a561f9ff 421.PP
984263bc
MD
422This next example shows how to expand environment variables safely.
423.PP
424Suppose you want a variable called \fBtmpfile\fR to refer to a
425temporary filename. The directory it is placed in can determined by
426the the \fB\s-1TEMP\s0\fR or \fB\s-1TMP\s0\fR environment variables but they may not be
427set to any value at all. If you just include the environment variable
428names and the variable doesn't exist then this will cause an error when
429an attempt is made to load the configuration file. By making use of the
430default section both values can be looked up with \fB\s-1TEMP\s0\fR taking
431priority and \fB/tmp\fR used if neither is defined:
432.PP
433.Vb 5
434\& TMP=/tmp
435\& # The above value is used if TMP isn't in the environment
436\& TEMP=$ENV::TMP
437\& # The above value is used if TEMP isn't in the environment
438\& tmpfile=${ENV::TEMP}/tmp.filename
439.Ve
440.SH "BUGS"
441.IX Header "BUGS"
442Currently there is no way to include characters using the octal \fB\ennn\fR
443form. Strings are all null terminated so nulls cannot form part of
444the value.
445.PP
446The escaping isn't quite right: if you want to use sequences like \fB\en\fR
447you can't use any quote escaping on the same line.
448.PP
449Files are loaded in a single pass. This means that an variable expansion
450will only work if the variables referenced are defined earlier in the
451file.
452.SH "SEE ALSO"
453.IX Header "SEE ALSO"
a561f9ff 454\&\fIx509\fR\|(1), \fIreq\fR\|(1), \fIca\fR\|(1)