1CA(1) OpenSSL CA(1)
2
6 openssl-ca, ca - sample minimal CA application
7
9 openssl ca [-help] [-verbose] [-config filename] [-name section]
10 [-gencrl] [-revoke file] [-valid file] [-status serial] [-updatedb]
11 [-crl_reason reason] [-crl_hold instruction] [-crl_compromise time]
12 [-crl_CA_compromise time] [-crldays days] [-crlhours hours] [-crlexts
13 section] [-startdate date] [-enddate date] [-days arg] [-md arg]
14 [-policy arg] [-keyfile arg] [-keyform PEM|DER] [-key arg] [-passin
15 arg] [-cert file] [-selfsign] [-in file] [-out file] [-notext] [-outdir
16 dir] [-infiles] [-spkac file] [-ss_cert file] [-preserveDN]
17 [-noemailDN] [-batch] [-msie_hack] [-extensions section] [-extfile
18 section] [-engine id] [-subj arg] [-utf8] [-sigopt nm:v]
19 [-create_serial] [-rand_serial] [-multivalue-rdn] [-rand file...]
20 [-writerand file]
21
23 The ca command is a minimal CA application. It can be used to sign
24 certificate requests in a variety of forms and generate CRLs it also
25 maintains a text database of issued certificates and their status.
26 The options descriptions will be divided into each purpose.
28
30 -help
31 Print out a usage message.
32 -verbose
34 This prints extra details about the operations being performed.
35 -config filename
37 Specifies the configuration file to use. Optional; for a
38 description of the default value, see "COMMAND SUMMARY" in
39 openssl(1).
40 -name section
42 Specifies the configuration file section to use (overrides
43 default_ca in the ca section).
44 -in filename
46 An input filename containing a single certificate request to be
47 signed by the CA.
48 -ss_cert filename
50 A single self-signed certificate to be signed by the CA.
51 -spkac filename
53 A file containing a single Netscape signed public key and challenge
54 and additional field values to be signed by the CA. See the SPKAC
55 FORMAT section for information on the required input and output
56 format.
57 -infiles
59 If present this should be the last option, all subsequent arguments
60 are taken as the names of files containing certificate requests.
61 -out filename
63 The output file to output certificates to. The default is standard
64 output. The certificate details will also be printed out to this
65 file in PEM format (except that -spkac outputs DER format).
66 -outdir directory
68 The directory to output certificates to. The certificate will be
69 written to a filename consisting of the serial number in hex with
70 ".pem" appended.
71 -cert
73 The CA certificate file.
74 -keyfile filename
76 The private key to sign requests with.
77 -keyform PEM|DER
79 The format of the data in the private key file. The default is
80 PEM.
81 -sigopt nm:v
83 Pass options to the signature algorithm during sign or verify
84 operations. Names and values of these options are algorithm-
85 specific.
86 -key password
88 The password used to encrypt the private key. Since on some systems
89 the command line arguments are visible (e.g. Unix with the 'ps'
90 utility) this option should be used with caution.
91 -selfsign
93 Indicates the issued certificates are to be signed with the key the
94 certificate requests were signed with (given with -keyfile).
95 Certificate requests signed with a different key are ignored. If
96 -spkac, -ss_cert or -gencrl are given, -selfsign is ignored.
97 A consequence of using -selfsign is that the self-signed
99 certificate appears among the entries in the certificate database
100 (see the configuration option database), and uses the same serial
101 number counter as all other certificates sign with the self-signed
102 certificate.
103 -passin arg
105 The key password source. For more information about the format of
106 arg see "Pass Phrase Options" in openssl(1).
107 -notext
109 Don't output the text form of a certificate to the output file.
110 -startdate date
112 This allows the start date to be explicitly set. The format of the
113 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
114 YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
115 both formats, seconds SS and timezone Z must be present.
116 -enddate date
118 This allows the expiry date to be explicitly set. The format of the
119 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
120 YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
121 both formats, seconds SS and timezone Z must be present.
122 -days arg
124 The number of days to certify the certificate for.
125 -md alg
127 The message digest to use. Any digest supported by the OpenSSL
128 dgst command can be used. For signing algorithms that do not
129 support a digest (i.e. Ed25519 and Ed448) any message digest that
130 is set is ignored. This option also applies to CRLs.
131 -policy arg
133 This option defines the CA "policy" to use. This is a section in
134 the configuration file which decides which fields should be
135 mandatory or match the CA certificate. Check out the POLICY FORMAT
136 section for more information.
137 -msie_hack
139 This is a deprecated option to make ca work with very old versions
140 of the IE certificate enrollment control "certenr3". It used
141 UniversalStrings for almost everything. Since the old control has
142 various security bugs its use is strongly discouraged.
143 -preserveDN
145 Normally the DN order of a certificate is the same as the order of
146 the fields in the relevant policy section. When this option is set
147 the order is the same as the request. This is largely for
148 compatibility with the older IE enrollment control which would only
149 accept certificates if their DNs match the order of the request.
150 This is not needed for Xenroll.
151 -noemailDN
153 The DN of a certificate can contain the EMAIL field if present in
154 the request DN, however, it is good policy just having the e-mail
155 set into the altName extension of the certificate. When this option
156 is set the EMAIL field is removed from the certificate' subject and
157 set only in the, eventually present, extensions. The email_in_dn
158 keyword can be used in the configuration file to enable this
159 behaviour.
160 -batch
162 This sets the batch mode. In this mode no questions will be asked
163 and all certificates will be certified automatically.
164 -extensions section
166 The section of the configuration file containing certificate
167 extensions to be added when a certificate is issued (defaults to
168 x509_extensions unless the -extfile option is used). If no
169 extension section is present then, a V1 certificate is created. If
170 the extension section is present (even if it is empty), then a V3
171 certificate is created. See the x509v3_config(5) manual page for
172 details of the extension section format.
173 -extfile file
175 An additional configuration file to read certificate extensions
176 from (using the default section unless the -extensions option is
177 also used).
178 -engine id
180 Specifying an engine (by its unique id string) will cause ca to
181 attempt to obtain a functional reference to the specified engine,
182 thus initialising it if needed. The engine will then be set as the
183 default for all available algorithms.
184 -subj arg
186 Supersedes subject name given in the request. The arg must be
187 formatted as /type0=value0/type1=value1/type2=.... Keyword
188 characters may be escaped by \ (backslash), and whitespace is
189 retained. Empty values are permitted, but the corresponding type
190 will not be included in the resulting certificate.
191 -utf8
193 This option causes field values to be interpreted as UTF8 strings,
194 by default they are interpreted as ASCII. This means that the field
195 values, whether prompted from a terminal or obtained from a
196 configuration file, must be valid UTF8 strings.
197 -create_serial
199 If reading serial from the text file as specified in the
200 configuration fails, specifying this option creates a new random
201 serial to be used as next serial number. To get random serial
202 numbers, use the -rand_serial flag instead; this should only be
203 used for simple error-recovery.
204 -rand_serial
206 Generate a large random number to use as the serial number. This
207 overrides any option or configuration to use a serial number file.
208 -multivalue-rdn
210 This option causes the -subj argument to be interpreted with full
211 support for multivalued RDNs. Example:
212 /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
214 If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
216 -rand file...
218 A file or files containing random data used to seed the random
219 number generator. Multiple files can be specified separated by an
220 OS-dependent character. The separator is ; for MS-Windows, , for
221 OpenVMS, and : for all others.
222 [-writerand file]
224 Writes random data to the specified file upon exit. This can be
225 used with a subsequent -rand flag.
226
228 -gencrl
229 This option generates a CRL based on information in the index file.
230 -crldays num
232 The number of days before the next CRL is due. That is the days
233 from now to place in the CRL nextUpdate field.
234 -crlhours num
236 The number of hours before the next CRL is due.
237 -revoke filename
239 A filename containing a certificate to revoke.
240 -valid filename
242 A filename containing a certificate to add a Valid certificate
243 entry.
244 -status serial
246 Displays the revocation status of the certificate with the
247 specified serial number and exits.
248 -updatedb
250 Updates the database index to purge expired certificates.
251 -crl_reason reason
253 Revocation reason, where reason is one of: unspecified,
254 keyCompromise, CACompromise, affiliationChanged, superseded,
255 cessationOfOperation, certificateHold or removeFromCRL. The
256 matching of reason is case insensitive. Setting any revocation
257 reason will make the CRL v2.
258 In practice removeFromCRL is not particularly useful because it is
260 only used in delta CRLs which are not currently implemented.
261 -crl_hold instruction
263 This sets the CRL revocation reason code to certificateHold and the
264 hold instruction to instruction which must be an OID. Although any
265 OID can be used only holdInstructionNone (the use of which is
266 discouraged by RFC2459) holdInstructionCallIssuer or
267 holdInstructionReject will normally be used.
268 -crl_compromise time
270 This sets the revocation reason to keyCompromise and the compromise
271 time to time. time should be in GeneralizedTime format that is
272 YYYYMMDDHHMMSSZ.
273 -crl_CA_compromise time
275 This is the same as crl_compromise except the revocation reason is
276 set to CACompromise.
277 -crlexts section
279 The section of the configuration file containing CRL extensions to
280 include. If no CRL extension section is present then a V1 CRL is
281 created, if the CRL extension section is present (even if it is
282 empty) then a V2 CRL is created. The CRL extensions specified are
283 CRL extensions and not CRL entry extensions. It should be noted
284 that some software (for example Netscape) can't handle V2 CRLs. See
285 x509v3_config(5) manual page for details of the extension section
286 format.
287
289 The section of the configuration file containing options for ca is
290 found as follows: If the -name command line option is used, then it
291 names the section to be used. Otherwise the section to be used must be
292 named in the default_ca option of the ca section of the configuration
293 file (or in the default section of the configuration file). Besides
294 default_ca, the following options are read directly from the ca
295 section:
296 RANDFILE
297 preserve
298 msie_hack With the exception of RANDFILE, this is probably a bug and
299 may change in future releases.
300 Many of the configuration file options are identical to command line
302 options. Where the option is present in the configuration file and the
303 command line the command line value is used. Where an option is
304 described as mandatory then it must be present in the configuration
305 file or the command line equivalent (if any) used.
306 oid_file
308 This specifies a file containing additional OBJECT IDENTIFIERS.
309 Each line of the file should consist of the numerical form of the
310 object identifier followed by white space then the short name
311 followed by white space and finally the long name.
312 oid_section
314 This specifies a section in the configuration file containing extra
315 object identifiers. Each line should consist of the short name of
316 the object identifier followed by = and the numerical form. The
317 short and long names are the same when this option is used.
318 new_certs_dir
320 The same as the -outdir command line option. It specifies the
321 directory where new certificates will be placed. Mandatory.
322 certificate
324 The same as -cert. It gives the file containing the CA certificate.
325 Mandatory.
326 private_key
328 Same as the -keyfile option. The file containing the CA private
329 key. Mandatory.
330 RANDFILE
332 At startup the specified file is loaded into the random number
333 generator, and at exit 256 bytes will be written to it.
334 default_days
336 The same as the -days option. The number of days to certify a
337 certificate for.
338 default_startdate
340 The same as the -startdate option. The start date to certify a
341 certificate for. If not set the current time is used.
342 default_enddate
344 The same as the -enddate option. Either this option or default_days
345 (or the command line equivalents) must be present.
346 default_crl_hours default_crl_days
348 The same as the -crlhours and the -crldays options. These will only
349 be used if neither command line option is present. At least one of
350 these must be present to generate a CRL.
351 default_md
353 The same as the -md option. Mandatory except where the signing
354 algorithm does not require a digest (i.e. Ed25519 and Ed448).
355 database
357 The text database file to use. Mandatory. This file must be present
358 though initially it will be empty.
359 unique_subject
361 If the value yes is given, the valid certificate entries in the
362 database must have unique subjects. if the value no is given,
363 several valid certificate entries may have the exact same subject.
364 The default value is yes, to be compatible with older (pre 0.9.8)
365 versions of OpenSSL. However, to make CA certificate roll-over
366 easier, it's recommended to use the value no, especially if
367 combined with the -selfsign command line option.
368 Note that it is valid in some circumstances for certificates to be
370 created without any subject. In the case where there are multiple
371 certificates without subjects this does not count as a duplicate.
372 serial
374 A text file containing the next serial number to use in hex.
375 Mandatory. This file must be present and contain a valid serial
376 number.
377 crlnumber
379 A text file containing the next CRL number to use in hex. The crl
380 number will be inserted in the CRLs only if this file exists. If
381 this file is present, it must contain a valid CRL number.
382 x509_extensions
384 The same as -extensions.
385 crl_extensions
387 The same as -crlexts.
388 preserve
390 The same as -preserveDN
391 email_in_dn
393 The same as -noemailDN. If you want the EMAIL field to be removed
394 from the DN of the certificate simply set this to 'no'. If not
395 present the default is to allow for the EMAIL filed in the
396 certificate's DN.
397 msie_hack
399 The same as -msie_hack
400 policy
402 The same as -policy. Mandatory. See the POLICY FORMAT section for
403 more information.
404 name_opt, cert_opt
406 These options allow the format used to display the certificate
407 details when asking the user to confirm signing. All the options
408 supported by the x509 utilities -nameopt and -certopt switches can
409 be used here, except the no_signame and no_sigdump are permanently
410 set and cannot be disabled (this is because the certificate
411 signature cannot be displayed because the certificate has not been
412 signed at this point).
413 For convenience the values ca_default are accepted by both to
415 produce a reasonable output.
416 If neither option is present the format used in earlier versions of
418 OpenSSL is used. Use of the old format is strongly discouraged
419 because it only displays fields mentioned in the policy section,
420 mishandles multicharacter string types and does not display
421 extensions.
422 copy_extensions
424 Determines how extensions in certificate requests should be
425 handled. If set to none or this option is not present then
426 extensions are ignored and not copied to the certificate. If set to
427 copy then any extensions present in the request that are not
428 already present are copied to the certificate. If set to copyall
429 then all extensions in the request are copied to the certificate:
430 if the extension is already present in the certificate it is
431 deleted first. See the WARNINGS section before using this option.
432 The main use of this option is to allow a certificate request to
434 supply values for certain extensions such as subjectAltName.
435
437 The policy section consists of a set of variables corresponding to
438 certificate DN fields. If the value is "match" then the field value
439 must match the same field in the CA certificate. If the value is
440 "supplied" then it must be present. If the value is "optional" then it
441 may be present. Any fields not mentioned in the policy section are
442 silently deleted, unless the -preserveDN option is set but this can be
443 regarded more of a quirk than intended behaviour.
444
446 The input to the -spkac command line option is a Netscape signed public
447 key and challenge. This will usually come from the KEYGEN tag in an
448 HTML form to create a new private key. It is however possible to
449 create SPKACs using the spkac utility.
450 The file should contain the variable SPKAC set to the value of the
452 SPKAC and also the required DN components as name value pairs. If you
453 need to include the same component twice then it can be preceded by a
454 number and a '.'.
455 When processing SPKAC format, the output is DER if the -out flag is
457 used, but PEM format if sending to stdout or the -outdir flag is used.
458
460 Note: these examples assume that the ca directory structure is already
461 set up and the relevant files already exist. This usually involves
462 creating a CA certificate and private key with req, a serial number
463 file and an empty index file and placing them in the relevant
464 directories.
465 To use the sample configuration file below the directories demoCA,
467 demoCA/private and demoCA/newcerts would be created. The CA certificate
468 would be copied to demoCA/cacert.pem and its private key to
469 demoCA/private/cakey.pem. A file demoCA/serial would be created
470 containing for example "01" and the empty index file demoCA/index.txt.
471 Sign a certificate request:
473 openssl ca -in req.pem -out newcert.pem
475 Sign a certificate request, using CA extensions:
477 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
479 Generate a CRL
481 openssl ca -gencrl -out crl.pem
483 Sign several requests:
485 openssl ca -infiles req1.pem req2.pem req3.pem
487 Certify a Netscape SPKAC:
489 openssl ca -spkac spkac.txt
491 A sample SPKAC file (the SPKAC line has been truncated for clarity):
493 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
495 CN=Steve Test
496 emailAddress=steve@openssl.org
497 0.OU=OpenSSL Group
498 1.OU=Another Group
499 A sample configuration file with the relevant sections for ca:
501 [ ca ]
503 default_ca = CA_default # The default ca section
504 [ CA_default ]
506 dir = ./demoCA # top dir
508 database = $dir/index.txt # index file.
509 new_certs_dir = $dir/newcerts # new certs dir
510 certificate = $dir/cacert.pem # The CA cert
512 serial = $dir/serial # serial no file
513 #rand_serial = yes # for random serial#'s
514 private_key = $dir/private/cakey.pem# CA private key
515 RANDFILE = $dir/private/.rand # random number file
516 default_days = 365 # how long to certify for
518 default_crl_days= 30 # how long before next CRL
519 default_md = md5 # md to use
520 policy = policy_any # default policy
522 email_in_dn = no # Don't add the email into cert DN
523 name_opt = ca_default # Subject name display option
525 cert_opt = ca_default # Certificate display option
526 copy_extensions = none # Don't copy extensions from request
527 [ policy_any ]
529 countryName = supplied
530 stateOrProvinceName = optional
531 organizationName = optional
532 organizationalUnitName = optional
533 commonName = supplied
534 emailAddress = optional
535
537 Note: the location of all files can change either by compile time
538 options, configuration file entries, environment variables or command
539 line options. The values below reflect the default values.
540 /usr/local/ssl/lib/openssl.cnf - master configuration file
542 ./demoCA - main CA directory
543 ./demoCA/cacert.pem - CA certificate
544 ./demoCA/private/cakey.pem - CA private key
545 ./demoCA/serial - CA serial number file
546 ./demoCA/serial.old - CA serial number backup file
547 ./demoCA/index.txt - CA text database file
548 ./demoCA/index.txt.old - CA text database backup file
549 ./demoCA/certs - certificate output file
550 ./demoCA/.rnd - CA random seed information
551
553 The text database index file is a critical part of the process and if
554 corrupted it can be difficult to fix. It is theoretically possible to
555 rebuild the index file from all the issued certificates and a current
556 CRL: however there is no option to do this.
557 V2 CRL features like delta CRLs are not currently supported.
559 Although several requests can be input and handled at once it is only
561 possible to include one SPKAC or self-signed certificate.
562
564 The use of an in-memory text database can cause problems when large
565 numbers of certificates are present because, as the name implies the
566 database has to be kept in memory.
567 The ca command really needs rewriting or the required functionality
569 exposed at either a command or interface level so a more friendly
570 utility (perl script or GUI) can handle things properly. The script
571 CA.pl helps a little but not very much.
572 Any fields in a request that are not present in a policy are silently
574 deleted. This does not happen if the -preserveDN option is used. To
575 enforce the absence of the EMAIL field within the DN, as suggested by
576 RFCs, regardless the contents of the request' subject the -noemailDN
577 option can be used. The behaviour should be more friendly and
578 configurable.
579 Canceling some commands by refusing to certify a certificate can create
581 an empty file.
582
584 The ca command is quirky and at times downright unfriendly.
585 The ca utility was originally meant as an example of how to do things
587 in a CA. It was not supposed to be used as a full blown CA itself:
588 nevertheless some people are using it for this purpose.
589 The ca command is effectively a single user command: no locking is done
591 on the various files and attempts to run more than one ca command on
592 the same database can have unpredictable results.
593 The copy_extensions option should be used with caution. If care is not
595 taken then it can be a security risk. For example if a certificate
596 request contains a basicConstraints extension with CA:TRUE and the
597 copy_extensions value is set to copyall and the user does not spot this
598 when the certificate is displayed then this will hand the requester a
599 valid CA certificate.
600 This situation can be avoided by setting copy_extensions to copy and
602 including basicConstraints with CA:FALSE in the configuration file.
603 Then if the request contains a basicConstraints extension it will be
604 ignored.
605 It is advisable to also include values for other extensions such as
607 keyUsage to prevent a request supplying its own values.
608 Additional restrictions can be placed on the CA certificate itself.
610 For example if the CA certificate has:
611 basicConstraints = CA:TRUE, pathlen:0
613 then even if a certificate is issued with CA:TRUE it will not be valid.
615
617 Since OpenSSL 1.1.1, the program follows RFC5280. Specifically,
618 certificate validity period (specified by any of -startdate, -enddate
619 and -days) will be encoded as UTCTime if the dates are earlier than
620 year 2049 (included), and as GeneralizedTime if the dates are in year
621 2050 or later.
622
624 req(1), spkac(1), x509(1), CA.pl(1), config(5), x509v3_config(5)
625
627 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
628 Licensed under the OpenSSL license (the "License"). You may not use
630 this file except in compliance with the License. You can obtain a copy
631 in the file LICENSE in the source distribution or at
632 <https://www.openssl.org/source/license.html>.
6331.1.1l 2021-09-15 CA(1)