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-09-11" "1.1.1" "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 characters may be escaped by \e (backslash), no spaces are skipped.
355 This option causes field values to be interpreted as \s-1UTF8\s0 strings, by
356 default they are interpreted as \s-1ASCII.\s0 This means that the field
357 values, whether prompted from a terminal or obtained from a
358 configuration file, must be valid \s-1UTF8\s0 strings.
359 .IP "\fB\-create_serial\fR" 4
360 .IX Item "-create_serial"
361 If reading serial from the text file as specified in the configuration
362 fails, specifying this option creates a new random serial to be used as next
364 To get random serial numbers, use the \fB\-rand_serial\fR flag instead; this
365 should only be used for simple error-recovery.
366 .IP "\fB\-rand_serial\fR" 4
367 .IX Item "-rand_serial"
368 Generate a large random number to use as the serial number.
369 This overrides any option or configuration to use a serial number file.
370 .IP "\fB\-multivalue\-rdn\fR" 4
371 .IX Item "-multivalue-rdn"
372 This option causes the \-subj argument to be interpreted with full
373 support for multivalued RDNs. Example:
375 \&\fI/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe\fR
377 If \-multi\-rdn is not used then the \s-1UID\s0 value is \fI123456+CN=John Doe\fR.
378 .IP "\fB\-rand file...\fR" 4
379 .IX Item "-rand file..."
380 A file or files containing random data used to seed the random number
382 Multiple files can be specified separated by an OS-dependent character.
383 The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for
385 .IP "[\fB\-writerand file\fR]" 4
386 .IX Item "[-writerand file]"
387 Writes random data to the specified \fIfile\fR upon exit.
388 This can be used with a subsequent \fB\-rand\fR flag.
390 .IX Header "CRL OPTIONS"
391 .IP "\fB\-gencrl\fR" 4
393 This option generates a \s-1CRL\s0 based on information in the index file.
394 .IP "\fB\-crldays num\fR" 4
395 .IX Item "-crldays num"
396 The number of days before the next \s-1CRL\s0 is due. That is the days from
397 now to place in the \s-1CRL\s0 nextUpdate field.
398 .IP "\fB\-crlhours num\fR" 4
399 .IX Item "-crlhours num"
400 The number of hours before the next \s-1CRL\s0 is due.
401 .IP "\fB\-revoke filename\fR" 4
402 .IX Item "-revoke filename"
403 A filename containing a certificate to revoke.
404 .IP "\fB\-valid filename\fR" 4
405 .IX Item "-valid filename"
406 A filename containing a certificate to add a Valid certificate entry.
407 .IP "\fB\-status serial\fR" 4
408 .IX Item "-status serial"
409 Displays the revocation status of the certificate with the specified
410 serial number and exits.
411 .IP "\fB\-updatedb\fR" 4
413 Updates the database index to purge expired certificates.
414 .IP "\fB\-crl_reason reason\fR" 4
415 .IX Item "-crl_reason reason"
416 Revocation reason, where \fBreason\fR is one of: \fBunspecified\fR, \fBkeyCompromise\fR,
417 \&\fBCACompromise\fR, \fBaffiliationChanged\fR, \fBsuperseded\fR, \fBcessationOfOperation\fR,
418 \&\fBcertificateHold\fR or \fBremoveFromCRL\fR. The matching of \fBreason\fR is case
419 insensitive. Setting any revocation reason will make the \s-1CRL\s0 v2.
421 In practice \fBremoveFromCRL\fR is not particularly useful because it is only used
422 in delta CRLs which are not currently implemented.
423 .IP "\fB\-crl_hold instruction\fR" 4
424 .IX Item "-crl_hold instruction"
425 This sets the \s-1CRL\s0 revocation reason code to \fBcertificateHold\fR and the hold
426 instruction to \fBinstruction\fR which must be an \s-1OID.\s0 Although any \s-1OID\s0 can be
427 used only \fBholdInstructionNone\fR (the use of which is discouraged by \s-1RFC2459\s0)
428 \&\fBholdInstructionCallIssuer\fR or \fBholdInstructionReject\fR will normally be used.
429 .IP "\fB\-crl_compromise time\fR" 4
430 .IX Item "-crl_compromise time"
431 This sets the revocation reason to \fBkeyCompromise\fR and the compromise time to
432 \&\fBtime\fR. \fBtime\fR should be in GeneralizedTime format that is \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
433 .IP "\fB\-crl_CA_compromise time\fR" 4
434 .IX Item "-crl_CA_compromise time"
435 This is the same as \fBcrl_compromise\fR except the revocation reason is set to
436 \&\fBCACompromise\fR.
437 .IP "\fB\-crlexts section\fR" 4
438 .IX Item "-crlexts section"
439 The section of the configuration file containing \s-1CRL\s0 extensions to
440 include. If no \s-1CRL\s0 extension section is present then a V1 \s-1CRL\s0 is
441 created, if the \s-1CRL\s0 extension section is present (even if it is
442 empty) then a V2 \s-1CRL\s0 is created. The \s-1CRL\s0 extensions specified are
443 \&\s-1CRL\s0 extensions and \fBnot\fR \s-1CRL\s0 entry extensions. It should be noted
444 that some software (for example Netscape) can't handle V2 CRLs. See
445 \&\fIx509v3_config\fR\|(5) manual page for details of the
446 extension section format.
447 .SH "CONFIGURATION FILE OPTIONS"
448 .IX Header "CONFIGURATION FILE OPTIONS"
449 The section of the configuration file containing options for \fBca\fR
450 is found as follows: If the \fB\-name\fR command line option is used,
451 then it names the section to be used. Otherwise the section to
452 be used must be named in the \fBdefault_ca\fR option of the \fBca\fR section
453 of the configuration file (or in the default section of the
454 configuration file). Besides \fBdefault_ca\fR, the following options are
455 read directly from the \fBca\fR section:
459 With the exception of \fB\s-1RANDFILE\s0\fR, this is probably a bug and may
460 change in future releases.
462 Many of the configuration file options are identical to command line
463 options. Where the option is present in the configuration file
464 and the command line the command line value is used. Where an
465 option is described as mandatory then it must be present in
466 the configuration file or the command line equivalent (if
468 .IP "\fBoid_file\fR" 4
470 This specifies a file containing additional \fB\s-1OBJECT IDENTIFIERS\s0\fR.
471 Each line of the file should consist of the numerical form of the
472 object identifier followed by white space then the short name followed
473 by white space and finally the long name.
474 .IP "\fBoid_section\fR" 4
475 .IX Item "oid_section"
476 This specifies a section in the configuration file containing extra
477 object identifiers. Each line should consist of the short name of the
478 object identifier followed by \fB=\fR and the numerical form. The short
479 and long names are the same when this option is used.
480 .IP "\fBnew_certs_dir\fR" 4
481 .IX Item "new_certs_dir"
482 The same as the \fB\-outdir\fR command line option. It specifies
483 the directory where new certificates will be placed. Mandatory.
484 .IP "\fBcertificate\fR" 4
485 .IX Item "certificate"
486 The same as \fB\-cert\fR. It gives the file containing the \s-1CA\s0
487 certificate. Mandatory.
488 .IP "\fBprivate_key\fR" 4
489 .IX Item "private_key"
490 Same as the \fB\-keyfile\fR option. The file containing the
491 \&\s-1CA\s0 private key. Mandatory.
492 .IP "\fB\s-1RANDFILE\s0\fR" 4
494 At startup the specified file is loaded into the random number generator,
495 and at exit 256 bytes will be written to it.
496 .IP "\fBdefault_days\fR" 4
497 .IX Item "default_days"
498 The same as the \fB\-days\fR option. The number of days to certify
500 .IP "\fBdefault_startdate\fR" 4
501 .IX Item "default_startdate"
502 The same as the \fB\-startdate\fR option. The start date to certify
503 a certificate for. If not set the current time is used.
504 .IP "\fBdefault_enddate\fR" 4
505 .IX Item "default_enddate"
506 The same as the \fB\-enddate\fR option. Either this option or
507 \&\fBdefault_days\fR (or the command line equivalents) must be
509 .IP "\fBdefault_crl_hours default_crl_days\fR" 4
510 .IX Item "default_crl_hours default_crl_days"
511 The same as the \fB\-crlhours\fR and the \fB\-crldays\fR options. These
512 will only be used if neither command line option is present. At
513 least one of these must be present to generate a \s-1CRL.\s0
514 .IP "\fBdefault_md\fR" 4
515 .IX Item "default_md"
516 The same as the \fB\-md\fR option. Mandatory except where the signing algorithm does
517 not require a digest (i.e. Ed25519 and Ed448).
518 .IP "\fBdatabase\fR" 4
520 The text database file to use. Mandatory. This file must be present
521 though initially it will be empty.
522 .IP "\fBunique_subject\fR" 4
523 .IX Item "unique_subject"
524 If the value \fByes\fR is given, the valid certificate entries in the
525 database must have unique subjects. if the value \fBno\fR is given,
526 several valid certificate entries may have the exact same subject.
527 The default value is \fByes\fR, to be compatible with older (pre 0.9.8)
528 versions of OpenSSL. However, to make \s-1CA\s0 certificate roll-over easier,
529 it's recommended to use the value \fBno\fR, especially if combined with
530 the \fB\-selfsign\fR command line option.
532 Note that it is valid in some circumstances for certificates to be created
533 without any subject. In the case where there are multiple certificates without
534 subjects this does not count as a duplicate.
537 A text file containing the next serial number to use in hex. Mandatory.
538 This file must be present and contain a valid serial number.
539 .IP "\fBcrlnumber\fR" 4
541 A text file containing the next \s-1CRL\s0 number to use in hex. The crl number
542 will be inserted in the CRLs only if this file exists. If this file is
543 present, it must contain a valid \s-1CRL\s0 number.
544 .IP "\fBx509_extensions\fR" 4
545 .IX Item "x509_extensions"
546 The same as \fB\-extensions\fR.
547 .IP "\fBcrl_extensions\fR" 4
548 .IX Item "crl_extensions"
549 The same as \fB\-crlexts\fR.
550 .IP "\fBpreserve\fR" 4
552 The same as \fB\-preserveDN\fR
553 .IP "\fBemail_in_dn\fR" 4
554 .IX Item "email_in_dn"
555 The same as \fB\-noemailDN\fR. If you want the \s-1EMAIL\s0 field to be removed
556 from the \s-1DN\s0 of the certificate simply set this to 'no'. If not present
557 the default is to allow for the \s-1EMAIL\s0 filed in the certificate's \s-1DN.\s0
558 .IP "\fBmsie_hack\fR" 4
560 The same as \fB\-msie_hack\fR
563 The same as \fB\-policy\fR. Mandatory. See the \fB\s-1POLICY FORMAT\s0\fR section
564 for more information.
565 .IP "\fBname_opt\fR, \fBcert_opt\fR" 4
566 .IX Item "name_opt, cert_opt"
567 These options allow the format used to display the certificate details
568 when asking the user to confirm signing. All the options supported by
569 the \fBx509\fR utilities \fB\-nameopt\fR and \fB\-certopt\fR switches can be used
570 here, except the \fBno_signame\fR and \fBno_sigdump\fR are permanently set
571 and cannot be disabled (this is because the certificate signature cannot
572 be displayed because the certificate has not been signed at this point).
574 For convenience the values \fBca_default\fR are accepted by both to produce
577 If neither option is present the format used in earlier versions of
578 OpenSSL is used. Use of the old format is \fBstrongly\fR discouraged because
579 it only displays fields mentioned in the \fBpolicy\fR section, mishandles
580 multicharacter string types and does not display extensions.
581 .IP "\fBcopy_extensions\fR" 4
582 .IX Item "copy_extensions"
583 Determines how extensions in certificate requests should be handled.
584 If set to \fBnone\fR or this option is not present then extensions are
585 ignored and not copied to the certificate. If set to \fBcopy\fR then any
586 extensions present in the request that are not already present are copied
587 to the certificate. If set to \fBcopyall\fR then all extensions in the
588 request are copied to the certificate: if the extension is already present
589 in the certificate it is deleted first. See the \fB\s-1WARNINGS\s0\fR section before
592 The main use of this option is to allow a certificate request to supply
593 values for certain extensions such as subjectAltName.
595 .IX Header "POLICY FORMAT"
596 The policy section consists of a set of variables corresponding to
597 certificate \s-1DN\s0 fields. If the value is \*(L"match\*(R" then the field value
598 must match the same field in the \s-1CA\s0 certificate. If the value is
599 \&\*(L"supplied\*(R" then it must be present. If the value is \*(L"optional\*(R" then
600 it may be present. Any fields not mentioned in the policy section
601 are silently deleted, unless the \fB\-preserveDN\fR option is set but
602 this can be regarded more of a quirk than intended behaviour.
604 .IX Header "SPKAC FORMAT"
605 The input to the \fB\-spkac\fR command line option is a Netscape
606 signed public key and challenge. This will usually come from
607 the \fB\s-1KEYGEN\s0\fR tag in an \s-1HTML\s0 form to create a new private key.
608 It is however possible to create SPKACs using the \fBspkac\fR utility.
610 The file should contain the variable \s-1SPKAC\s0 set to the value of
611 the \s-1SPKAC\s0 and also the required \s-1DN\s0 components as name value pairs.
612 If you need to include the same component twice then it can be
613 preceded by a number and a '.'.
615 When processing \s-1SPKAC\s0 format, the output is \s-1DER\s0 if the \fB\-out\fR
616 flag is used, but \s-1PEM\s0 format if sending to stdout or the \fB\-outdir\fR
619 .IX Header "EXAMPLES"
620 Note: these examples assume that the \fBca\fR directory structure is
621 already set up and the relevant files already exist. This usually
622 involves creating a \s-1CA\s0 certificate and private key with \fBreq\fR, a
623 serial number file and an empty index file and placing them in
624 the relevant directories.
626 To use the sample configuration file below the directories demoCA,
627 demoCA/private and demoCA/newcerts would be created. The \s-1CA\s0
628 certificate would be copied to demoCA/cacert.pem and its private
629 key to demoCA/private/cakey.pem. A file demoCA/serial would be
630 created containing for example \*(L"01\*(R" and the empty index file
633 Sign a certificate request:
636 \& openssl ca \-in req.pem \-out newcert.pem
639 Sign a certificate request, using \s-1CA\s0 extensions:
642 \& openssl ca \-in req.pem \-extensions v3_ca \-out newcert.pem
645 Generate a \s-1CRL\s0
648 \& openssl ca \-gencrl \-out crl.pem
651 Sign several requests:
654 \& openssl ca \-infiles req1.pem req2.pem req3.pem
657 Certify a Netscape \s-1SPKAC:\s0
660 \& openssl ca \-spkac spkac.txt
663 A sample \s-1SPKAC\s0 file (the \s-1SPKAC\s0 line has been truncated for clarity):
666 \& SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
668 \& emailAddress=steve@openssl.org
669 \& 0.OU=OpenSSL Group
670 \& 1.OU=Another Group
673 A sample configuration file with the relevant sections for \fBca\fR:
677 \& default_ca = CA_default # The default ca section
681 \& dir = ./demoCA # top dir
682 \& database = $dir/index.txt # index file.
683 \& new_certs_dir = $dir/newcerts # new certs dir
685 \& certificate = $dir/cacert.pem # The CA cert
686 \& serial = $dir/serial # serial no file
687 \& #rand_serial = yes # for random serial#\*(Aqs
688 \& private_key = $dir/private/cakey.pem# CA private key
689 \& RANDFILE = $dir/private/.rand # random number file
691 \& default_days = 365 # how long to certify for
692 \& default_crl_days= 30 # how long before next CRL
693 \& default_md = md5 # md to use
695 \& policy = policy_any # default policy
696 \& email_in_dn = no # Don\*(Aqt add the email into cert DN
698 \& name_opt = ca_default # Subject name display option
699 \& cert_opt = ca_default # Certificate display option
700 \& copy_extensions = none # Don\*(Aqt copy extensions from request
703 \& countryName = supplied
704 \& stateOrProvinceName = optional
705 \& organizationName = optional
706 \& organizationalUnitName = optional
707 \& commonName = supplied
708 \& emailAddress = optional
712 Note: the location of all files can change either by compile time options,
713 configuration file entries, environment variables or command line options.
714 The values below reflect the default values.
717 \& /usr/local/ssl/lib/openssl.cnf \- master configuration file
718 \& ./demoCA \- main CA directory
719 \& ./demoCA/cacert.pem \- CA certificate
720 \& ./demoCA/private/cakey.pem \- CA private key
721 \& ./demoCA/serial \- CA serial number file
722 \& ./demoCA/serial.old \- CA serial number backup file
723 \& ./demoCA/index.txt \- CA text database file
724 \& ./demoCA/index.txt.old \- CA text database backup file
725 \& ./demoCA/certs \- certificate output file
726 \& ./demoCA/.rnd \- CA random seed information
729 .IX Header "RESTRICTIONS"
730 The text database index file is a critical part of the process and
731 if corrupted it can be difficult to fix. It is theoretically possible
732 to rebuild the index file from all the issued certificates and a current
733 \&\s-1CRL:\s0 however there is no option to do this.
735 V2 \s-1CRL\s0 features like delta CRLs are not currently supported.
737 Although several requests can be input and handled at once it is only
738 possible to include one \s-1SPKAC\s0 or self-signed certificate.
741 The use of an in-memory text database can cause problems when large
742 numbers of certificates are present because, as the name implies
743 the database has to be kept in memory.
745 The \fBca\fR command really needs rewriting or the required functionality
746 exposed at either a command or interface level so a more friendly utility
747 (perl script or \s-1GUI\s0) can handle things properly. The script
748 \&\fB\s-1CA\s0.pl\fR helps a little but not very much.
750 Any fields in a request that are not present in a policy are silently
751 deleted. This does not happen if the \fB\-preserveDN\fR option is used. To
752 enforce the absence of the \s-1EMAIL\s0 field within the \s-1DN,\s0 as suggested by
753 RFCs, regardless the contents of the request' subject the \fB\-noemailDN\fR
754 option can be used. The behaviour should be more friendly and
757 Canceling some commands by refusing to certify a certificate can
758 create an empty file.
760 .IX Header "WARNINGS"
761 The \fBca\fR command is quirky and at times downright unfriendly.
763 The \fBca\fR utility was originally meant as an example of how to do things
764 in a \s-1CA.\s0 It was not supposed to be used as a full blown \s-1CA\s0 itself:
765 nevertheless some people are using it for this purpose.
767 The \fBca\fR command is effectively a single user command: no locking is
768 done on the various files and attempts to run more than one \fBca\fR command
769 on the same database can have unpredictable results.
771 The \fBcopy_extensions\fR option should be used with caution. If care is
772 not taken then it can be a security risk. For example if a certificate
773 request contains a basicConstraints extension with \s-1CA:TRUE\s0 and the
774 \&\fBcopy_extensions\fR value is set to \fBcopyall\fR and the user does not spot
775 this when the certificate is displayed then this will hand the requester
776 a valid \s-1CA\s0 certificate.
778 This situation can be avoided by setting \fBcopy_extensions\fR to \fBcopy\fR
779 and including basicConstraints with \s-1CA:FALSE\s0 in the configuration file.
780 Then if the request contains a basicConstraints extension it will be
783 It is advisable to also include values for other extensions such
784 as \fBkeyUsage\fR to prevent a request supplying its own values.
786 Additional restrictions can be placed on the \s-1CA\s0 certificate itself.
787 For example if the \s-1CA\s0 certificate has:
790 \& basicConstraints = CA:TRUE, pathlen:0
793 then even if a certificate is issued with \s-1CA:TRUE\s0 it will not be valid.
796 Since OpenSSL 1.1.1, the program follows \s-1RFC5280.\s0 Specifically,
797 certificate validity period (specified by any of \fB\-startdate\fR,
798 \&\fB\-enddate\fR and \fB\-days\fR) will be encoded as UTCTime if the dates are
799 earlier than year 2049 (included), and as GeneralizedTime if the dates
800 are in year 2050 or later.
802 .IX Header "SEE ALSO"
803 \&\fIreq\fR\|(1), \fIspkac\fR\|(1), \fIx509\fR\|(1), \s-1\fICA\s0.pl\fR\|(1),
804 \&\fIconfig\fR\|(5), \fIx509v3_config\fR\|(5)
806 .IX Header "COPYRIGHT"
807 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
809 Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
810 this file except in compliance with the License. You can obtain a copy
811 in the file \s-1LICENSE\s0 in the source distribution or at
812 <https://www.openssl.org/source/license.html>.
projects / FreeBSD / FreeBSD.git / blob