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