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