1CA(1)                               OpenSSL                              CA(1)
2
3
4

NAME

6       openssl-ca, ca - sample minimal CA application
7

SYNOPSIS

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

DESCRIPTION

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
27       The options descriptions will be divided into each purpose.
28

OPTIONS

30       -help
31           Print out a usage message.
32
33       -verbose
34           This prints extra details about the operations being performed.
35
36       -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
41       -name section
42           Specifies the configuration file section to use (overrides
43           default_ca in the ca section).
44
45       -in filename
46           An input filename containing a single certificate request to be
47           signed by the CA.
48
49       -ss_cert filename
50           A single self-signed certificate to be signed by the CA.
51
52       -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
58       -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
62       -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
67       -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
72       -cert
73           The CA certificate file.
74
75       -keyfile filename
76           The private key to sign requests with.
77
78       -keyform PEM|DER
79           The format of the data in the private key file.  The default is
80           PEM.
81
82       -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
87       -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
92       -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
98           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
104       -passin arg
105           The key password source. For more information about the format of
106           arg see "Pass Phrase Options" in openssl(1).
107
108       -notext
109           Don't output the text form of a certificate to the output file.
110
111       -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
117       -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
123       -days arg
124           The number of days to certify the certificate for.
125
126       -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
132       -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
138       -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
144       -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
152       -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
161       -batch
162           This sets the batch mode. In this mode no questions will be asked
163           and all certificates will be certified automatically.
164
165       -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
174       -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
179       -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
185       -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
192       -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
198       -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
205       -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
209       -multivalue-rdn
210           This option causes the -subj argument to be interpreted with full
211           support for multivalued RDNs. Example:
212
213           /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
214
215           If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
216
217       -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
223       [-writerand file]
224           Writes random data to the specified file upon exit.  This can be
225           used with a subsequent -rand flag.
226

CRL OPTIONS

228       -gencrl
229           This option generates a CRL based on information in the index file.
230
231       -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
235       -crlhours num
236           The number of hours before the next CRL is due.
237
238       -revoke filename
239           A filename containing a certificate to revoke.
240
241       -valid filename
242           A filename containing a certificate to add a Valid certificate
243           entry.
244
245       -status serial
246           Displays the revocation status of the certificate with the
247           specified serial number and exits.
248
249       -updatedb
250           Updates the database index to purge expired certificates.
251
252       -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
259           In practice removeFromCRL is not particularly useful because it is
260           only used in delta CRLs which are not currently implemented.
261
262       -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
269       -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
274       -crl_CA_compromise time
275           This is the same as crl_compromise except the revocation reason is
276           set to CACompromise.
277
278       -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

CONFIGURATION FILE OPTIONS

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
301       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
307       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
313       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
319       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
323       certificate
324           The same as -cert. It gives the file containing the CA certificate.
325           Mandatory.
326
327       private_key
328           Same as the -keyfile option. The file containing the CA private
329           key. Mandatory.
330
331       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
335       default_days
336           The same as the -days option. The number of days to certify a
337           certificate for.
338
339       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
343       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
347       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
352       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
356       database
357           The text database file to use. Mandatory. This file must be present
358           though initially it will be empty.
359
360       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
369           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
373       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
378       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
383       x509_extensions
384           The same as -extensions.
385
386       crl_extensions
387           The same as -crlexts.
388
389       preserve
390           The same as -preserveDN
391
392       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
398       msie_hack
399           The same as -msie_hack
400
401       policy
402           The same as -policy. Mandatory. See the POLICY FORMAT section for
403           more information.
404
405       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
414           For convenience the values ca_default are accepted by both to
415           produce a reasonable output.
416
417           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
423       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
433           The main use of this option is to allow a certificate request to
434           supply values for certain extensions such as subjectAltName.
435

POLICY FORMAT

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

SPKAC FORMAT

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
451       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
456       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

EXAMPLES

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
466       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
472       Sign a certificate request:
473
474        openssl ca -in req.pem -out newcert.pem
475
476       Sign a certificate request, using CA extensions:
477
478        openssl ca -in req.pem -extensions v3_ca -out newcert.pem
479
480       Generate a CRL
481
482        openssl ca -gencrl -out crl.pem
483
484       Sign several requests:
485
486        openssl ca -infiles req1.pem req2.pem req3.pem
487
488       Certify a Netscape SPKAC:
489
490        openssl ca -spkac spkac.txt
491
492       A sample SPKAC file (the SPKAC line has been truncated for clarity):
493
494        SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
495        CN=Steve Test
496        emailAddress=steve@openssl.org
497        0.OU=OpenSSL Group
498        1.OU=Another Group
499
500       A sample configuration file with the relevant sections for ca:
501
502        [ ca ]
503        default_ca      = CA_default            # The default ca section
504
505        [ CA_default ]
506
507        dir            = ./demoCA              # top dir
508        database       = $dir/index.txt        # index file.
509        new_certs_dir  = $dir/newcerts         # new certs dir
510
511        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
517        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
521        policy         = policy_any            # default policy
522        email_in_dn    = no                    # Don't add the email into cert DN
523
524        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
528        [ policy_any ]
529        countryName            = supplied
530        stateOrProvinceName    = optional
531        organizationName       = optional
532        organizationalUnitName = optional
533        commonName             = supplied
534        emailAddress           = optional
535

FILES

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
541        /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

RESTRICTIONS

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
558       V2 CRL features like delta CRLs are not currently supported.
559
560       Although several requests can be input and handled at once it is only
561       possible to include one SPKAC or self-signed certificate.
562

BUGS

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
568       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
573       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
580       Canceling some commands by refusing to certify a certificate can create
581       an empty file.
582

WARNINGS

584       The ca command is quirky and at times downright unfriendly.
585
586       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
590       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
594       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
601       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
606       It is advisable to also include values for other extensions such as
607       keyUsage to prevent a request supplying its own values.
608
609       Additional restrictions can be placed on the CA certificate itself.
610       For example if the CA certificate has:
611
612        basicConstraints = CA:TRUE, pathlen:0
613
614       then even if a certificate is issued with CA:TRUE it will not be valid.
615

HISTORY

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

SEE ALSO

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
629       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>.
633
634
635
6361.1.1k                            2021-03-26                             CA(1)
Impressum