1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
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<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
54 .\" Avoid warning from groff about undefined register 'F'.
60 . tm Index:\\$1\t\\n%\t"\\$2"
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
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
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'
102 . \" troff and (daisy-wheel) nroff accents
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
112 . \" corrections for vroff
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'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
132 .TH CA 1 "2018-11-20" "1.1.1a" "OpenSSL"
133 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
134 .\" way too many mistakes in technical documents.
138 openssl\-ca, ca \- sample minimal CA application
140 .IX Header "SYNOPSIS"
141 \&\fBopenssl\fR \fBca\fR
144 [\fB\-config filename\fR]
145 [\fB\-name section\fR]
147 [\fB\-revoke file\fR]
149 [\fB\-status serial\fR]
151 [\fB\-crl_reason reason\fR]
152 [\fB\-crl_hold instruction\fR]
153 [\fB\-crl_compromise time\fR]
154 [\fB\-crl_CA_compromise time\fR]
155 [\fB\-crldays days\fR]
156 [\fB\-crlhours hours\fR]
157 [\fB\-crlexts section\fR]
158 [\fB\-startdate date\fR]
159 [\fB\-enddate date\fR]
163 [\fB\-keyfile arg\fR]
164 [\fB\-keyform PEM|DER\fR]
175 [\fB\-ss_cert file\fR]
180 [\fB\-extensions section\fR]
181 [\fB\-extfile section\fR]
185 [\fB\-create_serial\fR]
186 [\fB\-rand_serial\fR]
187 [\fB\-multivalue\-rdn\fR]
188 [\fB\-rand file...\fR]
189 [\fB\-writerand file\fR]
191 .IX Header "DESCRIPTION"
192 The \fBca\fR command is a minimal \s-1CA\s0 application. It can be used
193 to sign certificate requests in a variety of forms and generate
194 CRLs it also maintains a text database of issued certificates
197 The options descriptions will be divided into each purpose.
202 Print out a usage message.
203 .IP "\fB\-verbose\fR" 4
205 This prints extra details about the operations being performed.
206 .IP "\fB\-config filename\fR" 4
207 .IX Item "-config filename"
208 Specifies the configuration file to use.
209 Optional; for a description of the default value,
210 see \*(L"\s-1COMMAND SUMMARY\*(R"\s0 in \fIopenssl\fR\|(1).
211 .IP "\fB\-name section\fR" 4
212 .IX Item "-name section"
213 Specifies the configuration file section to use (overrides
214 \&\fBdefault_ca\fR in the \fBca\fR section).
215 .IP "\fB\-in filename\fR" 4
216 .IX Item "-in filename"
217 An input filename containing a single certificate request to be
218 signed by the \s-1CA.\s0
219 .IP "\fB\-ss_cert filename\fR" 4
220 .IX Item "-ss_cert filename"
221 A single self-signed certificate to be signed by the \s-1CA.\s0
222 .IP "\fB\-spkac filename\fR" 4
223 .IX Item "-spkac filename"
224 A file containing a single Netscape signed public key and challenge
225 and additional field values to be signed by the \s-1CA.\s0 See the \fB\s-1SPKAC FORMAT\s0\fR
226 section for information on the required input and output format.
227 .IP "\fB\-infiles\fR" 4
229 If present this should be the last option, all subsequent arguments
230 are taken as the names of files containing certificate requests.
231 .IP "\fB\-out filename\fR" 4
232 .IX Item "-out filename"
233 The output file to output certificates to. The default is standard
234 output. The certificate details will also be printed out to this
235 file in \s-1PEM\s0 format (except that \fB\-spkac\fR outputs \s-1DER\s0 format).
236 .IP "\fB\-outdir directory\fR" 4
237 .IX Item "-outdir directory"
238 The directory to output certificates to. The certificate will be
239 written to a filename consisting of the serial number in hex with
240 \&\*(L".pem\*(R" appended.
243 The \s-1CA\s0 certificate file.
244 .IP "\fB\-keyfile filename\fR" 4
245 .IX Item "-keyfile filename"
246 The private key to sign requests with.
247 .IP "\fB\-keyform PEM|DER\fR" 4
248 .IX Item "-keyform PEM|DER"
249 The format of the data in the private key file.
250 The default is \s-1PEM.\s0
251 .IP "\fB\-key password\fR" 4
252 .IX Item "-key password"
253 The password used to encrypt the private key. Since on some
254 systems the command line arguments are visible (e.g. Unix with
255 the 'ps' utility) this option should be used with caution.
256 .IP "\fB\-selfsign\fR" 4
258 Indicates the issued certificates are to be signed with the key
259 the certificate requests were signed with (given with \fB\-keyfile\fR).
260 Certificate requests signed with a different key are ignored. If
261 \&\fB\-spkac\fR, \fB\-ss_cert\fR or \fB\-gencrl\fR are given, \fB\-selfsign\fR is
264 A consequence of using \fB\-selfsign\fR is that the self-signed
265 certificate appears among the entries in the certificate database
266 (see the configuration option \fBdatabase\fR), and uses the same
267 serial number counter as all other certificates sign with the
268 self-signed certificate.
269 .IP "\fB\-passin arg\fR" 4
270 .IX Item "-passin arg"
271 The key password source. For more information about the format of \fBarg\fR
272 see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
273 .IP "\fB\-notext\fR" 4
275 Don't output the text form of a certificate to the output file.
276 .IP "\fB\-startdate date\fR" 4
277 .IX Item "-startdate date"
278 This allows the start date to be explicitly set. The format of the
279 date is \s-1YYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 UTCTime structure), or
280 \&\s-1YYYYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 GeneralizedTime structure). In
281 both formats, seconds \s-1SS\s0 and timezone Z must be present.
282 .IP "\fB\-enddate date\fR" 4
283 .IX Item "-enddate date"
284 This allows the expiry date to be explicitly set. The format of the
285 date is \s-1YYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 UTCTime structure), or
286 \&\s-1YYYYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 GeneralizedTime structure). In
287 both formats, seconds \s-1SS\s0 and timezone Z must be present.
288 .IP "\fB\-days arg\fR" 4
290 The number of days to certify the certificate for.
291 .IP "\fB\-md alg\fR" 4
293 The message digest to use.
294 Any digest supported by the OpenSSL \fBdgst\fR command can be used. For signing
295 algorithms that do not support a digest (i.e. Ed25519 and Ed448) any message
296 digest that is set is ignored. This option also applies to CRLs.
297 .IP "\fB\-policy arg\fR" 4
298 .IX Item "-policy arg"
299 This option defines the \s-1CA\s0 \*(L"policy\*(R" to use. This is a section in
300 the configuration file which decides which fields should be mandatory
301 or match the \s-1CA\s0 certificate. Check out the \fB\s-1POLICY FORMAT\s0\fR section
302 for more information.
303 .IP "\fB\-msie_hack\fR" 4
304 .IX Item "-msie_hack"
305 This is a deprecated option to make \fBca\fR work with very old versions of
306 the \s-1IE\s0 certificate enrollment control \*(L"certenr3\*(R". It used UniversalStrings
307 for almost everything. Since the old control has various security bugs
308 its use is strongly discouraged.
309 .IP "\fB\-preserveDN\fR" 4
310 .IX Item "-preserveDN"
311 Normally the \s-1DN\s0 order of a certificate is the same as the order of the
312 fields in the relevant policy section. When this option is set the order
313 is the same as the request. This is largely for compatibility with the
314 older \s-1IE\s0 enrollment control which would only accept certificates if their
315 DNs match the order of the request. This is not needed for Xenroll.
316 .IP "\fB\-noemailDN\fR" 4
317 .IX Item "-noemailDN"
318 The \s-1DN\s0 of a certificate can contain the \s-1EMAIL\s0 field if present in the
319 request \s-1DN,\s0 however it is good policy just having the e\-mail set into
320 the altName extension of the certificate. When this option is set the
321 \&\s-1EMAIL\s0 field is removed from the certificate' subject and set only in
322 the, eventually present, extensions. The \fBemail_in_dn\fR keyword can be
323 used in the configuration file to enable this behaviour.
324 .IP "\fB\-batch\fR" 4
326 This sets the batch mode. In this mode no questions will be asked
327 and all certificates will be certified automatically.
328 .IP "\fB\-extensions section\fR" 4
329 .IX Item "-extensions section"
330 The section of the configuration file containing certificate extensions
331 to be added when a certificate is issued (defaults to \fBx509_extensions\fR
332 unless the \fB\-extfile\fR option is used). If no extension section is
333 present then, a V1 certificate is created. If the extension section
334 is present (even if it is empty), then a V3 certificate is created. See the:w
335 \&\fIx509v3_config\fR\|(5) manual page for details of the
336 extension section format.
337 .IP "\fB\-extfile file\fR" 4
338 .IX Item "-extfile file"
339 An additional configuration file to read certificate extensions from
340 (using the default section unless the \fB\-extensions\fR option is also
342 .IP "\fB\-engine id\fR" 4
343 .IX Item "-engine id"
344 Specifying an engine (by its unique \fBid\fR string) will cause \fBca\fR
345 to attempt to obtain a functional reference to the specified engine,
346 thus initialising it if needed. The engine will then be set as the default
347 for all available algorithms.
348 .IP "\fB\-subj arg\fR" 4
350 Supersedes subject name given in the request.
351 The arg must be formatted as \fI/type0=value0/type1=value1/type2=...\fR.
352 Keyword characters may be escaped by \e (backslash), and whitespace is retained.
353 Empty values are permitted, but the corresponding type will not be included
354 in the resulting certificate.
357 This option causes field values to be interpreted as \s-1UTF8\s0 strings, by
358 default they are interpreted as \s-1ASCII.\s0 This means that the field
359 values, whether prompted from a terminal or obtained from a
360 configuration file, must be valid \s-1UTF8\s0 strings.
361 .IP "\fB\-create_serial\fR" 4
362 .IX Item "-create_serial"
363 If reading serial from the text file as specified in the configuration
364 fails, specifying this option creates a new random serial to be used as next
366 To get random serial numbers, use the \fB\-rand_serial\fR flag instead; this
367 should only be used for simple error-recovery.
368 .IP "\fB\-rand_serial\fR" 4
369 .IX Item "-rand_serial"
370 Generate a large random number to use as the serial number.
371 This overrides any option or configuration to use a serial number file.
372 .IP "\fB\-multivalue\-rdn\fR" 4
373 .IX Item "-multivalue-rdn"
374 This option causes the \-subj argument to be interpreted with full
375 support for multivalued RDNs. Example:
377 \&\fI/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe\fR
379 If \-multi\-rdn is not used then the \s-1UID\s0 value is \fI123456+CN=John Doe\fR.
380 .IP "\fB\-rand file...\fR" 4
381 .IX Item "-rand file..."
382 A file or files containing random data used to seed the random number
384 Multiple files can be specified separated by an OS-dependent character.
385 The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for
387 .IP "[\fB\-writerand file\fR]" 4
388 .IX Item "[-writerand file]"
389 Writes random data to the specified \fIfile\fR upon exit.
390 This can be used with a subsequent \fB\-rand\fR flag.
392 .IX Header "CRL OPTIONS"
393 .IP "\fB\-gencrl\fR" 4
395 This option generates a \s-1CRL\s0 based on information in the index file.
396 .IP "\fB\-crldays num\fR" 4
397 .IX Item "-crldays num"
398 The number of days before the next \s-1CRL\s0 is due. That is the days from
399 now to place in the \s-1CRL\s0 nextUpdate field.
400 .IP "\fB\-crlhours num\fR" 4
401 .IX Item "-crlhours num"
402 The number of hours before the next \s-1CRL\s0 is due.
403 .IP "\fB\-revoke filename\fR" 4
404 .IX Item "-revoke filename"
405 A filename containing a certificate to revoke.
406 .IP "\fB\-valid filename\fR" 4
407 .IX Item "-valid filename"
408 A filename containing a certificate to add a Valid certificate entry.
409 .IP "\fB\-status serial\fR" 4
410 .IX Item "-status serial"
411 Displays the revocation status of the certificate with the specified
412 serial number and exits.
413 .IP "\fB\-updatedb\fR" 4
415 Updates the database index to purge expired certificates.
416 .IP "\fB\-crl_reason reason\fR" 4
417 .IX Item "-crl_reason reason"
418 Revocation reason, where \fBreason\fR is one of: \fBunspecified\fR, \fBkeyCompromise\fR,
419 \&\fBCACompromise\fR, \fBaffiliationChanged\fR, \fBsuperseded\fR, \fBcessationOfOperation\fR,
420 \&\fBcertificateHold\fR or \fBremoveFromCRL\fR. The matching of \fBreason\fR is case
421 insensitive. Setting any revocation reason will make the \s-1CRL\s0 v2.
423 In practice \fBremoveFromCRL\fR is not particularly useful because it is only used
424 in delta CRLs which are not currently implemented.
425 .IP "\fB\-crl_hold instruction\fR" 4
426 .IX Item "-crl_hold instruction"
427 This sets the \s-1CRL\s0 revocation reason code to \fBcertificateHold\fR and the hold
428 instruction to \fBinstruction\fR which must be an \s-1OID.\s0 Although any \s-1OID\s0 can be
429 used only \fBholdInstructionNone\fR (the use of which is discouraged by \s-1RFC2459\s0)
430 \&\fBholdInstructionCallIssuer\fR or \fBholdInstructionReject\fR will normally be used.
431 .IP "\fB\-crl_compromise time\fR" 4
432 .IX Item "-crl_compromise time"
433 This sets the revocation reason to \fBkeyCompromise\fR and the compromise time to
434 \&\fBtime\fR. \fBtime\fR should be in GeneralizedTime format that is \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
435 .IP "\fB\-crl_CA_compromise time\fR" 4
436 .IX Item "-crl_CA_compromise time"
437 This is the same as \fBcrl_compromise\fR except the revocation reason is set to
438 \&\fBCACompromise\fR.
439 .IP "\fB\-crlexts section\fR" 4
440 .IX Item "-crlexts section"
441 The section of the configuration file containing \s-1CRL\s0 extensions to
442 include. If no \s-1CRL\s0 extension section is present then a V1 \s-1CRL\s0 is
443 created, if the \s-1CRL\s0 extension section is present (even if it is
444 empty) then a V2 \s-1CRL\s0 is created. The \s-1CRL\s0 extensions specified are
445 \&\s-1CRL\s0 extensions and \fBnot\fR \s-1CRL\s0 entry extensions. It should be noted
446 that some software (for example Netscape) can't handle V2 CRLs. See
447 \&\fIx509v3_config\fR\|(5) manual page for details of the
448 extension section format.
449 .SH "CONFIGURATION FILE OPTIONS"
450 .IX Header "CONFIGURATION FILE OPTIONS"
451 The section of the configuration file containing options for \fBca\fR
452 is found as follows: If the \fB\-name\fR command line option is used,
453 then it names the section to be used. Otherwise the section to
454 be used must be named in the \fBdefault_ca\fR option of the \fBca\fR section
455 of the configuration file (or in the default section of the
456 configuration file). Besides \fBdefault_ca\fR, the following options are
457 read directly from the \fBca\fR section:
461 With the exception of \fB\s-1RANDFILE\s0\fR, this is probably a bug and may
462 change in future releases.
464 Many of the configuration file options are identical to command line
465 options. Where the option is present in the configuration file
466 and the command line the command line value is used. Where an
467 option is described as mandatory then it must be present in
468 the configuration file or the command line equivalent (if
470 .IP "\fBoid_file\fR" 4
472 This specifies a file containing additional \fB\s-1OBJECT IDENTIFIERS\s0\fR.
473 Each line of the file should consist of the numerical form of the
474 object identifier followed by white space then the short name followed
475 by white space and finally the long name.
476 .IP "\fBoid_section\fR" 4
477 .IX Item "oid_section"
478 This specifies a section in the configuration file containing extra
479 object identifiers. Each line should consist of the short name of the
480 object identifier followed by \fB=\fR and the numerical form. The short
481 and long names are the same when this option is used.
482 .IP "\fBnew_certs_dir\fR" 4
483 .IX Item "new_certs_dir"
484 The same as the \fB\-outdir\fR command line option. It specifies
485 the directory where new certificates will be placed. Mandatory.
486 .IP "\fBcertificate\fR" 4
487 .IX Item "certificate"
488 The same as \fB\-cert\fR. It gives the file containing the \s-1CA\s0
489 certificate. Mandatory.
490 .IP "\fBprivate_key\fR" 4
491 .IX Item "private_key"
492 Same as the \fB\-keyfile\fR option. The file containing the
493 \&\s-1CA\s0 private key. Mandatory.
494 .IP "\fB\s-1RANDFILE\s0\fR" 4
496 At startup the specified file is loaded into the random number generator,
497 and at exit 256 bytes will be written to it.
498 .IP "\fBdefault_days\fR" 4
499 .IX Item "default_days"
500 The same as the \fB\-days\fR option. The number of days to certify
502 .IP "\fBdefault_startdate\fR" 4
503 .IX Item "default_startdate"
504 The same as the \fB\-startdate\fR option. The start date to certify
505 a certificate for. If not set the current time is used.
506 .IP "\fBdefault_enddate\fR" 4
507 .IX Item "default_enddate"
508 The same as the \fB\-enddate\fR option. Either this option or
509 \&\fBdefault_days\fR (or the command line equivalents) must be
511 .IP "\fBdefault_crl_hours default_crl_days\fR" 4
512 .IX Item "default_crl_hours default_crl_days"
513 The same as the \fB\-crlhours\fR and the \fB\-crldays\fR options. These
514 will only be used if neither command line option is present. At
515 least one of these must be present to generate a \s-1CRL.\s0
516 .IP "\fBdefault_md\fR" 4
517 .IX Item "default_md"
518 The same as the \fB\-md\fR option. Mandatory except where the signing algorithm does
519 not require a digest (i.e. Ed25519 and Ed448).
520 .IP "\fBdatabase\fR" 4
522 The text database file to use. Mandatory. This file must be present
523 though initially it will be empty.
524 .IP "\fBunique_subject\fR" 4
525 .IX Item "unique_subject"
526 If the value \fByes\fR is given, the valid certificate entries in the
527 database must have unique subjects. if the value \fBno\fR is given,
528 several valid certificate entries may have the exact same subject.
529 The default value is \fByes\fR, to be compatible with older (pre 0.9.8)
530 versions of OpenSSL. However, to make \s-1CA\s0 certificate roll-over easier,
531 it's recommended to use the value \fBno\fR, especially if combined with
532 the \fB\-selfsign\fR command line option.
534 Note that it is valid in some circumstances for certificates to be created
535 without any subject. In the case where there are multiple certificates without
536 subjects this does not count as a duplicate.
539 A text file containing the next serial number to use in hex. Mandatory.
540 This file must be present and contain a valid serial number.
541 .IP "\fBcrlnumber\fR" 4
543 A text file containing the next \s-1CRL\s0 number to use in hex. The crl number
544 will be inserted in the CRLs only if this file exists. If this file is
545 present, it must contain a valid \s-1CRL\s0 number.
546 .IP "\fBx509_extensions\fR" 4
547 .IX Item "x509_extensions"
548 The same as \fB\-extensions\fR.
549 .IP "\fBcrl_extensions\fR" 4
550 .IX Item "crl_extensions"
551 The same as \fB\-crlexts\fR.
552 .IP "\fBpreserve\fR" 4
554 The same as \fB\-preserveDN\fR
555 .IP "\fBemail_in_dn\fR" 4
556 .IX Item "email_in_dn"
557 The same as \fB\-noemailDN\fR. If you want the \s-1EMAIL\s0 field to be removed
558 from the \s-1DN\s0 of the certificate simply set this to 'no'. If not present
559 the default is to allow for the \s-1EMAIL\s0 filed in the certificate's \s-1DN.\s0
560 .IP "\fBmsie_hack\fR" 4
562 The same as \fB\-msie_hack\fR
565 The same as \fB\-policy\fR. Mandatory. See the \fB\s-1POLICY FORMAT\s0\fR section
566 for more information.
567 .IP "\fBname_opt\fR, \fBcert_opt\fR" 4
568 .IX Item "name_opt, cert_opt"
569 These options allow the format used to display the certificate details
570 when asking the user to confirm signing. All the options supported by
571 the \fBx509\fR utilities \fB\-nameopt\fR and \fB\-certopt\fR switches can be used
572 here, except the \fBno_signame\fR and \fBno_sigdump\fR are permanently set
573 and cannot be disabled (this is because the certificate signature cannot
574 be displayed because the certificate has not been signed at this point).
576 For convenience the values \fBca_default\fR are accepted by both to produce
579 If neither option is present the format used in earlier versions of
580 OpenSSL is used. Use of the old format is \fBstrongly\fR discouraged because
581 it only displays fields mentioned in the \fBpolicy\fR section, mishandles
582 multicharacter string types and does not display extensions.
583 .IP "\fBcopy_extensions\fR" 4
584 .IX Item "copy_extensions"
585 Determines how extensions in certificate requests should be handled.
586 If set to \fBnone\fR or this option is not present then extensions are
587 ignored and not copied to the certificate. If set to \fBcopy\fR then any
588 extensions present in the request that are not already present are copied
589 to the certificate. If set to \fBcopyall\fR then all extensions in the
590 request are copied to the certificate: if the extension is already present
591 in the certificate it is deleted first. See the \fB\s-1WARNINGS\s0\fR section before
594 The main use of this option is to allow a certificate request to supply
595 values for certain extensions such as subjectAltName.
597 .IX Header "POLICY FORMAT"
598 The policy section consists of a set of variables corresponding to
599 certificate \s-1DN\s0 fields. If the value is \*(L"match\*(R" then the field value
600 must match the same field in the \s-1CA\s0 certificate. If the value is
601 \&\*(L"supplied\*(R" then it must be present. If the value is \*(L"optional\*(R" then
602 it may be present. Any fields not mentioned in the policy section
603 are silently deleted, unless the \fB\-preserveDN\fR option is set but
604 this can be regarded more of a quirk than intended behaviour.
606 .IX Header "SPKAC FORMAT"
607 The input to the \fB\-spkac\fR command line option is a Netscape
608 signed public key and challenge. This will usually come from
609 the \fB\s-1KEYGEN\s0\fR tag in an \s-1HTML\s0 form to create a new private key.
610 It is however possible to create SPKACs using the \fBspkac\fR utility.
612 The file should contain the variable \s-1SPKAC\s0 set to the value of
613 the \s-1SPKAC\s0 and also the required \s-1DN\s0 components as name value pairs.
614 If you need to include the same component twice then it can be
615 preceded by a number and a '.'.
617 When processing \s-1SPKAC\s0 format, the output is \s-1DER\s0 if the \fB\-out\fR
618 flag is used, but \s-1PEM\s0 format if sending to stdout or the \fB\-outdir\fR
621 .IX Header "EXAMPLES"
622 Note: these examples assume that the \fBca\fR directory structure is
623 already set up and the relevant files already exist. This usually
624 involves creating a \s-1CA\s0 certificate and private key with \fBreq\fR, a
625 serial number file and an empty index file and placing them in
626 the relevant directories.
628 To use the sample configuration file below the directories demoCA,
629 demoCA/private and demoCA/newcerts would be created. The \s-1CA\s0
630 certificate would be copied to demoCA/cacert.pem and its private
631 key to demoCA/private/cakey.pem. A file demoCA/serial would be
632 created containing for example \*(L"01\*(R" and the empty index file
635 Sign a certificate request:
638 \& openssl ca \-in req.pem \-out newcert.pem
641 Sign a certificate request, using \s-1CA\s0 extensions:
644 \& openssl ca \-in req.pem \-extensions v3_ca \-out newcert.pem
647 Generate a \s-1CRL\s0
650 \& openssl ca \-gencrl \-out crl.pem
653 Sign several requests:
656 \& openssl ca \-infiles req1.pem req2.pem req3.pem
659 Certify a Netscape \s-1SPKAC:\s0
662 \& openssl ca \-spkac spkac.txt
665 A sample \s-1SPKAC\s0 file (the \s-1SPKAC\s0 line has been truncated for clarity):
668 \& SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
670 \& emailAddress=steve@openssl.org
671 \& 0.OU=OpenSSL Group
672 \& 1.OU=Another Group
675 A sample configuration file with the relevant sections for \fBca\fR:
679 \& default_ca = CA_default # The default ca section
683 \& dir = ./demoCA # top dir
684 \& database = $dir/index.txt # index file.
685 \& new_certs_dir = $dir/newcerts # new certs dir
687 \& certificate = $dir/cacert.pem # The CA cert
688 \& serial = $dir/serial # serial no file
689 \& #rand_serial = yes # for random serial#\*(Aqs
690 \& private_key = $dir/private/cakey.pem# CA private key
691 \& RANDFILE = $dir/private/.rand # random number file
693 \& default_days = 365 # how long to certify for
694 \& default_crl_days= 30 # how long before next CRL
695 \& default_md = md5 # md to use
697 \& policy = policy_any # default policy
698 \& email_in_dn = no # Don\*(Aqt add the email into cert DN
700 \& name_opt = ca_default # Subject name display option
701 \& cert_opt = ca_default # Certificate display option
702 \& copy_extensions = none # Don\*(Aqt copy extensions from request
705 \& countryName = supplied
706 \& stateOrProvinceName = optional
707 \& organizationName = optional
708 \& organizationalUnitName = optional
709 \& commonName = supplied
710 \& emailAddress = optional
714 Note: the location of all files can change either by compile time options,
715 configuration file entries, environment variables or command line options.
716 The values below reflect the default values.
719 \& /usr/local/ssl/lib/openssl.cnf \- master configuration file
720 \& ./demoCA \- main CA directory
721 \& ./demoCA/cacert.pem \- CA certificate
722 \& ./demoCA/private/cakey.pem \- CA private key
723 \& ./demoCA/serial \- CA serial number file
724 \& ./demoCA/serial.old \- CA serial number backup file
725 \& ./demoCA/index.txt \- CA text database file
726 \& ./demoCA/index.txt.old \- CA text database backup file
727 \& ./demoCA/certs \- certificate output file
728 \& ./demoCA/.rnd \- CA random seed information
731 .IX Header "RESTRICTIONS"
732 The text database index file is a critical part of the process and
733 if corrupted it can be difficult to fix. It is theoretically possible
734 to rebuild the index file from all the issued certificates and a current
735 \&\s-1CRL:\s0 however there is no option to do this.
737 V2 \s-1CRL\s0 features like delta CRLs are not currently supported.
739 Although several requests can be input and handled at once it is only
740 possible to include one \s-1SPKAC\s0 or self-signed certificate.
743 The use of an in-memory text database can cause problems when large
744 numbers of certificates are present because, as the name implies
745 the database has to be kept in memory.
747 The \fBca\fR command really needs rewriting or the required functionality
748 exposed at either a command or interface level so a more friendly utility
749 (perl script or \s-1GUI\s0) can handle things properly. The script
750 \&\fB\s-1CA\s0.pl\fR helps a little but not very much.
752 Any fields in a request that are not present in a policy are silently
753 deleted. This does not happen if the \fB\-preserveDN\fR option is used. To
754 enforce the absence of the \s-1EMAIL\s0 field within the \s-1DN,\s0 as suggested by
755 RFCs, regardless the contents of the request' subject the \fB\-noemailDN\fR
756 option can be used. The behaviour should be more friendly and
759 Canceling some commands by refusing to certify a certificate can
760 create an empty file.
762 .IX Header "WARNINGS"
763 The \fBca\fR command is quirky and at times downright unfriendly.
765 The \fBca\fR utility was originally meant as an example of how to do things
766 in a \s-1CA.\s0 It was not supposed to be used as a full blown \s-1CA\s0 itself:
767 nevertheless some people are using it for this purpose.
769 The \fBca\fR command is effectively a single user command: no locking is
770 done on the various files and attempts to run more than one \fBca\fR command
771 on the same database can have unpredictable results.
773 The \fBcopy_extensions\fR option should be used with caution. If care is
774 not taken then it can be a security risk. For example if a certificate
775 request contains a basicConstraints extension with \s-1CA:TRUE\s0 and the
776 \&\fBcopy_extensions\fR value is set to \fBcopyall\fR and the user does not spot
777 this when the certificate is displayed then this will hand the requester
778 a valid \s-1CA\s0 certificate.
780 This situation can be avoided by setting \fBcopy_extensions\fR to \fBcopy\fR
781 and including basicConstraints with \s-1CA:FALSE\s0 in the configuration file.
782 Then if the request contains a basicConstraints extension it will be
785 It is advisable to also include values for other extensions such
786 as \fBkeyUsage\fR to prevent a request supplying its own values.
788 Additional restrictions can be placed on the \s-1CA\s0 certificate itself.
789 For example if the \s-1CA\s0 certificate has:
792 \& basicConstraints = CA:TRUE, pathlen:0
795 then even if a certificate is issued with \s-1CA:TRUE\s0 it will not be valid.
798 Since OpenSSL 1.1.1, the program follows \s-1RFC5280.\s0 Specifically,
799 certificate validity period (specified by any of \fB\-startdate\fR,
800 \&\fB\-enddate\fR and \fB\-days\fR) will be encoded as UTCTime if the dates are
801 earlier than year 2049 (included), and as GeneralizedTime if the dates
802 are in year 2050 or later.
804 .IX Header "SEE ALSO"
805 \&\fIreq\fR\|(1), \fIspkac\fR\|(1), \fIx509\fR\|(1), \s-1\fICA\s0.pl\fR\|(1),
806 \&\fIconfig\fR\|(5), \fIx509v3_config\fR\|(5)
808 .IX Header "COPYRIGHT"
809 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
811 Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
812 this file except in compliance with the License. You can obtain a copy
813 in the file \s-1LICENSE\s0 in the source distribution or at
814 <https://www.openssl.org/source/license.html>.
projects / FreeBSD / FreeBSD.git / blob