1OPENSSL-CA(1ossl) OpenSSL OPENSSL-CA(1ossl)
2
6 openssl-ca - sample minimal CA application
7
9 openssl ca [-help] [-verbose] [-config filename] [-name section]
10 [-section section] [-gencrl] [-revoke file] [-valid file] [-status
11 serial] [-updatedb] [-crl_reason reason] [-crl_hold instruction]
12 [-crl_compromise time] [-crl_CA_compromise time] [-crl_lastupdate date]
13 [-crl_nextupdate date] [-crldays days] [-crlhours hours] [-crlsec
14 seconds] [-crlexts section] [-startdate date] [-enddate date] [-days
15 arg] [-md arg] [-policy arg] [-keyfile filename|uri] [-keyform
16 DER|PEM|P12|ENGINE] [-key arg] [-passin arg] [-cert file] [-certform
17 DER|PEM|P12] [-selfsign] [-in file] [-inform DER|<PEM>] [-out file]
18 [-notext] [-dateopt] [-outdir dir] [-infiles] [-spkac file] [-ss_cert
19 file] [-preserveDN] [-noemailDN] [-batch] [-msie_hack] [-extensions
20 section] [-extfile section] [-subj arg] [-utf8] [-sigopt nm:v] [-vfyopt
21 nm:v] [-create_serial] [-rand_serial] [-multivalue-rdn] [-rand files]
22 [-writerand file] [-engine id] [-provider name] [-provider-path path]
23 [-propquery propq] [certreq...]
24
26 This command emulates a CA application. See the WARNINGS especially
27 when considering to use it productively. It can be used to sign
28 certificate requests (CSRs) in a variety of forms and generate
29 certificate revocation lists (CRLs). It also maintains a text database
30 of issued certificates and their status. When signing certificates, a
31 single request can be specified with the -in option, or multiple
32 requests can be processed by specifying a set of certreq files after
33 all options.
34 Note that there are also very lean ways of generating certificates: the
36 req and x509 commands can be used for directly creating certificates.
37 See openssl-req(1) and openssl-x509(1) for details.
38 The descriptions of the ca command options are divided into each
40 purpose.
41
43 -help
44 Print out a usage message.
45 -verbose
47 This prints extra details about the operations being performed.
48 -config filename
50 Specifies the configuration file to use. Optional; for a
51 description of the default value, see "COMMAND SUMMARY" in
52 openssl(1).
53 -name section, -section section
55 Specifies the configuration file section to use (overrides
56 default_ca in the ca section).
57 -in filename
59 An input filename containing a single certificate request (CSR) to
60 be signed by the CA.
61 -inform DER|PEM
63 The format of the data in certificate request input files;
64 unspecified by default. See openssl-format-options(1) for details.
65 -ss_cert filename
67 A single self-signed certificate to be signed by the CA.
68 -spkac filename
70 A file containing a single Netscape signed public key and challenge
71 and additional field values to be signed by the CA. See the SPKAC
72 FORMAT section for information on the required input and output
73 format.
74 -infiles
76 If present this should be the last option, all subsequent arguments
77 are taken as the names of files containing certificate requests.
78 -out filename
80 The output file to output certificates to. The default is standard
81 output. The certificate details will also be printed out to this
82 file in PEM format (except that -spkac outputs DER format).
83 -outdir directory
85 The directory to output certificates to. The certificate will be
86 written to a filename consisting of the serial number in hex with
87 .pem appended.
88 -cert filename
90 The CA certificate, which must match with -keyfile.
91 -certform DER|PEM|P12
93 The format of the data in certificate input files; unspecified by
94 default. See openssl-format-options(1) for details.
95 -keyfile filename|uri
97 The CA private key to sign certificate requests with. This must
98 match with -cert.
99 -keyform DER|PEM|P12|ENGINE
101 The format of the private key input file; unspecified by default.
102 See openssl-format-options(1) for details.
103 -sigopt nm:v
105 Pass options to the signature algorithm during sign operations.
106 Names and values of these options are algorithm-specific.
107 -vfyopt nm:v
109 Pass options to the signature algorithm during verify operations.
110 Names and values of these options are algorithm-specific.
111 This often needs to be given while signing too, because the self-
113 signature of a certificate signing request (CSR) is verified
114 against the included public key, and that verification may need its
115 own set of options.
116 -key password
118 The password used to encrypt the private key. Since on some systems
119 the command line arguments are visible (e.g., when using ps(1) on
120 Unix), this option should be used with caution. Better use
121 -passin.
122 -passin arg
124 The key password source for key files and certificate PKCS#12
125 files. For more information about the format of arg see
126 openssl-passphrase-options(1).
127 -selfsign
129 Indicates the issued certificates are to be signed with the key the
130 certificate requests were signed with (given with -keyfile).
131 Certificate requests signed with a different key are ignored. If
132 -spkac, -ss_cert or -gencrl are given, -selfsign is ignored.
133 A consequence of using -selfsign is that the self-signed
135 certificate appears among the entries in the certificate database
136 (see the configuration option database), and uses the same serial
137 number counter as all other certificates sign with the self-signed
138 certificate.
139 -notext
141 Don't output the text form of a certificate to the output file.
142 -dateopt
144 Specify the date output format. Values are: rfc_822 and iso_8601.
145 Defaults to rfc_822.
146 -startdate date
148 This allows the start date to be explicitly set. The format of the
149 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
150 YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
151 both formats, seconds SS and timezone Z must be present.
152 -enddate date
154 This allows the expiry date to be explicitly set. The format of the
155 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
156 YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
157 both formats, seconds SS and timezone Z must be present.
158 -days arg
160 The number of days to certify the certificate for.
161 -md alg
163 The message digest to use. Any digest supported by the
164 openssl-dgst(1) command can be used. For signing algorithms that do
165 not support a digest (i.e. Ed25519 and Ed448) any message digest
166 that is set is ignored. This option also applies to CRLs.
167 -policy arg
169 This option defines the CA "policy" to use. This is a section in
170 the configuration file which decides which fields should be
171 mandatory or match the CA certificate. Check out the POLICY FORMAT
172 section for more information.
173 -msie_hack
175 This is a deprecated option to make this command work with very old
176 versions of the IE certificate enrollment control "certenr3". It
177 used UniversalStrings for almost everything. Since the old control
178 has various security bugs its use is strongly discouraged.
179 -preserveDN
181 Normally the DN order of a certificate is the same as the order of
182 the fields in the relevant policy section. When this option is set
183 the order is the same as the request. This is largely for
184 compatibility with the older IE enrollment control which would only
185 accept certificates if their DNs match the order of the request.
186 This is not needed for Xenroll.
187 -noemailDN
189 The DN of a certificate can contain the EMAIL field if present in
190 the request DN, however, it is good policy just having the e-mail
191 set into the altName extension of the certificate. When this option
192 is set the EMAIL field is removed from the certificate' subject and
193 set only in the, eventually present, extensions. The email_in_dn
194 keyword can be used in the configuration file to enable this
195 behaviour.
196 -batch
198 This sets the batch mode. In this mode no questions will be asked
199 and all certificates will be certified automatically.
200 -extensions section
202 The section of the configuration file containing certificate
203 extensions to be added when a certificate is issued (defaults to
204 x509_extensions unless the -extfile option is used). If no X.509
205 extensions are specified then a V1 certificate is created, else a
206 V3 certificate is created. See the x509v3_config(5) manual page
207 for details of the extension section format.
208 -extfile file
210 An additional configuration file to read certificate extensions
211 from (using the default section unless the -extensions option is
212 also used).
213 -subj arg
215 Supersedes subject name given in the request.
216 The arg must be formatted as
218 "/type0=value0/type1=value1/type2=...". Special characters may be
219 escaped by "\" (backslash), whitespace is retained. Empty values
220 are permitted, but the corresponding type will not be included in
221 the resulting certificate. Giving a single "/" will lead to an
222 empty sequence of RDNs (a NULL-DN). Multi-valued RDNs can be
223 formed by placing a "+" character instead of a "/" between the
224 AttributeValueAssertions (AVAs) that specify the members of the
225 set. Example:
226 "/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe"
228 -utf8
230 This option causes field values to be interpreted as UTF8 strings,
231 by default they are interpreted as ASCII. This means that the field
232 values, whether prompted from a terminal or obtained from a
233 configuration file, must be valid UTF8 strings.
234 -create_serial
236 If reading serial from the text file as specified in the
237 configuration fails, specifying this option creates a new random
238 serial to be used as next serial number. To get random serial
239 numbers, use the -rand_serial flag instead; this should only be
240 used for simple error-recovery.
241 -rand_serial
243 Generate a large random number to use as the serial number. This
244 overrides any option or configuration to use a serial number file.
245 -multivalue-rdn
247 This option has been deprecated and has no effect.
248 -rand files, -writerand file
250 See "Random State Options" in openssl(1) for details.
251 -engine id
253 See "Engine Options" in openssl(1). This option is deprecated.
254 -provider name
256 -provider-path path
257 -propquery propq
258 See "Provider Options" in openssl(1), provider(7), and property(7).
259
261 -gencrl
262 This option generates a CRL based on information in the index file.
263 -crl_lastupdate time
265 Allows the value of the CRL's lastUpdate field to be explicitly
266 set; if this option is not present, the current time is used.
267 Accepts times in YYMMDDHHMMSSZ format (the same as an ASN1 UTCTime
268 structure) or YYYYMMDDHHMMSSZ format (the same as an ASN1
269 GeneralizedTime structure).
270 -crl_nextupdate time
272 Allows the value of the CRL's nextUpdate field to be explicitly
273 set; if this option is present, any values given for -crldays,
274 -crlhours and -crlsec are ignored. Accepts times in the same
275 formats as -crl_lastupdate.
276 -crldays num
278 The number of days before the next CRL is due. That is the days
279 from now to place in the CRL nextUpdate field.
280 -crlhours num
282 The number of hours before the next CRL is due.
283 -crlsec num
285 The number of seconds before the next CRL is due.
286 -revoke filename
288 A filename containing a certificate to revoke.
289 -valid filename
291 A filename containing a certificate to add a Valid certificate
292 entry.
293 -status serial
295 Displays the revocation status of the certificate with the
296 specified serial number and exits.
297 -updatedb
299 Updates the database index to purge expired certificates.
300 -crl_reason reason
302 Revocation reason, where reason is one of: unspecified,
303 keyCompromise, CACompromise, affiliationChanged, superseded,
304 cessationOfOperation, certificateHold or removeFromCRL. The
305 matching of reason is case insensitive. Setting any revocation
306 reason will make the CRL v2.
307 In practice removeFromCRL is not particularly useful because it is
309 only used in delta CRLs which are not currently implemented.
310 -crl_hold instruction
312 This sets the CRL revocation reason code to certificateHold and the
313 hold instruction to instruction which must be an OID. Although any
314 OID can be used only holdInstructionNone (the use of which is
315 discouraged by RFC2459) holdInstructionCallIssuer or
316 holdInstructionReject will normally be used.
317 -crl_compromise time
319 This sets the revocation reason to keyCompromise and the compromise
320 time to time. time should be in GeneralizedTime format that is
321 YYYYMMDDHHMMSSZ.
322 -crl_CA_compromise time
324 This is the same as crl_compromise except the revocation reason is
325 set to CACompromise.
326 -crlexts section
328 The section of the configuration file containing CRL extensions to
329 include. If no CRL extension section is present then a V1 CRL is
330 created, if the CRL extension section is present (even if it is
331 empty) then a V2 CRL is created. The CRL extensions specified are
332 CRL extensions and not CRL entry extensions. It should be noted
333 that some software (for example Netscape) can't handle V2 CRLs. See
334 x509v3_config(5) manual page for details of the extension section
335 format.
336
338 The section of the configuration file containing options for this
339 command is found as follows: If the -name command line option is used,
340 then it names the section to be used. Otherwise the section to be used
341 must be named in the default_ca option of the ca section of the
342 configuration file (or in the default section of the configuration
343 file). Besides default_ca, the following options are read directly from
344 the ca section:
345 RANDFILE
346 preserve
347 msie_hack With the exception of RANDFILE, this is probably a bug and
348 may change in future releases.
349 Many of the configuration file options are identical to command line
351 options. Where the option is present in the configuration file and the
352 command line the command line value is used. Where an option is
353 described as mandatory then it must be present in the configuration
354 file or the command line equivalent (if any) used.
355 oid_file
357 This specifies a file containing additional OBJECT IDENTIFIERS.
358 Each line of the file should consist of the numerical form of the
359 object identifier followed by whitespace then the short name
360 followed by whitespace and finally the long name.
361 oid_section
363 This specifies a section in the configuration file containing extra
364 object identifiers. Each line should consist of the short name of
365 the object identifier followed by = and the numerical form. The
366 short and long names are the same when this option is used.
367 new_certs_dir
369 The same as the -outdir command line option. It specifies the
370 directory where new certificates will be placed. Mandatory.
371 certificate
373 The same as -cert. It gives the file containing the CA certificate.
374 Mandatory.
375 private_key
377 Same as the -keyfile option. The file containing the CA private
378 key. Mandatory.
379 RANDFILE
381 At startup the specified file is loaded into the random number
382 generator, and at exit 256 bytes will be written to it. (Note:
383 Using a RANDFILE is not necessary anymore, see the "HISTORY"
384 section.
385 default_days
387 The same as the -days option. The number of days to certify a
388 certificate for.
389 default_startdate
391 The same as the -startdate option. The start date to certify a
392 certificate for. If not set the current time is used.
393 default_enddate
395 The same as the -enddate option. Either this option or default_days
396 (or the command line equivalents) must be present.
397 default_crl_hours default_crl_days
399 The same as the -crlhours and the -crldays options. These will only
400 be used if neither command line option is present. At least one of
401 these must be present to generate a CRL.
402 default_md
404 The same as the -md option. Mandatory except where the signing
405 algorithm does not require a digest (i.e. Ed25519 and Ed448).
406 database
408 The text database file to use. Mandatory. This file must be present
409 though initially it will be empty.
410 unique_subject
412 If the value yes is given, the valid certificate entries in the
413 database must have unique subjects. if the value no is given,
414 several valid certificate entries may have the exact same subject.
415 The default value is yes, to be compatible with older (pre 0.9.8)
416 versions of OpenSSL. However, to make CA certificate roll-over
417 easier, it's recommended to use the value no, especially if
418 combined with the -selfsign command line option.
419 Note that it is valid in some circumstances for certificates to be
421 created without any subject. In the case where there are multiple
422 certificates without subjects this does not count as a duplicate.
423 serial
425 A text file containing the next serial number to use in hex.
426 Mandatory. This file must be present and contain a valid serial
427 number.
428 crlnumber
430 A text file containing the next CRL number to use in hex. The crl
431 number will be inserted in the CRLs only if this file exists. If
432 this file is present, it must contain a valid CRL number.
433 x509_extensions
435 A fallback to the -extensions option.
436 crl_extensions
438 A fallback to the -crlexts option.
439 preserve
441 The same as -preserveDN
442 email_in_dn
444 The same as -noemailDN. If you want the EMAIL field to be removed
445 from the DN of the certificate simply set this to 'no'. If not
446 present the default is to allow for the EMAIL filed in the
447 certificate's DN.
448 msie_hack
450 The same as -msie_hack
451 policy
453 The same as -policy. Mandatory. See the POLICY FORMAT section for
454 more information.
455 name_opt, cert_opt
457 These options allow the format used to display the certificate
458 details when asking the user to confirm signing. All the options
459 supported by the x509 utilities -nameopt and -certopt switches can
460 be used here, except the no_signame and no_sigdump are permanently
461 set and cannot be disabled (this is because the certificate
462 signature cannot be displayed because the certificate has not been
463 signed at this point).
464 For convenience the values ca_default are accepted by both to
466 produce a reasonable output.
467 If neither option is present the format used in earlier versions of
469 OpenSSL is used. Use of the old format is strongly discouraged
470 because it only displays fields mentioned in the policy section,
471 mishandles multicharacter string types and does not display
472 extensions.
473 copy_extensions
475 Determines how extensions in certificate requests should be
476 handled. If set to none or this option is not present then
477 extensions are ignored and not copied to the certificate. If set to
478 copy then any extensions present in the request that are not
479 already present are copied to the certificate. If set to copyall
480 then all extensions in the request are copied to the certificate:
481 if the extension is already present in the certificate it is
482 deleted first. See the WARNINGS section before using this option.
483 The main use of this option is to allow a certificate request to
485 supply values for certain extensions such as subjectAltName.
486
488 The policy section consists of a set of variables corresponding to
489 certificate DN fields. If the value is "match" then the field value
490 must match the same field in the CA certificate. If the value is
491 "supplied" then it must be present. If the value is "optional" then it
492 may be present. Any fields not mentioned in the policy section are
493 silently deleted, unless the -preserveDN option is set but this can be
494 regarded more of a quirk than intended behaviour.
495
497 The input to the -spkac command line option is a Netscape signed public
498 key and challenge. This will usually come from the KEYGEN tag in an
499 HTML form to create a new private key. It is however possible to
500 create SPKACs using openssl-spkac(1).
501 The file should contain the variable SPKAC set to the value of the
503 SPKAC and also the required DN components as name value pairs. If you
504 need to include the same component twice then it can be preceded by a
505 number and a '.'.
506 When processing SPKAC format, the output is DER if the -out flag is
508 used, but PEM format if sending to stdout or the -outdir flag is used.
509
511 Note: these examples assume that the directory structure this command
512 assumes is already set up and the relevant files already exist. This
513 usually involves creating a CA certificate and private key with
514 openssl-req(1), a serial number file and an empty index file and
515 placing them in the relevant directories.
516 To use the sample configuration file below the directories demoCA,
518 demoCA/private and demoCA/newcerts would be created. The CA certificate
519 would be copied to demoCA/cacert.pem and its private key to
520 demoCA/private/cakey.pem. A file demoCA/serial would be created
521 containing for example "01" and the empty index file demoCA/index.txt.
522 Sign a certificate request:
524 openssl ca -in req.pem -out newcert.pem
526 Sign an SM2 certificate request:
528 openssl ca -in sm2.csr -out sm2.crt -md sm3 \
530 -sigopt "distid:1234567812345678" \
531 -vfyopt "distid:1234567812345678"
532 Sign a certificate request, using CA extensions:
534 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
536 Generate a CRL
538 openssl ca -gencrl -out crl.pem
540 Sign several requests:
542 openssl ca -infiles req1.pem req2.pem req3.pem
544 Certify a Netscape SPKAC:
546 openssl ca -spkac spkac.txt
548 A sample SPKAC file (the SPKAC line has been truncated for clarity):
550 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
552 CN=Steve Test
553 emailAddress=steve@openssl.org
554 0.OU=OpenSSL Group
555 1.OU=Another Group
556 A sample configuration file with the relevant sections for this
558 command:
559 [ ca ]
561 default_ca = CA_default # The default ca section
562 [ CA_default ]
564 dir = ./demoCA # top dir
566 database = $dir/index.txt # index file.
567 new_certs_dir = $dir/newcerts # new certs dir
568 certificate = $dir/cacert.pem # The CA cert
570 serial = $dir/serial # serial no file
571 #rand_serial = yes # for random serial#'s
572 private_key = $dir/private/cakey.pem# CA private key
573 default_days = 365 # how long to certify for
575 default_crl_days= 30 # how long before next CRL
576 default_md = md5 # md to use
577 policy = policy_any # default policy
579 email_in_dn = no # Don't add the email into cert DN
580 name_opt = ca_default # Subject name display option
582 cert_opt = ca_default # Certificate display option
583 copy_extensions = none # Don't copy extensions from request
584 [ policy_any ]
586 countryName = supplied
587 stateOrProvinceName = optional
588 organizationName = optional
589 organizationalUnitName = optional
590 commonName = supplied
591 emailAddress = optional
592
594 Note: the location of all files can change either by compile time
595 options, configuration file entries, environment variables or command
596 line options. The values below reflect the default values.
597 /usr/local/ssl/lib/openssl.cnf - master configuration file
599 ./demoCA - main CA directory
600 ./demoCA/cacert.pem - CA certificate
601 ./demoCA/private/cakey.pem - CA private key
602 ./demoCA/serial - CA serial number file
603 ./demoCA/serial.old - CA serial number backup file
604 ./demoCA/index.txt - CA text database file
605 ./demoCA/index.txt.old - CA text database backup file
606 ./demoCA/certs - certificate output file
607
609 The text database index file is a critical part of the process and if
610 corrupted it can be difficult to fix. It is theoretically possible to
611 rebuild the index file from all the issued certificates and a current
612 CRL: however there is no option to do this.
613 V2 CRL features like delta CRLs are not currently supported.
615 Although several requests can be input and handled at once it is only
617 possible to include one SPKAC or self-signed certificate.
618
620 This command is quirky and at times downright unfriendly.
621 The use of an in-memory text database can cause problems when large
623 numbers of certificates are present because, as the name implies the
624 database has to be kept in memory.
625 This command really needs rewriting or the required functionality
627 exposed at either a command or interface level so that a more user-
628 friendly replacement could handle things properly. The script CA.pl
629 helps a little but not very much.
630 Any fields in a request that are not present in a policy are silently
632 deleted. This does not happen if the -preserveDN option is used. To
633 enforce the absence of the EMAIL field within the DN, as suggested by
634 RFCs, regardless the contents of the request' subject the -noemailDN
635 option can be used. The behaviour should be more friendly and
636 configurable.
637 Canceling some commands by refusing to certify a certificate can create
639 an empty file.
640
642 This command was originally meant as an example of how to do things in
643 a CA. Its code does not have production quality. It was not supposed
644 to be used as a full blown CA itself, nevertheless some people are
645 using it for this purpose at least internally. When doing so, specific
646 care should be taken to properly secure the private key(s) used for
647 signing certificates. It is advisable to keep them in a secure HW
648 storage such as a smart card or HSM and access them via a suitable
649 engine or crypto provider.
650 This command command is effectively a single user command: no locking
652 is done on the various files and attempts to run more than one openssl
653 ca command on the same database can have unpredictable results.
654 The copy_extensions option should be used with caution. If care is not
656 taken then it can be a security risk. For example if a certificate
657 request contains a basicConstraints extension with CA:TRUE and the
658 copy_extensions value is set to copyall and the user does not spot this
659 when the certificate is displayed then this will hand the requester a
660 valid CA certificate. This situation can be avoided by setting
661 copy_extensions to copy and including basicConstraints with CA:FALSE in
662 the configuration file. Then if the request contains a
663 basicConstraints extension it will be ignored.
664 It is advisable to also include values for other extensions such as
666 keyUsage to prevent a request supplying its own values.
667 Additional restrictions can be placed on the CA certificate itself.
669 For example if the CA certificate has:
670 basicConstraints = CA:TRUE, pathlen:0
672 then even if a certificate is issued with CA:TRUE it will not be valid.
674
676 Since OpenSSL 1.1.1, the program follows RFC5280. Specifically,
677 certificate validity period (specified by any of -startdate, -enddate
678 and -days) and CRL last/next update time (specified by any of
679 -crl_lastupdate, -crl_nextupdate, -crldays, -crlhours and -crlsec) will
680 be encoded as UTCTime if the dates are earlier than year 2049
681 (included), and as GeneralizedTime if the dates are in year 2050 or
682 later.
683 OpenSSL 1.1.1 introduced a new random generator (CSPRNG) with an
685 improved seeding mechanism. The new seeding mechanism makes it
686 unnecessary to define a RANDFILE for saving and restoring randomness.
687 This option is retained mainly for compatibility reasons.
688 The -section option was added in OpenSSL 3.0.0.
690 The -multivalue-rdn option has become obsolete in OpenSSL 3.0.0 and has
692 no effect.
693 The -engine option was deprecated in OpenSSL 3.0.
695
697 openssl(1), openssl-req(1), openssl-spkac(1), openssl-x509(1),
698 CA.pl(1), config(5), x509v3_config(5)
699
701 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
702 Licensed under the Apache License 2.0 (the "License"). You may not use
704 this file except in compliance with the License. You can obtain a copy
705 in the file LICENSE in the source distribution or at
706 <https://www.openssl.org/source/license.html>.
7073.1.1 2023-08-31 OPENSSL-CA(1ossl)