Merge from vendor branch OPENSSL:
[dragonfly.git] / secure / usr.bin / openssl / man / config.1
CommitLineData
984263bc
MD
1.\" Automatically generated by Pod::Man version 1.15
2.\" Sun Jan 12 18:05:02 2003
3.\"
4.\" Standard preamble:
5.\" ======================================================================
6.de Sh \" Subsection heading
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
14.de Sp \" Vertical space (when we can't use .PP)
15.if t .sp .5v
16.if n .sp
17..
18.de Ip \" List item
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
24.de Vb \" Begin verbatim text
25.ft CW
26.nf
27.ne \\$1
28..
29.de Ve \" End verbatim text
30.ft R
31
32.fi
33..
34.\" Set up some character translations and predefined strings. \*(-- will
35.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
36.\" double quote, and \*(R" will give a right double quote. | will give a
37.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
38.\" to do unbreakable dashes and therefore won't be available. \*(C` and
39.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
40.tr \(*W-|\(bv\*(Tr
41.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
42.ie n \{\
43. ds -- \(*W-
44. ds PI pi
45. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
46. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
47. ds L" ""
48. ds R" ""
49. ds C` ""
50. ds C' ""
51'br\}
52.el\{\
53. ds -- \|\(em\|
54. ds PI \(*p
55. ds L" ``
56. ds R" ''
57'br\}
58.\"
59.\" If the F register is turned on, we'll generate index entries on stderr
60.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
61.\" index entries marked with X<> in POD. Of course, you'll have to process
62.\" the output yourself in some meaningful fashion.
63.if \nF \{\
64. de IX
65. tm Index:\\$1\t\\n%\t"\\$2"
66..
67. nr % 0
68. rr F
69.\}
70.\"
71.\" For nroff, turn off justification. Always turn off hyphenation; it
72.\" makes way too many mistakes in technical documents.
73.hy 0
74.if n .na
75.\"
76.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
77.\" Fear. Run. Save yourself. No user-serviceable parts.
78.bd B 3
79. \" fudge factors for nroff and troff
80.if n \{\
81. ds #H 0
82. ds #V .8m
83. ds #F .3m
84. ds #[ \f1
85. ds #] \fP
86.\}
87.if t \{\
88. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
89. ds #V .6m
90. ds #F 0
91. ds #[ \&
92. ds #] \&
93.\}
94. \" simple accents for nroff and troff
95.if n \{\
96. ds ' \&
97. ds ` \&
98. ds ^ \&
99. ds , \&
100. ds ~ ~
101. ds /
102.\}
103.if t \{\
104. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
105. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
106. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
107. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
108. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
109. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
110.\}
111. \" troff and (daisy-wheel) nroff accents
112.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
113.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
114.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
115.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
116.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
117.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
118.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
119.ds ae a\h'-(\w'a'u*4/10)'e
120.ds Ae A\h'-(\w'A'u*4/10)'E
121. \" corrections for vroff
122.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
123.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
124. \" for low resolution devices (crt and lpr)
125.if \n(.H>23 .if \n(.V>19 \
126\{\
127. ds : e
128. ds 8 ss
129. ds o a
130. ds d- d\h'-1'\(ga
131. ds D- D\h'-1'\(hy
132. ds th \o'bp'
133. ds Th \o'LP'
134. ds ae ae
135. ds Ae AE
136.\}
137.rm #[ #] #H #V #F C
138.\" ======================================================================
139.\"
140.IX Title "config 3"
141.TH config 3 "0.9.7" "2003-01-12" "OpenSSL"
142.UC
143.SH "NAME"
144config \- OpenSSL \s-1CONF\s0 library configuration files
145.SH "DESCRIPTION"
146.IX Header "DESCRIPTION"
147The OpenSSL \s-1CONF\s0 library can be used to read configuration files.
148It is used for the OpenSSL master configuration file \fBopenssl.cnf\fR
149and in a few other places like \fB\s-1SPKAC\s0\fR files and certificate extension
150files for the \fBx509\fR utility.
151.PP
152A configuration file is divided into a number of sections. Each section
153starts with a line \fB[ section_name ]\fR and ends when a new section is
154started or end of file is reached. A section name can consist of
155alphanumeric characters and underscores.
156.PP
157The first section of a configuration file is special and is referred
158to as the \fBdefault\fR section this is usually unnamed and is from the
159start of file until the first named section. When a name is being looked up
160it is first looked up in a named section (if any) and then the
161default section.
162.PP
163The environment is mapped onto a section called \fB\s-1ENV\s0\fR.
164.PP
165Comments can be included by preceding them with the \fB#\fR character
166.PP
167Each section in a configuration file consists of a number of name and
168value pairs of the form \fBname=value\fR
169.PP
170The \fBname\fR string can contain any alphanumeric characters as well as
171a few punctuation symbols such as \fB.\fR \fB,\fR \fB;\fR and \fB_\fR.
172.PP
173The \fBvalue\fR string consists of the string following the \fB=\fR character
174until end of line with any leading and trailing white space removed.
175.PP
176The value string undergoes variable expansion. This can be done by
177including the form \fB$var\fR or \fB${var}\fR: this will substitute the value
178of the named variable in the current section. It is also possible to
179substitute a value from another section using the syntax \fB$section::name\fR
180or \fB${section::name}\fR. By using the form \fB$ENV::name\fR environment
181variables can be substituted. It is also possible to assign values to
182environment variables by using the name \fB\s-1ENV:\s0:name\fR, this will work
183if the program looks up environment variables using the \fB\s-1CONF\s0\fR library
184instead of calling \fB\f(BIgetenv()\fB\fR directly.
185.PP
186It is possible to escape certain characters by using any kind of quote
187or the \fB\e\fR character. By making the last character of a line a \fB\e\fR
188a \fBvalue\fR string can be spread across multiple lines. In addition
189the sequences \fB\en\fR, \fB\er\fR, \fB\eb\fR and \fB\et\fR are recognized.
190.SH "NOTES"
191.IX Header "NOTES"
192If a configuration file attempts to expand a variable that doesn't exist
193then an error is flagged and the file will not load. This can happen
194if an attempt is made to expand an environment variable that doesn't
195exist. For example the default OpenSSL master configuration file used
196the value of \fB\s-1HOME\s0\fR which may not be defined on non Unix systems.
197.PP
198This can be worked around by including a \fBdefault\fR section to provide
199a default value: then if the environment lookup fails the default value
200will be used instead. For this to work properly the default value must
201be defined earlier in the configuration file than the expansion. See
202the \fB\s-1EXAMPLES\s0\fR section for an example of how to do this.
203.PP
204If the same variable exists in the same section then all but the last
205value will be silently ignored. In certain circumstances such as with
206DNs the same field may occur multiple times. This is usually worked
207around by ignoring any characters before an initial \fB.\fR e.g.
208.PP
209.Vb 2
210\& 1.OU="My first OU"
211\& 2.OU="My Second OU"
212.Ve
213.SH "EXAMPLES"
214.IX Header "EXAMPLES"
215Here is a sample configuration file using some of the features
216mentioned above.
217.PP
218.Vb 1
219\& # This is the default section.
220.Ve
221.Vb 3
222\& HOME=/temp
223\& RANDFILE= ${ENV::HOME}/.rnd
224\& configdir=$ENV::HOME/config
225.Ve
226.Vb 1
227\& [ section_one ]
228.Ve
229.Vb 1
230\& # We are now in section one.
231.Ve
232.Vb 2
233\& # Quotes permit leading and trailing whitespace
234\& any = " any variable name "
235.Ve
236.Vb 3
237\& other = A string that can \e
238\& cover several lines \e
239\& by including \e\e characters
240.Ve
241.Vb 1
242\& message = Hello World\en
243.Ve
244.Vb 1
245\& [ section_two ]
246.Ve
247.Vb 1
248\& greeting = $section_one::message
249.Ve
250This next example shows how to expand environment variables safely.
251.PP
252Suppose you want a variable called \fBtmpfile\fR to refer to a
253temporary filename. The directory it is placed in can determined by
254the the \fB\s-1TEMP\s0\fR or \fB\s-1TMP\s0\fR environment variables but they may not be
255set to any value at all. If you just include the environment variable
256names and the variable doesn't exist then this will cause an error when
257an attempt is made to load the configuration file. By making use of the
258default section both values can be looked up with \fB\s-1TEMP\s0\fR taking
259priority and \fB/tmp\fR used if neither is defined:
260.PP
261.Vb 5
262\& TMP=/tmp
263\& # The above value is used if TMP isn't in the environment
264\& TEMP=$ENV::TMP
265\& # The above value is used if TEMP isn't in the environment
266\& tmpfile=${ENV::TEMP}/tmp.filename
267.Ve
268.SH "BUGS"
269.IX Header "BUGS"
270Currently there is no way to include characters using the octal \fB\ennn\fR
271form. Strings are all null terminated so nulls cannot form part of
272the value.
273.PP
274The escaping isn't quite right: if you want to use sequences like \fB\en\fR
275you can't use any quote escaping on the same line.
276.PP
277Files are loaded in a single pass. This means that an variable expansion
278will only work if the variables referenced are defined earlier in the
279file.
280.SH "SEE ALSO"
281.IX Header "SEE ALSO"
282x509(1), req(1), ca(1)