Merge from vendor branch LIBARCHIVE:
[dragonfly.git] / secure / usr.bin / openssl / man / ca.1
CommitLineData
2eaa1526 1.\" Automatically generated by Pod::Man 2.12 (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
2eaa1526
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
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb 62.\"
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"
2eaa1526
PA
127.TH CA 1 "2007-10-24" "0.9.8g" "OpenSSL"
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
2eaa1526 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
306is present (even if it is empty), then a V3 certificate is created.
8b0cefbb
JR
307.IP "\fB\-extfile file\fR" 4
308.IX Item "-extfile file"
984263bc
MD
309an additional configuration file to read certificate extensions from
310(using the default section unless the \fB\-extensions\fR option is also
311used).
8b0cefbb
JR
312.IP "\fB\-engine id\fR" 4
313.IX Item "-engine id"
984263bc
MD
314specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
315to attempt to obtain a functional reference to the specified engine,
316thus initialising it if needed. The engine will then be set as the default
317for all available algorithms.
c6082640
SS
318.IP "\fB\-subj arg\fR" 4
319.IX Item "-subj arg"
320supersedes subject name given in the request.
321The arg must be formatted as \fI/type0=value0/type1=value1/type2=...\fR,
322characters may be escaped by \e (backslash), no spaces are skipped.
323.IP "\fB\-utf8\fR" 4
324.IX Item "-utf8"
325this option causes field values to be interpreted as \s-1UTF8\s0 strings, by
326default they are interpreted as \s-1ASCII\s0. This means that the field
327values, whether prompted from a terminal or obtained from a
328configuration file, must be valid \s-1UTF8\s0 strings.
329.IP "\fB\-multivalue\-rdn\fR" 4
330.IX Item "-multivalue-rdn"
331this option causes the \-subj argument to be interpretedt with full
332support for multivalued RDNs. Example:
333.Sp
334\&\fI/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe\fR
335.Sp
336If \-multi\-rdn is not used then the \s-1UID\s0 value is \fI123456+CN=John Doe\fR.
984263bc 337.SH "CRL OPTIONS"
8b0cefbb
JR
338.IX Header "CRL OPTIONS"
339.IP "\fB\-gencrl\fR" 4
340.IX Item "-gencrl"
984263bc 341this option generates a \s-1CRL\s0 based on information in the index file.
8b0cefbb
JR
342.IP "\fB\-crldays num\fR" 4
343.IX Item "-crldays num"
984263bc
MD
344the number of days before the next \s-1CRL\s0 is due. That is the days from
345now to place in the \s-1CRL\s0 nextUpdate field.
8b0cefbb
JR
346.IP "\fB\-crlhours num\fR" 4
347.IX Item "-crlhours num"
984263bc 348the number of hours before the next \s-1CRL\s0 is due.
8b0cefbb
JR
349.IP "\fB\-revoke filename\fR" 4
350.IX Item "-revoke filename"
984263bc 351a filename containing a certificate to revoke.
8b0cefbb
JR
352.IP "\fB\-crl_reason reason\fR" 4
353.IX Item "-crl_reason reason"
984263bc 354revocation reason, where \fBreason\fR is one of: \fBunspecified\fR, \fBkeyCompromise\fR,
8b0cefbb
JR
355\&\fBCACompromise\fR, \fBaffiliationChanged\fR, \fBsuperseded\fR, \fBcessationOfOperation\fR,
356\&\fBcertificateHold\fR or \fBremoveFromCRL\fR. The matching of \fBreason\fR is case
984263bc
MD
357insensitive. Setting any revocation reason will make the \s-1CRL\s0 v2.
358.Sp
359In practive \fBremoveFromCRL\fR is not particularly useful because it is only used
360in delta CRLs which are not currently implemented.
8b0cefbb
JR
361.IP "\fB\-crl_hold instruction\fR" 4
362.IX Item "-crl_hold instruction"
984263bc
MD
363This sets the \s-1CRL\s0 revocation reason code to \fBcertificateHold\fR and the hold
364instruction to \fBinstruction\fR which must be an \s-1OID\s0. Although any \s-1OID\s0 can be
365used only \fBholdInstructionNone\fR (the use of which is discouraged by \s-1RFC2459\s0)
8b0cefbb
JR
366\&\fBholdInstructionCallIssuer\fR or \fBholdInstructionReject\fR will normally be used.
367.IP "\fB\-crl_compromise time\fR" 4
368.IX Item "-crl_compromise time"
984263bc 369This sets the revocation reason to \fBkeyCompromise\fR and the compromise time to
8b0cefbb
JR
370\&\fBtime\fR. \fBtime\fR should be in GeneralizedTime format that is \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
371.IP "\fB\-crl_CA_compromise time\fR" 4
372.IX Item "-crl_CA_compromise time"
984263bc 373This is the same as \fBcrl_compromise\fR except the revocation reason is set to
8b0cefbb 374\&\fBCACompromise\fR.
8b0cefbb
JR
375.IP "\fB\-crlexts section\fR" 4
376.IX Item "-crlexts section"
984263bc
MD
377the section of the configuration file containing \s-1CRL\s0 extensions to
378include. If no \s-1CRL\s0 extension section is present then a V1 \s-1CRL\s0 is
379created, if the \s-1CRL\s0 extension section is present (even if it is
380empty) then a V2 \s-1CRL\s0 is created. The \s-1CRL\s0 extensions specified are
8b0cefbb 381\&\s-1CRL\s0 extensions and \fBnot\fR \s-1CRL\s0 entry extensions. It should be noted
2eaa1526 382that some software (for example Netscape) can't handle V2 CRLs.
984263bc 383.SH "CONFIGURATION FILE OPTIONS"
8b0cefbb 384.IX Header "CONFIGURATION FILE OPTIONS"
984263bc
MD
385The section of the configuration file containing options for \fBca\fR
386is found as follows: If the \fB\-name\fR command line option is used,
387then it names the section to be used. Otherwise the section to
388be used must be named in the \fBdefault_ca\fR option of the \fBca\fR section
389of the configuration file (or in the default section of the
390configuration file). Besides \fBdefault_ca\fR, the following options are
391read directly from the \fBca\fR section:
8b0cefbb 392 \s-1RANDFILE\s0
984263bc
MD
393 preserve
394 msie_hack
8b0cefbb 395With the exception of \fB\s-1RANDFILE\s0\fR, this is probably a bug and may
984263bc
MD
396change in future releases.
397.PP
398Many of the configuration file options are identical to command line
399options. Where the option is present in the configuration file
400and the command line the command line value is used. Where an
401option is described as mandatory then it must be present in
402the configuration file or the command line equivalent (if
403any) used.
8b0cefbb
JR
404.IP "\fBoid_file\fR" 4
405.IX Item "oid_file"
984263bc
MD
406This specifies a file containing additional \fB\s-1OBJECT\s0 \s-1IDENTIFIERS\s0\fR.
407Each line of the file should consist of the numerical form of the
408object identifier followed by white space then the short name followed
2eaa1526 409by white space and finally the long name.
8b0cefbb
JR
410.IP "\fBoid_section\fR" 4
411.IX Item "oid_section"
984263bc
MD
412This specifies a section in the configuration file containing extra
413object identifiers. Each line should consist of the short name of the
414object identifier followed by \fB=\fR and the numerical form. The short
415and long names are the same when this option is used.
8b0cefbb
JR
416.IP "\fBnew_certs_dir\fR" 4
417.IX Item "new_certs_dir"
984263bc
MD
418the same as the \fB\-outdir\fR command line option. It specifies
419the directory where new certificates will be placed. Mandatory.
8b0cefbb
JR
420.IP "\fBcertificate\fR" 4
421.IX Item "certificate"
984263bc
MD
422the same as \fB\-cert\fR. It gives the file containing the \s-1CA\s0
423certificate. Mandatory.
8b0cefbb
JR
424.IP "\fBprivate_key\fR" 4
425.IX Item "private_key"
984263bc 426same as the \fB\-keyfile\fR option. The file containing the
8b0cefbb
JR
427\&\s-1CA\s0 private key. Mandatory.
428.IP "\fB\s-1RANDFILE\s0\fR" 4
429.IX Item "RANDFILE"
984263bc 430a file used to read and write random number seed information, or
8b0cefbb
JR
431an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)).
432.IP "\fBdefault_days\fR" 4
433.IX Item "default_days"
984263bc 434the same as the \fB\-days\fR option. The number of days to certify
2eaa1526 435a certificate for.
8b0cefbb
JR
436.IP "\fBdefault_startdate\fR" 4
437.IX Item "default_startdate"
984263bc
MD
438the same as the \fB\-startdate\fR option. The start date to certify
439a certificate for. If not set the current time is used.
8b0cefbb
JR
440.IP "\fBdefault_enddate\fR" 4
441.IX Item "default_enddate"
984263bc 442the same as the \fB\-enddate\fR option. Either this option or
8b0cefbb 443\&\fBdefault_days\fR (or the command line equivalents) must be
984263bc 444present.
8b0cefbb
JR
445.IP "\fBdefault_crl_hours default_crl_days\fR" 4
446.IX Item "default_crl_hours default_crl_days"
984263bc
MD
447the same as the \fB\-crlhours\fR and the \fB\-crldays\fR options. These
448will only be used if neither command line option is present. At
449least one of these must be present to generate a \s-1CRL\s0.
8b0cefbb
JR
450.IP "\fBdefault_md\fR" 4
451.IX Item "default_md"
984263bc 452the same as the \fB\-md\fR option. The message digest to use. Mandatory.
8b0cefbb
JR
453.IP "\fBdatabase\fR" 4
454.IX Item "database"
984263bc
MD
455the text database file to use. Mandatory. This file must be present
456though initially it will be empty.
a561f9ff
SS
457.IP "\fBunique_subject\fR" 4
458.IX Item "unique_subject"
459if the value \fByes\fR is given, the valid certificate entries in the
460database must have unique subjects. if the value \fBno\fR is given,
461several valid certificate entries may have the exact same subject.
462The default value is \fByes\fR, to be compatible with older (pre 0.9.8)
463versions of OpenSSL. However, to make \s-1CA\s0 certificate roll-over easier,
464it's recommended to use the value \fBno\fR, especially if combined with
465the \fB\-selfsign\fR command line option.
8b0cefbb
JR
466.IP "\fBserial\fR" 4
467.IX Item "serial"
984263bc
MD
468a text file containing the next serial number to use in hex. Mandatory.
469This file must be present and contain a valid serial number.
a561f9ff
SS
470.IP "\fBcrlnumber\fR" 4
471.IX Item "crlnumber"
472a text file containing the next \s-1CRL\s0 number to use in hex. The crl number
473will be inserted in the CRLs only if this file exists. If this file is
474present, it must contain a valid \s-1CRL\s0 number.
8b0cefbb
JR
475.IP "\fBx509_extensions\fR" 4
476.IX Item "x509_extensions"
984263bc 477the same as \fB\-extensions\fR.
8b0cefbb
JR
478.IP "\fBcrl_extensions\fR" 4
479.IX Item "crl_extensions"
984263bc 480the same as \fB\-crlexts\fR.
8b0cefbb
JR
481.IP "\fBpreserve\fR" 4
482.IX Item "preserve"
984263bc 483the same as \fB\-preserveDN\fR
8b0cefbb
JR
484.IP "\fBemail_in_dn\fR" 4
485.IX Item "email_in_dn"
984263bc 486the same as \fB\-noemailDN\fR. If you want the \s-1EMAIL\s0 field to be removed
8b0cefbb 487from the \s-1DN\s0 of the certificate simply set this to 'no'. If not present
984263bc 488the default is to allow for the \s-1EMAIL\s0 filed in the certificate's \s-1DN\s0.
8b0cefbb
JR
489.IP "\fBmsie_hack\fR" 4
490.IX Item "msie_hack"
984263bc 491the same as \fB\-msie_hack\fR
8b0cefbb
JR
492.IP "\fBpolicy\fR" 4
493.IX Item "policy"
984263bc
MD
494the same as \fB\-policy\fR. Mandatory. See the \fB\s-1POLICY\s0 \s-1FORMAT\s0\fR section
495for more information.
a561f9ff
SS
496.IP "\fBname_opt\fR, \fBcert_opt\fR" 4
497.IX Item "name_opt, cert_opt"
984263bc
MD
498these options allow the format used to display the certificate details
499when asking the user to confirm signing. All the options supported by
500the \fBx509\fR utilities \fB\-nameopt\fR and \fB\-certopt\fR switches can be used
501here, except the \fBno_signame\fR and \fBno_sigdump\fR are permanently set
502and cannot be disabled (this is because the certificate signature cannot
503be displayed because the certificate has not been signed at this point).
504.Sp
e3cdf75b 505For convenience the values \fBca_default\fR are accepted by both to produce
984263bc
MD
506a reasonable output.
507.Sp
508If neither option is present the format used in earlier versions of
509OpenSSL is used. Use of the old format is \fBstrongly\fR discouraged because
510it only displays fields mentioned in the \fBpolicy\fR section, mishandles
511multicharacter string types and does not display extensions.
8b0cefbb
JR
512.IP "\fBcopy_extensions\fR" 4
513.IX Item "copy_extensions"
984263bc
MD
514determines how extensions in certificate requests should be handled.
515If set to \fBnone\fR or this option is not present then extensions are
516ignored and not copied to the certificate. If set to \fBcopy\fR then any
517extensions present in the request that are not already present are copied
518to the certificate. If set to \fBcopyall\fR then all extensions in the
519request are copied to the certificate: if the extension is already present
520in the certificate it is deleted first. See the \fB\s-1WARNINGS\s0\fR section before
521using this option.
522.Sp
523The main use of this option is to allow a certificate request to supply
524values for certain extensions such as subjectAltName.
525.SH "POLICY FORMAT"
8b0cefbb 526.IX Header "POLICY FORMAT"
984263bc 527The policy section consists of a set of variables corresponding to
8b0cefbb
JR
528certificate \s-1DN\s0 fields. If the value is \*(L"match\*(R" then the field value
529must match the same field in the \s-1CA\s0 certificate. If the value is
530\&\*(L"supplied\*(R" then it must be present. If the value is \*(L"optional\*(R" then
984263bc
MD
531it may be present. Any fields not mentioned in the policy section
532are silently deleted, unless the \fB\-preserveDN\fR option is set but
533this can be regarded more of a quirk than intended behaviour.
534.SH "SPKAC FORMAT"
8b0cefbb 535.IX Header "SPKAC FORMAT"
984263bc
MD
536The input to the \fB\-spkac\fR command line option is a Netscape
537signed public key and challenge. This will usually come from
8b0cefbb 538the \fB\s-1KEYGEN\s0\fR tag in an \s-1HTML\s0 form to create a new private key.
984263bc
MD
539It is however possible to create SPKACs using the \fBspkac\fR utility.
540.PP
8b0cefbb
JR
541The file should contain the variable \s-1SPKAC\s0 set to the value of
542the \s-1SPKAC\s0 and also the required \s-1DN\s0 components as name value pairs.
984263bc 543If you need to include the same component twice then it can be
8b0cefbb 544preceded by a number and a '.'.
984263bc 545.SH "EXAMPLES"
8b0cefbb 546.IX Header "EXAMPLES"
984263bc
MD
547Note: these examples assume that the \fBca\fR directory structure is
548already set up and the relevant files already exist. This usually
8b0cefbb 549involves creating a \s-1CA\s0 certificate and private key with \fBreq\fR, a
984263bc
MD
550serial number file and an empty index file and placing them in
551the relevant directories.
552.PP
553To use the sample configuration file below the directories demoCA,
8b0cefbb 554demoCA/private and demoCA/newcerts would be created. The \s-1CA\s0
984263bc
MD
555certificate would be copied to demoCA/cacert.pem and its private
556key to demoCA/private/cakey.pem. A file demoCA/serial would be
557created containing for example \*(L"01\*(R" and the empty index file
558demoCA/index.txt.
559.PP
560Sign a certificate request:
561.PP
562.Vb 1
2eaa1526 563\& openssl ca \-in req.pem \-out newcert.pem
984263bc 564.Ve
8b0cefbb
JR
565.PP
566Sign a certificate request, using \s-1CA\s0 extensions:
984263bc
MD
567.PP
568.Vb 1
2eaa1526 569\& openssl ca \-in req.pem \-extensions v3_ca \-out newcert.pem
984263bc 570.Ve
8b0cefbb
JR
571.PP
572Generate a \s-1CRL\s0
984263bc
MD
573.PP
574.Vb 1
2eaa1526 575\& openssl ca \-gencrl \-out crl.pem
984263bc 576.Ve
8b0cefbb 577.PP
984263bc
MD
578Sign several requests:
579.PP
580.Vb 1
2eaa1526 581\& openssl ca \-infiles req1.pem req2.pem req3.pem
984263bc 582.Ve
8b0cefbb
JR
583.PP
584Certify a Netscape \s-1SPKAC:\s0
984263bc
MD
585.PP
586.Vb 1
2eaa1526 587\& openssl ca \-spkac spkac.txt
984263bc 588.Ve
8b0cefbb
JR
589.PP
590A sample \s-1SPKAC\s0 file (the \s-1SPKAC\s0 line has been truncated for clarity):
984263bc
MD
591.PP
592.Vb 5
593\& SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
594\& CN=Steve Test
595\& emailAddress=steve@openssl.org
596\& 0.OU=OpenSSL Group
597\& 1.OU=Another Group
598.Ve
8b0cefbb 599.PP
984263bc
MD
600A sample configuration file with the relevant sections for \fBca\fR:
601.PP
8b0cefbb 602.Vb 2
984263bc
MD
603\& [ ca ]
604\& default_ca = CA_default # The default ca section
2eaa1526 605\&
984263bc 606\& [ CA_default ]
2eaa1526 607\&
984263bc
MD
608\& dir = ./demoCA # top dir
609\& database = $dir/index.txt # index file.
610\& new_certs_dir = $dir/newcerts # new certs dir
2eaa1526 611\&
984263bc
MD
612\& certificate = $dir/cacert.pem # The CA cert
613\& serial = $dir/serial # serial no file
614\& private_key = $dir/private/cakey.pem# CA private key
615\& RANDFILE = $dir/private/.rand # random number file
2eaa1526 616\&
984263bc
MD
617\& default_days = 365 # how long to certify for
618\& default_crl_days= 30 # how long before next CRL
619\& default_md = md5 # md to use
2eaa1526 620\&
984263bc
MD
621\& policy = policy_any # default policy
622\& email_in_dn = no # Don't add the email into cert DN
2eaa1526 623\&
a561f9ff
SS
624\& name_opt = ca_default # Subject name display option
625\& cert_opt = ca_default # Certificate display option
984263bc 626\& copy_extensions = none # Don't copy extensions from request
2eaa1526 627\&
984263bc
MD
628\& [ policy_any ]
629\& countryName = supplied
630\& stateOrProvinceName = optional
631\& organizationName = optional
632\& organizationalUnitName = optional
633\& commonName = supplied
634\& emailAddress = optional
635.Ve
636.SH "FILES"
8b0cefbb 637.IX Header "FILES"
984263bc
MD
638Note: the location of all files can change either by compile time options,
639configuration file entries, environment variables or command line options.
640The values below reflect the default values.
641.PP
642.Vb 10
2eaa1526
PA
643\& /usr/local/ssl/lib/openssl.cnf \- master configuration file
644\& ./demoCA \- main CA directory
645\& ./demoCA/cacert.pem \- CA certificate
646\& ./demoCA/private/cakey.pem \- CA private key
647\& ./demoCA/serial \- CA serial number file
648\& ./demoCA/serial.old \- CA serial number backup file
649\& ./demoCA/index.txt \- CA text database file
650\& ./demoCA/index.txt.old \- CA text database backup file
651\& ./demoCA/certs \- certificate output file
652\& ./demoCA/.rnd \- CA random seed information
984263bc
MD
653.Ve
654.SH "ENVIRONMENT VARIABLES"
8b0cefbb
JR
655.IX Header "ENVIRONMENT VARIABLES"
656\&\fB\s-1OPENSSL_CONF\s0\fR reflects the location of master configuration file it can
984263bc
MD
657be overridden by the \fB\-config\fR command line option.
658.SH "RESTRICTIONS"
8b0cefbb 659.IX Header "RESTRICTIONS"
984263bc
MD
660The text database index file is a critical part of the process and
661if corrupted it can be difficult to fix. It is theoretically possible
662to rebuild the index file from all the issued certificates and a current
8b0cefbb 663\&\s-1CRL:\s0 however there is no option to do this.
984263bc 664.PP
a561f9ff 665V2 \s-1CRL\s0 features like delta CRLs are not currently supported.
984263bc
MD
666.PP
667Although several requests can be input and handled at once it is only
8b0cefbb 668possible to include one \s-1SPKAC\s0 or self signed certificate.
984263bc 669.SH "BUGS"
8b0cefbb 670.IX Header "BUGS"
984263bc
MD
671The use of an in memory text database can cause problems when large
672numbers of certificates are present because, as the name implies
673the database has to be kept in memory.
674.PP
984263bc
MD
675The \fBca\fR command really needs rewriting or the required functionality
676exposed at either a command or interface level so a more friendly utility
8b0cefbb
JR
677(perl script or \s-1GUI\s0) can handle things properly. The scripts \fB\s-1CA\s0.sh\fR and
678\&\fB\s-1CA\s0.pl\fR help a little but not very much.
984263bc
MD
679.PP
680Any fields in a request that are not present in a policy are silently
681deleted. This does not happen if the \fB\-preserveDN\fR option is used. To
8b0cefbb
JR
682enforce the absence of the \s-1EMAIL\s0 field within the \s-1DN\s0, as suggested by
683RFCs, regardless the contents of the request' subject the \fB\-noemailDN\fR
984263bc
MD
684option can be used. The behaviour should be more friendly and
685configurable.
686.PP
687Cancelling some commands by refusing to certify a certificate can
688create an empty file.
689.SH "WARNINGS"
8b0cefbb 690.IX Header "WARNINGS"
984263bc
MD
691The \fBca\fR command is quirky and at times downright unfriendly.
692.PP
693The \fBca\fR utility was originally meant as an example of how to do things
8b0cefbb 694in a \s-1CA\s0. It was not supposed to be used as a full blown \s-1CA\s0 itself:
984263bc
MD
695nevertheless some people are using it for this purpose.
696.PP
697The \fBca\fR command is effectively a single user command: no locking is
698done on the various files and attempts to run more than one \fBca\fR command
699on the same database can have unpredictable results.
700.PP
701The \fBcopy_extensions\fR option should be used with caution. If care is
702not taken then it can be a security risk. For example if a certificate
8b0cefbb
JR
703request contains a basicConstraints extension with \s-1CA:TRUE\s0 and the
704\&\fBcopy_extensions\fR value is set to \fBcopyall\fR and the user does not spot
984263bc 705this when the certificate is displayed then this will hand the requestor
8b0cefbb 706a valid \s-1CA\s0 certificate.
984263bc
MD
707.PP
708This situation can be avoided by setting \fBcopy_extensions\fR to \fBcopy\fR
8b0cefbb 709and including basicConstraints with \s-1CA:FALSE\s0 in the configuration file.
984263bc
MD
710Then if the request contains a basicConstraints extension it will be
711ignored.
712.PP
713It is advisable to also include values for other extensions such
714as \fBkeyUsage\fR to prevent a request supplying its own values.
715.PP
8b0cefbb
JR
716Additional restrictions can be placed on the \s-1CA\s0 certificate itself.
717For example if the \s-1CA\s0 certificate has:
984263bc
MD
718.PP
719.Vb 1
720\& basicConstraints = CA:TRUE, pathlen:0
721.Ve
8b0cefbb
JR
722.PP
723then even if a certificate is issued with \s-1CA:TRUE\s0 it will not be valid.
984263bc 724.SH "SEE ALSO"
e3cdf75b 725.IX Header "SEE ALSO"
8b0cefbb
JR
726\&\fIreq\fR\|(1), \fIspkac\fR\|(1), \fIx509\fR\|(1), \s-1\fICA\s0.pl\fR\|(1),
727\&\fIconfig\fR\|(5)