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