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