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