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