secure/usr.bin/openssl/man/config.1

   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"
 144 config \- OpenSSL \s-1CONF\s0 library configuration files
 145 .SH "DESCRIPTION"
 146 .IX Header "DESCRIPTION"
 147 The OpenSSL \s-1CONF\s0 library can be used to read configuration files.
 148 It is used for the OpenSSL master configuration file \fBopenssl.cnf\fR
 149 and in a few other places like \fB\s-1SPKAC\s0\fR files and certificate extension
 150 files for the \fBx509\fR utility.
 151 .PP
 152 A configuration file is divided into a number of sections. Each section
 153 starts with a line \fB[ section_name ]\fR and ends when a new section is
 154 started or end of file is reached. A section name can consist of
 155 alphanumeric characters and underscores.
 156 .PP
 157 The first section of a configuration file is special and is referred
 158 to as the \fBdefault\fR section this is usually unnamed and is from the
 159 start of file until the first named section. When a name is being looked up
 160 it is first looked up in a named section (if any) and then the
 161 default section.
 162 .PP
 163 The environment is mapped onto a section called \fB\s-1ENV\s0\fR.
 164 .PP
 165 Comments can be included by preceding them with the \fB#\fR character
 166 .PP
 167 Each section in a configuration file consists of a number of name and
 168 value pairs of the form \fBname=value\fR
 169 .PP
 170 The \fBname\fR string can contain any alphanumeric characters as well as
 171 a few punctuation symbols such as \fB.\fR \fB,\fR \fB;\fR and \fB_\fR.
 172 .PP
 173 The \fBvalue\fR string consists of the string following the \fB=\fR character
 174 until end of line with any leading and trailing white space removed.
 175 .PP
 176 The value string undergoes variable expansion. This can be done by
 177 including the form \fB$var\fR or \fB${var}\fR: this will substitute the value
 178 of the named variable in the current section. It is also possible to
 179 substitute a value from another section using the syntax \fB$section::name\fR
 180 or \fB${section::name}\fR. By using the form \fB$ENV::name\fR environment
 181 variables can be substituted. It is also possible to assign values to
 182 environment variables by using the name \fB\s-1ENV:\s0:name\fR, this will work
 183 if the program looks up environment variables using the \fB\s-1CONF\s0\fR library
 184 instead of calling \fB\f(BIgetenv()\fB\fR directly.
 185 .PP
 186 It is possible to escape certain characters by using any kind of quote
 187 or the \fB\e\fR character. By making the last character of a line a \fB\e\fR
 188 a \fBvalue\fR string can be spread across multiple lines. In addition
 189 the sequences \fB\en\fR, \fB\er\fR, \fB\eb\fR and \fB\et\fR are recognized.
 190 .SH "NOTES"
 191 .IX Header "NOTES"
 192 If a configuration file attempts to expand a variable that doesn't exist
 193 then an error is flagged and the file will not load. This can happen
 194 if an attempt is made to expand an environment variable that doesn't
 195 exist. For example the default OpenSSL master configuration file used
 196 the value of \fB\s-1HOME\s0\fR which may not be defined on non Unix systems.
 197 .PP
 198 This can be worked around by including a \fBdefault\fR section to provide
 199 a default value: then if the environment lookup fails the default value
 200 will be used instead. For this to work properly the default value must
 201 be defined earlier in the configuration file than the expansion. See
 202 the \fB\s-1EXAMPLES\s0\fR section for an example of how to do this.
 203 .PP
 204 If the same variable exists in the same section then all but the last
 205 value will be silently ignored. In certain circumstances such as with
 206 DNs the same field may occur multiple times. This is usually worked
 207 around 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"
 215 Here is a sample configuration file using some of the features
 216 mentioned 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
 250 This next example shows how to expand environment variables safely.
 251 .PP
 252 Suppose you want a variable called \fBtmpfile\fR to refer to a
 253 temporary filename. The directory it is placed in can determined by
 254 the the \fB\s-1TEMP\s0\fR or \fB\s-1TMP\s0\fR environment variables but they may not be
 255 set to any value at all. If you just include the environment variable
 256 names and the variable doesn't exist then this will cause an error when
 257 an attempt is made to load the configuration file. By making use of the
 258 default section both values can be looked up with \fB\s-1TEMP\s0\fR taking
 259 priority 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"
 270 Currently there is no way to include characters using the octal \fB\ennn\fR
 271 form. Strings are all null terminated so nulls cannot form part of
 272 the value.
 273 .PP
 274 The escaping isn't quite right: if you want to use sequences like \fB\en\fR
 275 you can't use any quote escaping on the same line.
 276 .PP
 277 Files are loaded in a single pass. This means that an variable expansion
 278 will only work if the variables referenced are defined earlier in the
 279 file.
 280 .SH "SEE ALSO"
 281 .IX Header "SEE ALSO"
 282 x509(1), req(1), ca(1)