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