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