Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / usr.bin / openssl / man / ca.1
CommitLineData
e3cdf75b
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
e3cdf75b 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
e3cdf75b 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
e3cdf75b 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
e3cdf75b 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
e3cdf75b
JR
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'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
e3cdf75b
JR
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' '
984263bc
MD
62'br\}
63.el\{\
e3cdf75b
JR
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
984263bc 79'br\}
e3cdf75b
JR
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"
984263bc 92..
e3cdf75b
JR
93.nr % 0
94.rr F
984263bc 95.\}
e3cdf75b
JR
96.TH CA 1 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
e3cdf75b
JR
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
984263bc 112.bd B 3
e3cdf75b 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
e3cdf75b
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
e3cdf75b
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
e3cdf75b 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
e3cdf75b
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
e3cdf75b
JR
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'
984263bc 150.\}
e3cdf75b 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
e3cdf75b
JR
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'\*(#]
984263bc
MD
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
e3cdf75b
JR
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
984263bc
MD
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'
e3cdf75b 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
e3cdf75b
JR
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
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
e3cdf75b 191ca \- sample minimal CA application
984263bc 192.SH "SYNOPSIS"
e3cdf75b 193\fBopenssl\fR \fBca\fR
984263bc
MD
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"
e3cdf75b 231The \fBca\fR command is a minimal CA application. It can be used
984263bc
MD
232to sign certificate requests in a variety of forms and generate
233CRLs it also maintains a text database of issued certificates
234and their status.
235.PP
236The options descriptions will be divided into each purpose.
237.SH "CA OPTIONS"
984263bc 238.Ip "\fB\-config filename\fR" 4
984263bc
MD
239specifies the configuration file to use.
240.Ip "\fB\-name section\fR" 4
984263bc 241specifies the configuration file section to use (overrides
e3cdf75b 242\fBdefault_ca\fR in the \fBca\fR section).
984263bc 243.Ip "\fB\-in filename\fR" 4
984263bc
MD
244an input filename containing a single certificate request to be
245signed by the \s-1CA\s0.
246.Ip "\fB\-ss_cert filename\fR" 4
984263bc
MD
247a single self signed certificate to be signed by the \s-1CA\s0.
248.Ip "\fB\-spkac filename\fR" 4
984263bc
MD
249a file containing a single Netscape signed public key and challenge
250and additional field values to be signed by the \s-1CA\s0. See the \fB\s-1SPKAC\s0 \s-1FORMAT\s0\fR
251section for information on the required format.
252.Ip "\fB\-infiles\fR" 4
984263bc
MD
253if present this should be the last option, all subsequent arguments
254are assumed to the the names of files containing certificate requests.
255.Ip "\fB\-out filename\fR" 4
984263bc
MD
256the output file to output certificates to. The default is standard
257output. The certificate details will also be printed out to this
258file.
259.Ip "\fB\-outdir directory\fR" 4
984263bc
MD
260the directory to output certificates to. The certificate will be
261written to a filename consisting of the serial number in hex with
e3cdf75b 262\*(L".pem\*(R" appended.
984263bc 263.Ip "\fB\-cert\fR" 4
984263bc
MD
264the \s-1CA\s0 certificate file.
265.Ip "\fB\-keyfile filename\fR" 4
984263bc
MD
266the private key to sign requests with.
267.Ip "\fB\-key password\fR" 4
984263bc
MD
268the password used to encrypt the private key. Since on some
269systems the command line arguments are visible (e.g. Unix with
e3cdf75b 270the \*(L'ps\*(R' utility) this option should be used with caution.
984263bc 271.Ip "\fB\-passin arg\fR" 4
984263bc
MD
272the key password source. For more information about the format of \fBarg\fR
273see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
274.Ip "\fB\-verbose\fR" 4
984263bc
MD
275this prints extra details about the operations being performed.
276.Ip "\fB\-notext\fR" 4
984263bc
MD
277don't output the text form of a certificate to the output file.
278.Ip "\fB\-startdate date\fR" 4
984263bc
MD
279this allows the start date to be explicitly set. The format of the
280date is \s-1YYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 UTCTime structure).
281.Ip "\fB\-enddate date\fR" 4
984263bc
MD
282this allows the expiry date to be explicitly set. The format of the
283date is \s-1YYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 UTCTime structure).
284.Ip "\fB\-days arg\fR" 4
984263bc
MD
285the number of days to certify the certificate for.
286.Ip "\fB\-md alg\fR" 4
984263bc
MD
287the message digest to use. Possible values include md5, sha1 and mdc2.
288This option also applies to CRLs.
289.Ip "\fB\-policy arg\fR" 4
984263bc
MD
290this option defines the \s-1CA\s0 \*(L"policy\*(R" to use. This is a section in
291the configuration file which decides which fields should be mandatory
292or match the \s-1CA\s0 certificate. Check out the \fB\s-1POLICY\s0 \s-1FORMAT\s0\fR section
293for more information.
294.Ip "\fB\-msie_hack\fR" 4
984263bc
MD
295this is a legacy option to make \fBca\fR work with very old versions of
296the \s-1IE\s0 certificate enrollment control \*(L"certenr3\*(R". It used UniversalStrings
297for almost everything. Since the old control has various security bugs
298its use is strongly discouraged. The newer control \*(L"Xenroll\*(R" does not
299need this option.
300.Ip "\fB\-preserveDN\fR" 4
984263bc
MD
301Normally the \s-1DN\s0 order of a certificate is the same as the order of the
302fields in the relevant policy section. When this option is set the order
303is the same as the request. This is largely for compatibility with the
304older \s-1IE\s0 enrollment control which would only accept certificates if their
305DNs match the order of the request. This is not needed for Xenroll.
306.Ip "\fB\-noemailDN\fR" 4
984263bc
MD
307The \s-1DN\s0 of a certificate can contain the \s-1EMAIL\s0 field if present in the
308request \s-1DN\s0, however it is good policy just having the e-mail set into
309the altName extension of the certificate. When this option is set the
e3cdf75b 310\s-1EMAIL\s0 field is removed from the certificate\*(R' subject and set only in
984263bc
MD
311the, eventually present, extensions. The \fBemail_in_dn\fR keyword can be
312used in the configuration file to enable this behaviour.
313.Ip "\fB\-batch\fR" 4
984263bc
MD
314this sets the batch mode. In this mode no questions will be asked
315and all certificates will be certified automatically.
316.Ip "\fB\-extensions section\fR" 4
984263bc
MD
317the section of the configuration file containing certificate extensions
318to be added when a certificate is issued (defaults to \fBx509_extensions\fR
319unless the \fB\-extfile\fR option is used). If no extension section is
320present then, a V1 certificate is created. If the extension section
321is present (even if it is empty), then a V3 certificate is created.
322.Ip "\fB\-extfile file\fR" 4
984263bc
MD
323an additional configuration file to read certificate extensions from
324(using the default section unless the \fB\-extensions\fR option is also
325used).
326.Ip "\fB\-engine id\fR" 4
984263bc
MD
327specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
328to attempt to obtain a functional reference to the specified engine,
329thus initialising it if needed. The engine will then be set as the default
330for all available algorithms.
331.SH "CRL OPTIONS"
984263bc 332.Ip "\fB\-gencrl\fR" 4
984263bc
MD
333this option generates a \s-1CRL\s0 based on information in the index file.
334.Ip "\fB\-crldays num\fR" 4
984263bc
MD
335the number of days before the next \s-1CRL\s0 is due. That is the days from
336now to place in the \s-1CRL\s0 nextUpdate field.
337.Ip "\fB\-crlhours num\fR" 4
984263bc
MD
338the number of hours before the next \s-1CRL\s0 is due.
339.Ip "\fB\-revoke filename\fR" 4
984263bc
MD
340a filename containing a certificate to revoke.
341.Ip "\fB\-crl_reason reason\fR" 4
984263bc 342revocation reason, where \fBreason\fR is one of: \fBunspecified\fR, \fBkeyCompromise\fR,
e3cdf75b
JR
343\fBCACompromise\fR, \fBaffiliationChanged\fR, \fBsuperseded\fR, \fBcessationOfOperation\fR,
344\fBcertificateHold\fR or \fBremoveFromCRL\fR. The matching of \fBreason\fR is case
984263bc
MD
345insensitive. Setting any revocation reason will make the \s-1CRL\s0 v2.
346.Sp
347In practive \fBremoveFromCRL\fR is not particularly useful because it is only used
348in delta CRLs which are not currently implemented.
349.Ip "\fB\-crl_hold instruction\fR" 4
984263bc
MD
350This sets the \s-1CRL\s0 revocation reason code to \fBcertificateHold\fR and the hold
351instruction to \fBinstruction\fR which must be an \s-1OID\s0. Although any \s-1OID\s0 can be
352used only \fBholdInstructionNone\fR (the use of which is discouraged by \s-1RFC2459\s0)
e3cdf75b 353\fBholdInstructionCallIssuer\fR or \fBholdInstructionReject\fR will normally be used.
984263bc 354.Ip "\fB\-crl_compromise time\fR" 4
984263bc 355This sets the revocation reason to \fBkeyCompromise\fR and the compromise time to
e3cdf75b 356\fBtime\fR. \fBtime\fR should be in GeneralizedTime format that is \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
984263bc 357.Ip "\fB\-crl_CA_compromise time\fR" 4
984263bc 358This is the same as \fBcrl_compromise\fR except the revocation reason is set to
e3cdf75b 359\fBCACompromise\fR.
984263bc 360.Ip "\fB\-subj arg\fR" 4
984263bc
MD
361supersedes subject name given in the request.
362The arg must be formatted as \fI/type0=value0/type1=value1/type2=...\fR,
363characters may be escaped by \e (backslash), no spaces are skipped.
364.Ip "\fB\-crlexts section\fR" 4
984263bc
MD
365the section of the configuration file containing \s-1CRL\s0 extensions to
366include. If no \s-1CRL\s0 extension section is present then a V1 \s-1CRL\s0 is
367created, if the \s-1CRL\s0 extension section is present (even if it is
368empty) then a V2 \s-1CRL\s0 is created. The \s-1CRL\s0 extensions specified are
e3cdf75b 369\s-1CRL\s0 extensions and \fBnot\fR \s-1CRL\s0 entry extensions. It should be noted
984263bc
MD
370that some software (for example Netscape) can't handle V2 CRLs.
371.SH "CONFIGURATION FILE OPTIONS"
984263bc
MD
372The section of the configuration file containing options for \fBca\fR
373is found as follows: If the \fB\-name\fR command line option is used,
374then it names the section to be used. Otherwise the section to
375be used must be named in the \fBdefault_ca\fR option of the \fBca\fR section
376of the configuration file (or in the default section of the
377configuration file). Besides \fBdefault_ca\fR, the following options are
378read directly from the \fBca\fR section:
e3cdf75b 379 RANDFILE
984263bc
MD
380 preserve
381 msie_hack
e3cdf75b 382With the exception of \fBRANDFILE\fR, this is probably a bug and may
984263bc
MD
383change in future releases.
384.PP
385Many of the configuration file options are identical to command line
386options. Where the option is present in the configuration file
387and the command line the command line value is used. Where an
388option is described as mandatory then it must be present in
389the configuration file or the command line equivalent (if
390any) used.
391.Ip "\fBoid_file\fR" 4
984263bc
MD
392This specifies a file containing additional \fB\s-1OBJECT\s0 \s-1IDENTIFIERS\s0\fR.
393Each line of the file should consist of the numerical form of the
394object identifier followed by white space then the short name followed
395by white space and finally the long name.
396.Ip "\fBoid_section\fR" 4
984263bc
MD
397This specifies a section in the configuration file containing extra
398object identifiers. Each line should consist of the short name of the
399object identifier followed by \fB=\fR and the numerical form. The short
400and long names are the same when this option is used.
401.Ip "\fBnew_certs_dir\fR" 4
984263bc
MD
402the same as the \fB\-outdir\fR command line option. It specifies
403the directory where new certificates will be placed. Mandatory.
404.Ip "\fBcertificate\fR" 4
984263bc
MD
405the same as \fB\-cert\fR. It gives the file containing the \s-1CA\s0
406certificate. Mandatory.
407.Ip "\fBprivate_key\fR" 4
984263bc 408same as the \fB\-keyfile\fR option. The file containing the
e3cdf75b 409\s-1CA\s0 private key. Mandatory.
984263bc 410.Ip "\fB\s-1RANDFILE\s0\fR" 4
984263bc
MD
411a file used to read and write random number seed information, or
412an \s-1EGD\s0 socket (see RAND_egd(3)).
413.Ip "\fBdefault_days\fR" 4
984263bc
MD
414the same as the \fB\-days\fR option. The number of days to certify
415a certificate for.
416.Ip "\fBdefault_startdate\fR" 4
984263bc
MD
417the same as the \fB\-startdate\fR option. The start date to certify
418a certificate for. If not set the current time is used.
419.Ip "\fBdefault_enddate\fR" 4
984263bc 420the same as the \fB\-enddate\fR option. Either this option or
e3cdf75b 421\fBdefault_days\fR (or the command line equivalents) must be
984263bc
MD
422present.
423.Ip "\fBdefault_crl_hours default_crl_days\fR" 4
984263bc
MD
424the same as the \fB\-crlhours\fR and the \fB\-crldays\fR options. These
425will only be used if neither command line option is present. At
426least one of these must be present to generate a \s-1CRL\s0.
427.Ip "\fBdefault_md\fR" 4
984263bc
MD
428the same as the \fB\-md\fR option. The message digest to use. Mandatory.
429.Ip "\fBdatabase\fR" 4
984263bc
MD
430the text database file to use. Mandatory. This file must be present
431though initially it will be empty.
e3cdf75b 432.Ip "\fBserial\fR" 4
984263bc
MD
433a text file containing the next serial number to use in hex. Mandatory.
434This file must be present and contain a valid serial number.
435.Ip "\fBx509_extensions\fR" 4
984263bc
MD
436the same as \fB\-extensions\fR.
437.Ip "\fBcrl_extensions\fR" 4
984263bc
MD
438the same as \fB\-crlexts\fR.
439.Ip "\fBpreserve\fR" 4
984263bc
MD
440the same as \fB\-preserveDN\fR
441.Ip "\fBemail_in_dn\fR" 4
984263bc 442the same as \fB\-noemailDN\fR. If you want the \s-1EMAIL\s0 field to be removed
e3cdf75b 443from the \s-1DN\s0 of the certificate simply set this to \*(L'no\*(R'. If not present
984263bc
MD
444the default is to allow for the \s-1EMAIL\s0 filed in the certificate's \s-1DN\s0.
445.Ip "\fBmsie_hack\fR" 4
984263bc
MD
446the same as \fB\-msie_hack\fR
447.Ip "\fBpolicy\fR" 4
984263bc
MD
448the same as \fB\-policy\fR. Mandatory. See the \fB\s-1POLICY\s0 \s-1FORMAT\s0\fR section
449for more information.
450.Ip "\fBnameopt\fR, \fBcertopt\fR" 4
984263bc
MD
451these options allow the format used to display the certificate details
452when asking the user to confirm signing. All the options supported by
453the \fBx509\fR utilities \fB\-nameopt\fR and \fB\-certopt\fR switches can be used
454here, except the \fBno_signame\fR and \fBno_sigdump\fR are permanently set
455and cannot be disabled (this is because the certificate signature cannot
456be displayed because the certificate has not been signed at this point).
457.Sp
e3cdf75b 458For convenience the values \fBca_default\fR are accepted by both to produce
984263bc
MD
459a reasonable output.
460.Sp
461If neither option is present the format used in earlier versions of
462OpenSSL is used. Use of the old format is \fBstrongly\fR discouraged because
463it only displays fields mentioned in the \fBpolicy\fR section, mishandles
464multicharacter string types and does not display extensions.
465.Ip "\fBcopy_extensions\fR" 4
984263bc
MD
466determines how extensions in certificate requests should be handled.
467If set to \fBnone\fR or this option is not present then extensions are
468ignored and not copied to the certificate. If set to \fBcopy\fR then any
469extensions present in the request that are not already present are copied
470to the certificate. If set to \fBcopyall\fR then all extensions in the
471request are copied to the certificate: if the extension is already present
472in the certificate it is deleted first. See the \fB\s-1WARNINGS\s0\fR section before
473using this option.
474.Sp
475The main use of this option is to allow a certificate request to supply
476values for certain extensions such as subjectAltName.
477.SH "POLICY FORMAT"
984263bc 478The policy section consists of a set of variables corresponding to
e3cdf75b
JR
479certificate DN fields. If the value is \*(L"match\*(R" then the field value
480must 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
984263bc
MD
482it may be present. Any fields not mentioned in the policy section
483are silently deleted, unless the \fB\-preserveDN\fR option is set but
484this can be regarded more of a quirk than intended behaviour.
485.SH "SPKAC FORMAT"
984263bc
MD
486The input to the \fB\-spkac\fR command line option is a Netscape
487signed public key and challenge. This will usually come from
e3cdf75b 488the \fBKEYGEN\fR tag in an HTML form to create a new private key.
984263bc
MD
489It is however possible to create SPKACs using the \fBspkac\fR utility.
490.PP
e3cdf75b
JR
491The file should contain the variable SPKAC set to the value of
492the SPKAC and also the required DN components as name value pairs.
984263bc 493If you need to include the same component twice then it can be
e3cdf75b 494preceded by a number and a \*(L'.\*(R'.
984263bc 495.SH "EXAMPLES"
984263bc
MD
496Note: these examples assume that the \fBca\fR directory structure is
497already set up and the relevant files already exist. This usually
e3cdf75b 498involves creating a CA certificate and private key with \fBreq\fR, a
984263bc
MD
499serial number file and an empty index file and placing them in
500the relevant directories.
501.PP
502To use the sample configuration file below the directories demoCA,
e3cdf75b 503demoCA/private and demoCA/newcerts would be created. The CA
984263bc
MD
504certificate would be copied to demoCA/cacert.pem and its private
505key to demoCA/private/cakey.pem. A file demoCA/serial would be
506created containing for example \*(L"01\*(R" and the empty index file
507demoCA/index.txt.
508.PP
509Sign a certificate request:
510.PP
511.Vb 1
512\& openssl ca -in req.pem -out newcert.pem
513.Ve
e3cdf75b 514Sign a certificate request, using CA extensions:
984263bc
MD
515.PP
516.Vb 1
517\& openssl ca -in req.pem -extensions v3_ca -out newcert.pem
518.Ve
e3cdf75b 519Generate a CRL
984263bc
MD
520.PP
521.Vb 1
522\& openssl ca -gencrl -out crl.pem
523.Ve
524Sign several requests:
525.PP
526.Vb 1
527\& openssl ca -infiles req1.pem req2.pem req3.pem
528.Ve
e3cdf75b 529Certify a Netscape SPKAC:
984263bc
MD
530.PP
531.Vb 1
532\& openssl ca -spkac spkac.txt
533.Ve
e3cdf75b 534A sample SPKAC file (the SPKAC line has been truncated for clarity):
984263bc
MD
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
543A sample configuration file with the relevant sections for \fBca\fR:
544.PP
e3cdf75b 545.Vb 4
984263bc
MD
546\& [ ca ]
547\& default_ca = CA_default # The default ca section
e3cdf75b 548\&
984263bc
MD
549\& [ CA_default ]
550.Ve
e3cdf75b 551.Vb 12
984263bc
MD
552\& dir = ./demoCA # top dir
553\& database = $dir/index.txt # index file.
554\& new_certs_dir = $dir/newcerts # new certs dir
e3cdf75b 555\&
984263bc
MD
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
e3cdf75b 560\&
984263bc
MD
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
e3cdf75b
JR
570\& nameopt = ca_default # Subject name display option
571\& certopt = ca_default # Certificate display option
984263bc
MD
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"
984263bc
MD
584Note: the location of all files can change either by compile time options,
585configuration file entries, environment variables or command line options.
586The 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"
e3cdf75b 601\fBOPENSSL_CONF\fR reflects the location of master configuration file it can
984263bc
MD
602be overridden by the \fB\-config\fR command line option.
603.SH "RESTRICTIONS"
984263bc
MD
604The text database index file is a critical part of the process and
605if corrupted it can be difficult to fix. It is theoretically possible
606to rebuild the index file from all the issued certificates and a current
e3cdf75b 607CRL: however there is no option to do this.
984263bc 608.PP
e3cdf75b 609V2 CRL features like delta CRL support and CRL numbers are not currently
984263bc
MD
610supported.
611.PP
612Although several requests can be input and handled at once it is only
e3cdf75b 613possible to include one SPKAC or self signed certificate.
984263bc 614.SH "BUGS"
984263bc
MD
615The use of an in memory text database can cause problems when large
616numbers of certificates are present because, as the name implies
617the database has to be kept in memory.
618.PP
e3cdf75b 619It is not possible to certify two certificates with the same DN: this
984263bc
MD
620is a side effect of how the text database is indexed and it cannot easily
621be fixed without introducing other problems. Some S/MIME clients can use
e3cdf75b 622two certificates with the same DN for separate signing and encryption
984263bc
MD
623keys.
624.PP
625The \fBca\fR command really needs rewriting or the required functionality
626exposed at either a command or interface level so a more friendly utility
e3cdf75b
JR
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.
984263bc
MD
629.PP
630Any fields in a request that are not present in a policy are silently
631deleted. This does not happen if the \fB\-preserveDN\fR option is used. To
e3cdf75b
JR
632enforce the absence of the EMAIL field within the DN, as suggested by
633RFCs, regardless the contents of the request\*(R' subject the \fB\-noemailDN\fR
984263bc
MD
634option can be used. The behaviour should be more friendly and
635configurable.
636.PP
637Cancelling some commands by refusing to certify a certificate can
638create an empty file.
639.SH "WARNINGS"
984263bc
MD
640The \fBca\fR command is quirky and at times downright unfriendly.
641.PP
642The \fBca\fR utility was originally meant as an example of how to do things
e3cdf75b 643in a CA. It was not supposed to be used as a full blown CA itself:
984263bc
MD
644nevertheless some people are using it for this purpose.
645.PP
646The \fBca\fR command is effectively a single user command: no locking is
647done on the various files and attempts to run more than one \fBca\fR command
648on the same database can have unpredictable results.
649.PP
650The \fBcopy_extensions\fR option should be used with caution. If care is
651not taken then it can be a security risk. For example if a certificate
e3cdf75b
JR
652request 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
984263bc 654this when the certificate is displayed then this will hand the requestor
e3cdf75b 655a valid CA certificate.
984263bc
MD
656.PP
657This situation can be avoided by setting \fBcopy_extensions\fR to \fBcopy\fR
e3cdf75b 658and including basicConstraints with CA:FALSE in the configuration file.
984263bc
MD
659Then if the request contains a basicConstraints extension it will be
660ignored.
661.PP
662It is advisable to also include values for other extensions such
663as \fBkeyUsage\fR to prevent a request supplying its own values.
664.PP
e3cdf75b
JR
665Additional restrictions can be placed on the CA certificate itself.
666For example if the CA certificate has:
984263bc
MD
667.PP
668.Vb 1
669\& basicConstraints = CA:TRUE, pathlen:0
670.Ve
e3cdf75b 671then even if a certificate is issued with CA:TRUE it will not be valid.
984263bc 672.SH "SEE ALSO"
984263bc
MD
673req(1), spkac(1), x509(1), CA.pl(1),
674config(5)
e3cdf75b
JR
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