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

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH CA 1 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 ca \- sample minimal CA application
 192 .SH "SYNOPSIS"
 193 \fBopenssl\fR \fBca\fR
 194 [\fB\-verbose\fR]
 195 [\fB\-config filename\fR]
 196 [\fB\-name section\fR]
 197 [\fB\-gencrl\fR]
 198 [\fB\-revoke file\fR]
 199 [\fB\-crl_reason reason\fR]
 200 [\fB\-crl_hold instruction\fR]
 201 [\fB\-crl_compromise time\fR]
 202 [\fB\-crl_CA_compromise time\fR]
 203 [\fB\-subj arg\fR]
 204 [\fB\-crldays days\fR]
 205 [\fB\-crlhours hours\fR]
 206 [\fB\-crlexts section\fR]
 207 [\fB\-startdate date\fR]
 208 [\fB\-enddate date\fR]
 209 [\fB\-days arg\fR]
 210 [\fB\-md arg\fR]
 211 [\fB\-policy arg\fR]
 212 [\fB\-keyfile arg\fR]
 213 [\fB\-key arg\fR]
 214 [\fB\-passin arg\fR]
 215 [\fB\-cert file\fR]
 216 [\fB\-in file\fR]
 217 [\fB\-out file\fR]
 218 [\fB\-notext\fR]
 219 [\fB\-outdir dir\fR]
 220 [\fB\-infiles\fR]
 221 [\fB\-spkac file\fR]
 222 [\fB\-ss_cert file\fR]
 223 [\fB\-preserveDN\fR]
 224 [\fB\-noemailDN\fR]
 225 [\fB\-batch\fR]
 226 [\fB\-msie_hack\fR]
 227 [\fB\-extensions section\fR]
 228 [\fB\-extfile section\fR]
 229 [\fB\-engine id\fR]
 230 .SH "DESCRIPTION"
 231 The \fBca\fR command is a minimal CA application. It can be used
 232 to sign certificate requests in a variety of forms and generate
 233 CRLs it also maintains a text database of issued certificates
 234 and their status.
 235 .PP
 236 The options descriptions will be divided into each purpose.
 237 .SH "CA OPTIONS"
 238 .Ip "\fB\-config filename\fR" 4
 239 specifies the configuration file to use.
 240 .Ip "\fB\-name section\fR" 4
 241 specifies the configuration file section to use (overrides
 242 \fBdefault_ca\fR in the \fBca\fR section).
 243 .Ip "\fB\-in filename\fR" 4
 244 an input filename containing a single certificate request to be
 245 signed by the \s-1CA\s0.
 246 .Ip "\fB\-ss_cert filename\fR" 4
 247 a single self signed certificate to be signed by the \s-1CA\s0.
 248 .Ip "\fB\-spkac filename\fR" 4
 249 a file containing a single Netscape signed public key and challenge
 250 and additional field values to be signed by the \s-1CA\s0. See the \fB\s-1SPKAC\s0 \s-1FORMAT\s0\fR
 251 section for information on the required format.
 252 .Ip "\fB\-infiles\fR" 4
 253 if present this should be the last option, all subsequent arguments
 254 are assumed to the the names of files containing certificate requests.
 255 .Ip "\fB\-out filename\fR" 4
 256 the output file to output certificates to. The default is standard
 257 output. The certificate details will also be printed out to this
 258 file.
 259 .Ip "\fB\-outdir directory\fR" 4
 260 the directory to output certificates to. The certificate will be
 261 written to a filename consisting of the serial number in hex with
 262 \*(L".pem\*(R" appended.
 263 .Ip "\fB\-cert\fR" 4
 264 the \s-1CA\s0 certificate file.
 265 .Ip "\fB\-keyfile filename\fR" 4
 266 the private key to sign requests with.
 267 .Ip "\fB\-key password\fR" 4
 268 the password used to encrypt the private key. Since on some
 269 systems the command line arguments are visible (e.g. Unix with
 270 the \*(L'ps\*(R' utility) this option should be used with caution.
 271 .Ip "\fB\-passin arg\fR" 4
 272 the key password source. For more information about the format of \fBarg\fR
 273 see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
 274 .Ip "\fB\-verbose\fR" 4
 275 this prints extra details about the operations being performed.
 276 .Ip "\fB\-notext\fR" 4
 277 don't output the text form of a certificate to the output file.
 278 .Ip "\fB\-startdate date\fR" 4
 279 this allows the start date to be explicitly set. The format of the
 280 date is \s-1YYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 UTCTime structure).
 281 .Ip "\fB\-enddate date\fR" 4
 282 this allows the expiry date to be explicitly set. The format of the
 283 date is \s-1YYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 UTCTime structure).
 284 .Ip "\fB\-days arg\fR" 4
 285 the number of days to certify the certificate for.
 286 .Ip "\fB\-md alg\fR" 4
 287 the message digest to use. Possible values include md5, sha1 and mdc2.
 288 This option also applies to CRLs.
 289 .Ip "\fB\-policy arg\fR" 4
 290 this option defines the \s-1CA\s0 \*(L"policy\*(R" to use. This is a section in
 291 the configuration file which decides which fields should be mandatory
 292 or match the \s-1CA\s0 certificate. Check out the \fB\s-1POLICY\s0 \s-1FORMAT\s0\fR section
 293 for more information.
 294 .Ip "\fB\-msie_hack\fR" 4
 295 this is a legacy option to make \fBca\fR work with very old versions of
 296 the \s-1IE\s0 certificate enrollment control \*(L"certenr3\*(R". It used UniversalStrings
 297 for almost everything. Since the old control has various security bugs
 298 its use is strongly discouraged. The newer control \*(L"Xenroll\*(R" does not
 299 need this option.
 300 .Ip "\fB\-preserveDN\fR" 4
 301 Normally the \s-1DN\s0 order of a certificate is the same as the order of the
 302 fields in the relevant policy section. When this option is set the order
 303 is the same as the request. This is largely for compatibility with the
 304 older \s-1IE\s0 enrollment control which would only accept certificates if their
 305 DNs match the order of the request. This is not needed for Xenroll.
 306 .Ip "\fB\-noemailDN\fR" 4
 307 The \s-1DN\s0 of a certificate can contain the \s-1EMAIL\s0 field if present in the
 308 request \s-1DN\s0, however it is good policy just having the e-mail set into
 309 the altName extension of the certificate. When this option is set the
 310 \s-1EMAIL\s0 field is removed from the certificate\*(R' subject and set only in
 311 the, eventually present, extensions. The \fBemail_in_dn\fR keyword can be
 312 used in the configuration file to enable this behaviour.
 313 .Ip "\fB\-batch\fR" 4
 314 this sets the batch mode. In this mode no questions will be asked
 315 and all certificates will be certified automatically.
 316 .Ip "\fB\-extensions section\fR" 4
 317 the section of the configuration file containing certificate extensions
 318 to be added when a certificate is issued (defaults to \fBx509_extensions\fR
 319 unless the \fB\-extfile\fR option is used). If no extension section is
 320 present then, a V1 certificate is created. If the extension section
 321 is present (even if it is empty), then a V3 certificate is created.
 322 .Ip "\fB\-extfile file\fR" 4
 323 an additional configuration file to read certificate extensions from
 324 (using the default section unless the \fB\-extensions\fR option is also
 325 used).
 326 .Ip "\fB\-engine id\fR" 4
 327 specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
 328 to attempt to obtain a functional reference to the specified engine,
 329 thus initialising it if needed. The engine will then be set as the default
 330 for all available algorithms.
 331 .SH "CRL OPTIONS"
 332 .Ip "\fB\-gencrl\fR" 4
 333 this option generates a \s-1CRL\s0 based on information in the index file.
 334 .Ip "\fB\-crldays num\fR" 4
 335 the number of days before the next \s-1CRL\s0 is due. That is the days from
 336 now to place in the \s-1CRL\s0 nextUpdate field.
 337 .Ip "\fB\-crlhours num\fR" 4
 338 the number of hours before the next \s-1CRL\s0 is due.
 339 .Ip "\fB\-revoke filename\fR" 4
 340 a filename containing a certificate to revoke.
 341 .Ip "\fB\-crl_reason reason\fR" 4
 342 revocation reason, where \fBreason\fR is one of: \fBunspecified\fR, \fBkeyCompromise\fR,
 343 \fBCACompromise\fR, \fBaffiliationChanged\fR, \fBsuperseded\fR, \fBcessationOfOperation\fR,
 344 \fBcertificateHold\fR or \fBremoveFromCRL\fR. The matching of \fBreason\fR is case
 345 insensitive. Setting any revocation reason will make the \s-1CRL\s0 v2.
 346 .Sp
 347 In practive \fBremoveFromCRL\fR is not particularly useful because it is only used
 348 in delta CRLs which are not currently implemented.
 349 .Ip "\fB\-crl_hold instruction\fR" 4
 350 This sets the \s-1CRL\s0 revocation reason code to \fBcertificateHold\fR and the hold
 351 instruction to \fBinstruction\fR which must be an \s-1OID\s0. Although any \s-1OID\s0 can be
 352 used only \fBholdInstructionNone\fR (the use of which is discouraged by \s-1RFC2459\s0)
 353 \fBholdInstructionCallIssuer\fR or \fBholdInstructionReject\fR will normally be used.
 354 .Ip "\fB\-crl_compromise time\fR" 4
 355 This sets the revocation reason to \fBkeyCompromise\fR and the compromise time to
 356 \fBtime\fR. \fBtime\fR should be in GeneralizedTime format that is \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
 357 .Ip "\fB\-crl_CA_compromise time\fR" 4
 358 This is the same as \fBcrl_compromise\fR except the revocation reason is set to
 359 \fBCACompromise\fR.
 360 .Ip "\fB\-subj arg\fR" 4
 361 supersedes subject name given in the request.
 362 The arg must be formatted as \fI/type0=value0/type1=value1/type2=...\fR,
 363 characters may be escaped by \e (backslash), no spaces are skipped.
 364 .Ip "\fB\-crlexts section\fR" 4
 365 the section of the configuration file containing \s-1CRL\s0 extensions to
 366 include. If no \s-1CRL\s0 extension section is present then a V1 \s-1CRL\s0 is
 367 created, if the \s-1CRL\s0 extension section is present (even if it is
 368 empty) then a V2 \s-1CRL\s0 is created. The \s-1CRL\s0 extensions specified are
 369 \s-1CRL\s0 extensions and \fBnot\fR \s-1CRL\s0 entry extensions.  It should be noted
 370 that some software (for example Netscape) can't handle V2 CRLs.
 371 .SH "CONFIGURATION FILE OPTIONS"
 372 The section of the configuration file containing options for \fBca\fR
 373 is found as follows: If the \fB\-name\fR command line option is used,
 374 then it names the section to be used. Otherwise the section to
 375 be used must be named in the \fBdefault_ca\fR option of the \fBca\fR section
 376 of the configuration file (or in the default section of the
 377 configuration file). Besides \fBdefault_ca\fR, the following options are
 378 read directly from the \fBca\fR section:
 379  RANDFILE
 380  preserve
 381  msie_hack
 382 With the exception of \fBRANDFILE\fR, this is probably a bug and may
 383 change in future releases.
 384 .PP
 385 Many of the configuration file options are identical to command line
 386 options. Where the option is present in the configuration file
 387 and the command line the command line value is used. Where an
 388 option is described as mandatory then it must be present in
 389 the configuration file or the command line equivalent (if
 390 any) used.
 391 .Ip "\fBoid_file\fR" 4
 392 This specifies a file containing additional \fB\s-1OBJECT\s0 \s-1IDENTIFIERS\s0\fR.
 393 Each line of the file should consist of the numerical form of the
 394 object identifier followed by white space then the short name followed
 395 by white space and finally the long name.
 396 .Ip "\fBoid_section\fR" 4
 397 This specifies a section in the configuration file containing extra
 398 object identifiers. Each line should consist of the short name of the
 399 object identifier followed by \fB=\fR and the numerical form. The short
 400 and long names are the same when this option is used.
 401 .Ip "\fBnew_certs_dir\fR" 4
 402 the same as the \fB\-outdir\fR command line option. It specifies
 403 the directory where new certificates will be placed. Mandatory.
 404 .Ip "\fBcertificate\fR" 4
 405 the same as \fB\-cert\fR. It gives the file containing the \s-1CA\s0
 406 certificate. Mandatory.
 407 .Ip "\fBprivate_key\fR" 4
 408 same as the \fB\-keyfile\fR option. The file containing the
 409 \s-1CA\s0 private key. Mandatory.
 410 .Ip "\fB\s-1RANDFILE\s0\fR" 4
 411 a file used to read and write random number seed information, or
 412 an \s-1EGD\s0 socket (see RAND_egd(3)).
 413 .Ip "\fBdefault_days\fR" 4
 414 the same as the \fB\-days\fR option. The number of days to certify
 415 a certificate for.
 416 .Ip "\fBdefault_startdate\fR" 4
 417 the same as the \fB\-startdate\fR option. The start date to certify
 418 a certificate for. If not set the current time is used.
 419 .Ip "\fBdefault_enddate\fR" 4
 420 the same as the \fB\-enddate\fR option. Either this option or
 421 \fBdefault_days\fR (or the command line equivalents) must be
 422 present.
 423 .Ip "\fBdefault_crl_hours default_crl_days\fR" 4
 424 the same as the \fB\-crlhours\fR and the \fB\-crldays\fR options. These
 425 will only be used if neither command line option is present. At
 426 least one of these must be present to generate a \s-1CRL\s0.
 427 .Ip "\fBdefault_md\fR" 4
 428 the same as the \fB\-md\fR option. The message digest to use. Mandatory.
 429 .Ip "\fBdatabase\fR" 4
 430 the text database file to use. Mandatory. This file must be present
 431 though initially it will be empty.
 432 .Ip "\fBserial\fR" 4
 433 a text file containing the next serial number to use in hex. Mandatory.
 434 This file must be present and contain a valid serial number.
 435 .Ip "\fBx509_extensions\fR" 4
 436 the same as \fB\-extensions\fR.
 437 .Ip "\fBcrl_extensions\fR" 4
 438 the same as \fB\-crlexts\fR.
 439 .Ip "\fBpreserve\fR" 4
 440 the same as \fB\-preserveDN\fR
 441 .Ip "\fBemail_in_dn\fR" 4
 442 the same as \fB\-noemailDN\fR. If you want the \s-1EMAIL\s0 field to be removed
 443 from the \s-1DN\s0 of the certificate simply set this to \*(L'no\*(R'. If not present
 444 the default is to allow for the \s-1EMAIL\s0 filed in the certificate's \s-1DN\s0.
 445 .Ip "\fBmsie_hack\fR" 4
 446 the same as \fB\-msie_hack\fR
 447 .Ip "\fBpolicy\fR" 4
 448 the same as \fB\-policy\fR. Mandatory. See the \fB\s-1POLICY\s0 \s-1FORMAT\s0\fR section
 449 for more information.
 450 .Ip "\fBnameopt\fR, \fBcertopt\fR" 4
 451 these options allow the format used to display the certificate details
 452 when asking the user to confirm signing. All the options supported by
 453 the \fBx509\fR utilities \fB\-nameopt\fR and \fB\-certopt\fR switches can be used
 454 here, except the \fBno_signame\fR and \fBno_sigdump\fR are permanently set
 455 and cannot be disabled (this is because the certificate signature cannot
 456 be displayed because the certificate has not been signed at this point).
 457 .Sp
 458 For convenience the values \fBca_default\fR are accepted by both to produce
 459 a reasonable output.
 460 .Sp
 461 If neither option is present the format used in earlier versions of
 462 OpenSSL is used. Use of the old format is \fBstrongly\fR discouraged because
 463 it only displays fields mentioned in the \fBpolicy\fR section, mishandles
 464 multicharacter string types and does not display extensions.
 465 .Ip "\fBcopy_extensions\fR" 4
 466 determines how extensions in certificate requests should be handled.
 467 If set to \fBnone\fR or this option is not present then extensions are
 468 ignored and not copied to the certificate. If set to \fBcopy\fR then any
 469 extensions present in the request that are not already present are copied
 470 to the certificate. If set to \fBcopyall\fR then all extensions in the
 471 request are copied to the certificate: if the extension is already present
 472 in the certificate it is deleted first. See the \fB\s-1WARNINGS\s0\fR section before
 473 using this option.
 474 .Sp
 475 The main use of this option is to allow a certificate request to supply
 476 values for certain extensions such as subjectAltName.
 477 .SH "POLICY FORMAT"
 478 The policy section consists of a set of variables corresponding to
 479 certificate DN fields. If the value is \*(L"match\*(R" then the field value
 480 must match the same field in the CA certificate. If the value is
 481 \*(L"supplied\*(R" then it must be present. If the value is \*(L"optional\*(R" then
 482 it may be present. Any fields not mentioned in the policy section
 483 are silently deleted, unless the \fB\-preserveDN\fR option is set but
 484 this can be regarded more of a quirk than intended behaviour.
 485 .SH "SPKAC FORMAT"
 486 The input to the \fB\-spkac\fR command line option is a Netscape
 487 signed public key and challenge. This will usually come from
 488 the \fBKEYGEN\fR tag in an HTML form to create a new private key.
 489 It is however possible to create SPKACs using the \fBspkac\fR utility.
 490 .PP
 491 The file should contain the variable SPKAC set to the value of
 492 the SPKAC and also the required DN components as name value pairs.
 493 If you need to include the same component twice then it can be
 494 preceded by a number and a \*(L'.\*(R'.
 495 .SH "EXAMPLES"
 496 Note: these examples assume that the \fBca\fR directory structure is
 497 already set up and the relevant files already exist. This usually
 498 involves creating a CA certificate and private key with \fBreq\fR, a
 499 serial number file and an empty index file and placing them in
 500 the relevant directories.
 501 .PP
 502 To use the sample configuration file below the directories demoCA,
 503 demoCA/private and demoCA/newcerts would be created. The CA
 504 certificate would be copied to demoCA/cacert.pem and its private
 505 key to demoCA/private/cakey.pem. A file demoCA/serial would be
 506 created containing for example \*(L"01\*(R" and the empty index file
 507 demoCA/index.txt.
 508 .PP
 509 Sign a certificate request:
 510 .PP
 511 .Vb 1
 512 \& openssl ca -in req.pem -out newcert.pem
 513 .Ve
 514 Sign a certificate request, using CA extensions:
 515 .PP
 516 .Vb 1
 517 \& openssl ca -in req.pem -extensions v3_ca -out newcert.pem
 518 .Ve
 519 Generate a CRL
 520 .PP
 521 .Vb 1
 522 \& openssl ca -gencrl -out crl.pem
 523 .Ve
 524 Sign several requests:
 525 .PP
 526 .Vb 1
 527 \& openssl ca -infiles req1.pem req2.pem req3.pem
 528 .Ve
 529 Certify a Netscape SPKAC:
 530 .PP
 531 .Vb 1
 532 \& openssl ca -spkac spkac.txt
 533 .Ve
 534 A sample SPKAC file (the SPKAC line has been truncated for clarity):
 535 .PP
 536 .Vb 5
 537 \& SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
 538 \& CN=Steve Test
 539 \& emailAddress=steve@openssl.org
 540 \& 0.OU=OpenSSL Group
 541 \& 1.OU=Another Group
 542 .Ve
 543 A sample configuration file with the relevant sections for \fBca\fR:
 544 .PP
 545 .Vb 4
 546 \& [ ca ]
 547 \& default_ca      = CA_default            # The default ca section
 548 \&
 549 \& [ CA_default ]
 550 .Ve
 551 .Vb 12
 552 \& dir            = ./demoCA              # top dir
 553 \& database       = $dir/index.txt        # index file.
 554 \& new_certs_dir  = $dir/newcerts         # new certs dir
 555 \&
 556 \& certificate    = $dir/cacert.pem       # The CA cert
 557 \& serial         = $dir/serial           # serial no file
 558 \& private_key    = $dir/private/cakey.pem# CA private key
 559 \& RANDFILE       = $dir/private/.rand    # random number file
 560 \&
 561 \& default_days   = 365                   # how long to certify for
 562 \& default_crl_days= 30                   # how long before next CRL
 563 \& default_md     = md5                   # md to use
 564 .Ve
 565 .Vb 2
 566 \& policy         = policy_any            # default policy
 567 \& email_in_dn    = no                    # Don't add the email into cert DN
 568 .Ve
 569 .Vb 3
 570 \& nameopt        = ca_default            # Subject name display option
 571 \& certopt        = ca_default            # Certificate display option
 572 \& copy_extensions = none                 # Don't copy extensions from request
 573 .Ve
 574 .Vb 7
 575 \& [ policy_any ]
 576 \& countryName            = supplied
 577 \& stateOrProvinceName    = optional
 578 \& organizationName       = optional
 579 \& organizationalUnitName = optional
 580 \& commonName             = supplied
 581 \& emailAddress           = optional
 582 .Ve
 583 .SH "FILES"
 584 Note: the location of all files can change either by compile time options,
 585 configuration file entries, environment variables or command line options.
 586 The values below reflect the default values.
 587 .PP
 588 .Vb 10
 589 \& /usr/local/ssl/lib/openssl.cnf - master configuration file
 590 \& ./demoCA                       - main CA directory
 591 \& ./demoCA/cacert.pem            - CA certificate
 592 \& ./demoCA/private/cakey.pem     - CA private key
 593 \& ./demoCA/serial                - CA serial number file
 594 \& ./demoCA/serial.old            - CA serial number backup file
 595 \& ./demoCA/index.txt             - CA text database file
 596 \& ./demoCA/index.txt.old         - CA text database backup file
 597 \& ./demoCA/certs                 - certificate output file
 598 \& ./demoCA/.rnd                  - CA random seed information
 599 .Ve
 600 .SH "ENVIRONMENT VARIABLES"
 601 \fBOPENSSL_CONF\fR reflects the location of master configuration file it can
 602 be overridden by the \fB\-config\fR command line option.
 603 .SH "RESTRICTIONS"
 604 The text database index file is a critical part of the process and
 605 if corrupted it can be difficult to fix. It is theoretically possible
 606 to rebuild the index file from all the issued certificates and a current
 607 CRL: however there is no option to do this.
 608 .PP
 609 V2 CRL features like delta CRL support and CRL numbers are not currently
 610 supported.
 611 .PP
 612 Although several requests can be input and handled at once it is only
 613 possible to include one SPKAC or self signed certificate.
 614 .SH "BUGS"
 615 The use of an in memory text database can cause problems when large
 616 numbers of certificates are present because, as the name implies
 617 the database has to be kept in memory.
 618 .PP
 619 It is not possible to certify two certificates with the same DN: this
 620 is a side effect of how the text database is indexed and it cannot easily
 621 be fixed without introducing other problems. Some S/MIME clients can use
 622 two certificates with the same DN for separate signing and encryption
 623 keys.
 624 .PP
 625 The \fBca\fR command really needs rewriting or the required functionality
 626 exposed at either a command or interface level so a more friendly utility
 627 (perl script or GUI) can handle things properly. The scripts \fBCA.sh\fR and
 628 \fBCA.pl\fR help a little but not very much.
 629 .PP
 630 Any fields in a request that are not present in a policy are silently
 631 deleted. This does not happen if the \fB\-preserveDN\fR option is used. To
 632 enforce the absence of the EMAIL field within the DN, as suggested by
 633 RFCs, regardless the contents of the request\*(R' subject the \fB\-noemailDN\fR
 634 option can be used. The behaviour should be more friendly and
 635 configurable.
 636 .PP
 637 Cancelling some commands by refusing to certify a certificate can
 638 create an empty file.
 639 .SH "WARNINGS"
 640 The \fBca\fR command is quirky and at times downright unfriendly.
 641 .PP
 642 The \fBca\fR utility was originally meant as an example of how to do things
 643 in a CA. It was not supposed to be used as a full blown CA itself:
 644 nevertheless some people are using it for this purpose.
 645 .PP
 646 The \fBca\fR command is effectively a single user command: no locking is
 647 done on the various files and attempts to run more than one \fBca\fR command
 648 on the same database can have unpredictable results.
 649 .PP
 650 The \fBcopy_extensions\fR option should be used with caution. If care is
 651 not taken then it can be a security risk. For example if a certificate
 652 request contains a basicConstraints extension with CA:TRUE and the
 653 \fBcopy_extensions\fR value is set to \fBcopyall\fR and the user does not spot
 654 this when the certificate is displayed then this will hand the requestor
 655 a valid CA certificate.
 656 .PP
 657 This situation can be avoided by setting \fBcopy_extensions\fR to \fBcopy\fR
 658 and including basicConstraints with CA:FALSE in the configuration file.
 659 Then if the request contains a basicConstraints extension it will be
 660 ignored.
 661 .PP
 662 It is advisable to also include values for other extensions such
 663 as \fBkeyUsage\fR to prevent a request supplying its own values.
 664 .PP
 665 Additional restrictions can be placed on the CA certificate itself.
 666 For example if the CA certificate has:
 667 .PP
 668 .Vb 1
 669 \& basicConstraints = CA:TRUE, pathlen:0
 670 .Ve
 671 then even if a certificate is issued with CA:TRUE it will not be valid.
 672 .SH "SEE ALSO"
 673 req(1), spkac(1), x509(1), CA.pl(1),
 674 config(5)
 675
 676 .rn }` ''
 677 .IX Title "CA 1"
 678 .IX Name "ca - sample minimal CA application"
 679
 680 .IX Header "NAME"
 681
 682 .IX Header "SYNOPSIS"
 683
 684 .IX Header "DESCRIPTION"
 685
 686 .IX Header "CA OPTIONS"
 687
 688 .IX Item "\fB\-config filename\fR"
 689
 690 .IX Item "\fB\-name section\fR"
 691
 692 .IX Item "\fB\-in filename\fR"
 693
 694 .IX Item "\fB\-ss_cert filename\fR"
 695
 696 .IX Item "\fB\-spkac filename\fR"
 697
 698 .IX Item "\fB\-infiles\fR"
 699
 700 .IX Item "\fB\-out filename\fR"
 701
 702 .IX Item "\fB\-outdir directory\fR"
 703
 704 .IX Item "\fB\-cert\fR"
 705
 706 .IX Item "\fB\-keyfile filename\fR"
 707
 708 .IX Item "\fB\-key password\fR"
 709
 710 .IX Item "\fB\-passin arg\fR"
 711
 712 .IX Item "\fB\-verbose\fR"
 713
 714 .IX Item "\fB\-notext\fR"
 715
 716 .IX Item "\fB\-startdate date\fR"
 717
 718 .IX Item "\fB\-enddate date\fR"
 719
 720 .IX Item "\fB\-days arg\fR"
 721
 722 .IX Item "\fB\-md alg\fR"
 723
 724 .IX Item "\fB\-policy arg\fR"
 725
 726 .IX Item "\fB\-msie_hack\fR"
 727
 728 .IX Item "\fB\-preserveDN\fR"
 729
 730 .IX Item "\fB\-noemailDN\fR"
 731
 732 .IX Item "\fB\-batch\fR"
 733
 734 .IX Item "\fB\-extensions section\fR"
 735
 736 .IX Item "\fB\-extfile file\fR"
 737
 738 .IX Item "\fB\-engine id\fR"
 739
 740 .IX Header "CRL OPTIONS"
 741
 742 .IX Item "\fB\-gencrl\fR"
 743
 744 .IX Item "\fB\-crldays num\fR"
 745
 746 .IX Item "\fB\-crlhours num\fR"
 747
 748 .IX Item "\fB\-revoke filename\fR"
 749
 750 .IX Item "\fB\-crl_reason reason\fR"
 751
 752 .IX Item "\fB\-crl_hold instruction\fR"
 753
 754 .IX Item "\fB\-crl_compromise time\fR"
 755
 756 .IX Item "\fB\-crl_CA_compromise time\fR"
 757
 758 .IX Item "\fB\-subj arg\fR"
 759
 760 .IX Item "\fB\-crlexts section\fR"
 761
 762 .IX Header "CONFIGURATION FILE OPTIONS"
 763
 764 .IX Item "\fBoid_file\fR"
 765
 766 .IX Item "\fBoid_section\fR"
 767
 768 .IX Item "\fBnew_certs_dir\fR"
 769
 770 .IX Item "\fBcertificate\fR"
 771
 772 .IX Item "\fBprivate_key\fR"
 773
 774 .IX Item "\fB\s-1RANDFILE\s0\fR"
 775
 776 .IX Item "\fBdefault_days\fR"
 777
 778 .IX Item "\fBdefault_startdate\fR"
 779
 780 .IX Item "\fBdefault_enddate\fR"
 781
 782 .IX Item "\fBdefault_crl_hours default_crl_days\fR"
 783
 784 .IX Item "\fBdefault_md\fR"
 785
 786 .IX Item "\fBdatabase\fR"
 787
 788 .IX Item "\fBserial\fR"
 789
 790 .IX Item "\fBx509_extensions\fR"
 791
 792 .IX Item "\fBcrl_extensions\fR"
 793
 794 .IX Item "\fBpreserve\fR"
 795
 796 .IX Item "\fBemail_in_dn\fR"
 797
 798 .IX Item "\fBmsie_hack\fR"
 799
 800 .IX Item "\fBpolicy\fR"
 801
 802 .IX Item "\fBnameopt\fR, \fBcertopt\fR"
 803
 804 .IX Item "\fBcopy_extensions\fR"
 805
 806 .IX Header "POLICY FORMAT"
 807
 808 .IX Header "SPKAC FORMAT"
 809
 810 .IX Header "EXAMPLES"
 811
 812 .IX Header "FILES"
 813
 814 .IX Header "ENVIRONMENT VARIABLES"
 815
 816 .IX Header "RESTRICTIONS"
 817
 818 .IX Header "BUGS"
 819
 820 .IX Header "WARNINGS"
 821
 822 .IX Header "SEE ALSO"
 823