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] [-create_serial]
19       [-rand_serial] [-multivalue-rdn] [-rand file...]  [-writerand file]
20

DESCRIPTION

22       The ca command is a minimal CA application. It can be used to sign
23       certificate requests in a variety of forms and generate CRLs it also
24       maintains a text database of issued certificates and their status.
25
26       The options descriptions will be divided into each purpose.
27

OPTIONS

29       -help
30           Print out a usage message.
31
32       -verbose
33           This prints extra details about the operations being performed.
34
35       -config filename
36           Specifies the configuration file to use.  Optional; for a
37           description of the default value, see "COMMAND SUMMARY" in
38           openssl(1).
39
40       -name section
41           Specifies the configuration file section to use (overrides
42           default_ca in the ca section).
43
44       -in filename
45           An input filename containing a single certificate request to be
46           signed by the CA.
47
48       -ss_cert filename
49           A single self-signed certificate to be signed by the CA.
50
51       -spkac filename
52           A file containing a single Netscape signed public key and challenge
53           and additional field values to be signed by the CA. See the SPKAC
54           FORMAT section for information on the required input and output
55           format.
56
57       -infiles
58           If present this should be the last option, all subsequent arguments
59           are taken as the names of files containing certificate requests.
60
61       -out filename
62           The output file to output certificates to. The default is standard
63           output. The certificate details will also be printed out to this
64           file in PEM format (except that -spkac outputs DER format).
65
66       -outdir directory
67           The directory to output certificates to. The certificate will be
68           written to a filename consisting of the serial number in hex with
69           ".pem" appended.
70
71       -cert
72           The CA certificate file.
73
74       -keyfile filename
75           The private key to sign requests with.
76
77       -keyform PEM|DER
78           The format of the data in the private key file.  The default is
79           PEM.
80
81       -key password
82           The password used to encrypt the private key. Since on some systems
83           the command line arguments are visible (e.g. Unix with the 'ps'
84           utility) this option should be used with caution.
85
86       -selfsign
87           Indicates the issued certificates are to be signed with the key the
88           certificate requests were signed with (given with -keyfile).
89           Certificate requests signed with a different key are ignored.  If
90           -spkac, -ss_cert or -gencrl are given, -selfsign is ignored.
91
92           A consequence of using -selfsign is that the self-signed
93           certificate appears among the entries in the certificate database
94           (see the configuration option database), and uses the same serial
95           number counter as all other certificates sign with the self-signed
96           certificate.
97
98       -passin arg
99           The key password source. For more information about the format of
100           arg see the PASS PHRASE ARGUMENTS section in openssl(1).
101
102       -notext
103           Don't output the text form of a certificate to the output file.
104
105       -startdate date
106           This allows the start date to be explicitly set. The format of the
107           date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
108           YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
109           both formats, seconds SS and timezone Z must be present.
110
111       -enddate date
112           This allows the expiry 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       -days arg
118           The number of days to certify the certificate for.
119
120       -md alg
121           The message digest to use.  Any digest supported by the OpenSSL
122           dgst command can be used. For signing algorithms that do not
123           support a digest (i.e. Ed25519 and Ed448) any message digest that
124           is set is ignored. This option also applies to CRLs.
125
126       -policy arg
127           This option defines the CA "policy" to use. This is a section in
128           the configuration file which decides which fields should be
129           mandatory or match the CA certificate. Check out the POLICY FORMAT
130           section for more information.
131
132       -msie_hack
133           This is a deprecated option to make ca work with very old versions
134           of the IE certificate enrollment control "certenr3". It used
135           UniversalStrings for almost everything. Since the old control has
136           various security bugs its use is strongly discouraged.
137
138       -preserveDN
139           Normally the DN order of a certificate is the same as the order of
140           the fields in the relevant policy section. When this option is set
141           the order is the same as the request. This is largely for
142           compatibility with the older IE enrollment control which would only
143           accept certificates if their DNs match the order of the request.
144           This is not needed for Xenroll.
145
146       -noemailDN
147           The DN of a certificate can contain the EMAIL field if present in
148           the request DN, however it is good policy just having the e-mail
149           set into the altName extension of the certificate. When this option
150           is set the EMAIL field is removed from the certificate' subject and
151           set only in the, eventually present, extensions. The email_in_dn
152           keyword can be used in the configuration file to enable this
153           behaviour.
154
155       -batch
156           This sets the batch mode. In this mode no questions will be asked
157           and all certificates will be certified automatically.
158
159       -extensions section
160           The section of the configuration file containing certificate
161           extensions to be added when a certificate is issued (defaults to
162           x509_extensions unless the -extfile option is used). If no
163           extension section is present then, a V1 certificate is created. If
164           the extension section is present (even if it is empty), then a V3
165           certificate is created. See the x509v3_config(5) manual page for
166           details of the extension section format.
167
168       -extfile file
169           An additional configuration file to read certificate extensions
170           from (using the default section unless the -extensions option is
171           also used).
172
173       -engine id
174           Specifying an engine (by its unique id string) will cause ca to
175           attempt to obtain a functional reference to the specified engine,
176           thus initialising it if needed. The engine will then be set as the
177           default for all available algorithms.
178
179       -subj arg
180           Supersedes subject name given in the request.  The arg must be
181           formatted as /type0=value0/type1=value1/type2=....  Keyword
182           characters may be escaped by \ (backslash), and whitespace is
183           retained.  Empty values are permitted, but the corresponding type
184           will not be included in the resulting certificate.
185
186       -utf8
187           This option causes field values to be interpreted as UTF8 strings,
188           by default they are interpreted as ASCII. This means that the field
189           values, whether prompted from a terminal or obtained from a
190           configuration file, must be valid UTF8 strings.
191
192       -create_serial
193           If reading serial from the text file as specified in the
194           configuration fails, specifying this option creates a new random
195           serial to be used as next serial number.  To get random serial
196           numbers, use the -rand_serial flag instead; this should only be
197           used for simple error-recovery.
198
199       -rand_serial
200           Generate a large random number to use as the serial number.  This
201           overrides any option or configuration to use a serial number file.
202
203       -multivalue-rdn
204           This option causes the -subj argument to be interpreted with full
205           support for multivalued RDNs. Example:
206
207           /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
208
209           If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
210
211       -rand file...
212           A file or files containing random data used to seed the random
213           number generator.  Multiple files can be specified separated by an
214           OS-dependent character.  The separator is ; for MS-Windows, , for
215           OpenVMS, and : for all others.
216
217       [-writerand file]
218           Writes random data to the specified file upon exit.  This can be
219           used with a subsequent -rand flag.
220

CRL OPTIONS

222       -gencrl
223           This option generates a CRL based on information in the index file.
224
225       -crldays num
226           The number of days before the next CRL is due. That is the days
227           from now to place in the CRL nextUpdate field.
228
229       -crlhours num
230           The number of hours before the next CRL is due.
231
232       -revoke filename
233           A filename containing a certificate to revoke.
234
235       -valid filename
236           A filename containing a certificate to add a Valid certificate
237           entry.
238
239       -status serial
240           Displays the revocation status of the certificate with the
241           specified serial number and exits.
242
243       -updatedb
244           Updates the database index to purge expired certificates.
245
246       -crl_reason reason
247           Revocation reason, where reason is one of: unspecified,
248           keyCompromise, CACompromise, affiliationChanged, superseded,
249           cessationOfOperation, certificateHold or removeFromCRL. The
250           matching of reason is case insensitive. Setting any revocation
251           reason will make the CRL v2.
252
253           In practice removeFromCRL is not particularly useful because it is
254           only used in delta CRLs which are not currently implemented.
255
256       -crl_hold instruction
257           This sets the CRL revocation reason code to certificateHold and the
258           hold instruction to instruction which must be an OID. Although any
259           OID can be used only holdInstructionNone (the use of which is
260           discouraged by RFC2459) holdInstructionCallIssuer or
261           holdInstructionReject will normally be used.
262
263       -crl_compromise time
264           This sets the revocation reason to keyCompromise and the compromise
265           time to time. time should be in GeneralizedTime format that is
266           YYYYMMDDHHMMSSZ.
267
268       -crl_CA_compromise time
269           This is the same as crl_compromise except the revocation reason is
270           set to CACompromise.
271
272       -crlexts section
273           The section of the configuration file containing CRL extensions to
274           include. If no CRL extension section is present then a V1 CRL is
275           created, if the CRL extension section is present (even if it is
276           empty) then a V2 CRL is created. The CRL extensions specified are
277           CRL extensions and not CRL entry extensions.  It should be noted
278           that some software (for example Netscape) can't handle V2 CRLs. See
279           x509v3_config(5) manual page for details of the extension section
280           format.
281

CONFIGURATION FILE OPTIONS

283       The section of the configuration file containing options for ca is
284       found as follows: If the -name command line option is used, then it
285       names the section to be used. Otherwise the section to be used must be
286       named in the default_ca option of the ca section of the configuration
287       file (or in the default section of the configuration file). Besides
288       default_ca, the following options are read directly from the ca
289       section:
290        RANDFILE
291        preserve
292        msie_hack With the exception of RANDFILE, this is probably a bug and
293       may change in future releases.
294
295       Many of the configuration file options are identical to command line
296       options. Where the option is present in the configuration file and the
297       command line the command line value is used. Where an option is
298       described as mandatory then it must be present in the configuration
299       file or the command line equivalent (if any) used.
300
301       oid_file
302           This specifies a file containing additional OBJECT IDENTIFIERS.
303           Each line of the file should consist of the numerical form of the
304           object identifier followed by white space then the short name
305           followed by white space and finally the long name.
306
307       oid_section
308           This specifies a section in the configuration file containing extra
309           object identifiers. Each line should consist of the short name of
310           the object identifier followed by = and the numerical form. The
311           short and long names are the same when this option is used.
312
313       new_certs_dir
314           The same as the -outdir command line option. It specifies the
315           directory where new certificates will be placed. Mandatory.
316
317       certificate
318           The same as -cert. It gives the file containing the CA certificate.
319           Mandatory.
320
321       private_key
322           Same as the -keyfile option. The file containing the CA private
323           key. Mandatory.
324
325       RANDFILE
326           At startup the specified file is loaded into the random number
327           generator, and at exit 256 bytes will be written to it.
328
329       default_days
330           The same as the -days option. The number of days to certify a
331           certificate for.
332
333       default_startdate
334           The same as the -startdate option. The start date to certify a
335           certificate for. If not set the current time is used.
336
337       default_enddate
338           The same as the -enddate option. Either this option or default_days
339           (or the command line equivalents) must be present.
340
341       default_crl_hours default_crl_days
342           The same as the -crlhours and the -crldays options. These will only
343           be used if neither command line option is present. At least one of
344           these must be present to generate a CRL.
345
346       default_md
347           The same as the -md option. Mandatory except where the signing
348           algorithm does not require a digest (i.e. Ed25519 and Ed448).
349
350       database
351           The text database file to use. Mandatory. This file must be present
352           though initially it will be empty.
353
354       unique_subject
355           If the value yes is given, the valid certificate entries in the
356           database must have unique subjects.  if the value no is given,
357           several valid certificate entries may have the exact same subject.
358           The default value is yes, to be compatible with older (pre 0.9.8)
359           versions of OpenSSL.  However, to make CA certificate roll-over
360           easier, it's recommended to use the value no, especially if
361           combined with the -selfsign command line option.
362
363           Note that it is valid in some circumstances for certificates to be
364           created without any subject. In the case where there are multiple
365           certificates without subjects this does not count as a duplicate.
366
367       serial
368           A text file containing the next serial number to use in hex.
369           Mandatory.  This file must be present and contain a valid serial
370           number.
371
372       crlnumber
373           A text file containing the next CRL number to use in hex. The crl
374           number will be inserted in the CRLs only if this file exists. If
375           this file is present, it must contain a valid CRL number.
376
377       x509_extensions
378           The same as -extensions.
379
380       crl_extensions
381           The same as -crlexts.
382
383       preserve
384           The same as -preserveDN
385
386       email_in_dn
387           The same as -noemailDN. If you want the EMAIL field to be removed
388           from the DN of the certificate simply set this to 'no'. If not
389           present the default is to allow for the EMAIL filed in the
390           certificate's DN.
391
392       msie_hack
393           The same as -msie_hack
394
395       policy
396           The same as -policy. Mandatory. See the POLICY FORMAT section for
397           more information.
398
399       name_opt, cert_opt
400           These options allow the format used to display the certificate
401           details when asking the user to confirm signing. All the options
402           supported by the x509 utilities -nameopt and -certopt switches can
403           be used here, except the no_signame and no_sigdump are permanently
404           set and cannot be disabled (this is because the certificate
405           signature cannot be displayed because the certificate has not been
406           signed at this point).
407
408           For convenience the values ca_default are accepted by both to
409           produce a reasonable output.
410
411           If neither option is present the format used in earlier versions of
412           OpenSSL is used. Use of the old format is strongly discouraged
413           because it only displays fields mentioned in the policy section,
414           mishandles multicharacter string types and does not display
415           extensions.
416
417       copy_extensions
418           Determines how extensions in certificate requests should be
419           handled.  If set to none or this option is not present then
420           extensions are ignored and not copied to the certificate. If set to
421           copy then any extensions present in the request that are not
422           already present are copied to the certificate. If set to copyall
423           then all extensions in the request are copied to the certificate:
424           if the extension is already present in the certificate it is
425           deleted first. See the WARNINGS section before using this option.
426
427           The main use of this option is to allow a certificate request to
428           supply values for certain extensions such as subjectAltName.
429

POLICY FORMAT

431       The policy section consists of a set of variables corresponding to
432       certificate DN fields. If the value is "match" then the field value
433       must match the same field in the CA certificate. If the value is
434       "supplied" then it must be present. If the value is "optional" then it
435       may be present. Any fields not mentioned in the policy section are
436       silently deleted, unless the -preserveDN option is set but this can be
437       regarded more of a quirk than intended behaviour.
438

SPKAC FORMAT

440       The input to the -spkac command line option is a Netscape signed public
441       key and challenge. This will usually come from the KEYGEN tag in an
442       HTML form to create a new private key.  It is however possible to
443       create SPKACs using the spkac utility.
444
445       The file should contain the variable SPKAC set to the value of the
446       SPKAC and also the required DN components as name value pairs.  If you
447       need to include the same component twice then it can be preceded by a
448       number and a '.'.
449
450       When processing SPKAC format, the output is DER if the -out flag is
451       used, but PEM format if sending to stdout or the -outdir flag is used.
452

EXAMPLES

454       Note: these examples assume that the ca directory structure is already
455       set up and the relevant files already exist. This usually involves
456       creating a CA certificate and private key with req, a serial number
457       file and an empty index file and placing them in the relevant
458       directories.
459
460       To use the sample configuration file below the directories demoCA,
461       demoCA/private and demoCA/newcerts would be created. The CA certificate
462       would be copied to demoCA/cacert.pem and its private key to
463       demoCA/private/cakey.pem. A file demoCA/serial would be created
464       containing for example "01" and the empty index file demoCA/index.txt.
465
466       Sign a certificate request:
467
468        openssl ca -in req.pem -out newcert.pem
469
470       Sign a certificate request, using CA extensions:
471
472        openssl ca -in req.pem -extensions v3_ca -out newcert.pem
473
474       Generate a CRL
475
476        openssl ca -gencrl -out crl.pem
477
478       Sign several requests:
479
480        openssl ca -infiles req1.pem req2.pem req3.pem
481
482       Certify a Netscape SPKAC:
483
484        openssl ca -spkac spkac.txt
485
486       A sample SPKAC file (the SPKAC line has been truncated for clarity):
487
488        SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
489        CN=Steve Test
490        emailAddress=steve@openssl.org
491        0.OU=OpenSSL Group
492        1.OU=Another Group
493
494       A sample configuration file with the relevant sections for ca:
495
496        [ ca ]
497        default_ca      = CA_default            # The default ca section
498
499        [ CA_default ]
500
501        dir            = ./demoCA              # top dir
502        database       = $dir/index.txt        # index file.
503        new_certs_dir  = $dir/newcerts         # new certs dir
504
505        certificate    = $dir/cacert.pem       # The CA cert
506        serial         = $dir/serial           # serial no file
507        #rand_serial    = yes                  # for random serial#'s
508        private_key    = $dir/private/cakey.pem# CA private key
509        RANDFILE       = $dir/private/.rand    # random number file
510
511        default_days   = 365                   # how long to certify for
512        default_crl_days= 30                   # how long before next CRL
513        default_md     = md5                   # md to use
514
515        policy         = policy_any            # default policy
516        email_in_dn    = no                    # Don't add the email into cert DN
517
518        name_opt       = ca_default            # Subject name display option
519        cert_opt       = ca_default            # Certificate display option
520        copy_extensions = none                 # Don't copy extensions from request
521
522        [ policy_any ]
523        countryName            = supplied
524        stateOrProvinceName    = optional
525        organizationName       = optional
526        organizationalUnitName = optional
527        commonName             = supplied
528        emailAddress           = optional
529

FILES

531       Note: the location of all files can change either by compile time
532       options, configuration file entries, environment variables or command
533       line options.  The values below reflect the default values.
534
535        /usr/local/ssl/lib/openssl.cnf - master configuration file
536        ./demoCA                       - main CA directory
537        ./demoCA/cacert.pem            - CA certificate
538        ./demoCA/private/cakey.pem     - CA private key
539        ./demoCA/serial                - CA serial number file
540        ./demoCA/serial.old            - CA serial number backup file
541        ./demoCA/index.txt             - CA text database file
542        ./demoCA/index.txt.old         - CA text database backup file
543        ./demoCA/certs                 - certificate output file
544        ./demoCA/.rnd                  - CA random seed information
545

RESTRICTIONS

547       The text database index file is a critical part of the process and if
548       corrupted it can be difficult to fix. It is theoretically possible to
549       rebuild the index file from all the issued certificates and a current
550       CRL: however there is no option to do this.
551
552       V2 CRL features like delta CRLs are not currently supported.
553
554       Although several requests can be input and handled at once it is only
555       possible to include one SPKAC or self-signed certificate.
556

BUGS

558       The use of an in-memory text database can cause problems when large
559       numbers of certificates are present because, as the name implies the
560       database has to be kept in memory.
561
562       The ca command really needs rewriting or the required functionality
563       exposed at either a command or interface level so a more friendly
564       utility (perl script or GUI) can handle things properly. The script
565       CA.pl helps a little but not very much.
566
567       Any fields in a request that are not present in a policy are silently
568       deleted. This does not happen if the -preserveDN option is used. To
569       enforce the absence of the EMAIL field within the DN, as suggested by
570       RFCs, regardless the contents of the request' subject the -noemailDN
571       option can be used. The behaviour should be more friendly and
572       configurable.
573
574       Canceling some commands by refusing to certify a certificate can create
575       an empty file.
576

WARNINGS

578       The ca command is quirky and at times downright unfriendly.
579
580       The ca utility was originally meant as an example of how to do things
581       in a CA. It was not supposed to be used as a full blown CA itself:
582       nevertheless some people are using it for this purpose.
583
584       The ca command is effectively a single user command: no locking is done
585       on the various files and attempts to run more than one ca command on
586       the same database can have unpredictable results.
587
588       The copy_extensions option should be used with caution. If care is not
589       taken then it can be a security risk. For example if a certificate
590       request contains a basicConstraints extension with CA:TRUE and the
591       copy_extensions value is set to copyall and the user does not spot this
592       when the certificate is displayed then this will hand the requester a
593       valid CA certificate.
594
595       This situation can be avoided by setting copy_extensions to copy and
596       including basicConstraints with CA:FALSE in the configuration file.
597       Then if the request contains a basicConstraints extension it will be
598       ignored.
599
600       It is advisable to also include values for other extensions such as
601       keyUsage to prevent a request supplying its own values.
602
603       Additional restrictions can be placed on the CA certificate itself.
604       For example if the CA certificate has:
605
606        basicConstraints = CA:TRUE, pathlen:0
607
608       then even if a certificate is issued with CA:TRUE it will not be valid.
609

HISTORY

611       Since OpenSSL 1.1.1, the program follows RFC5280. Specifically,
612       certificate validity period (specified by any of -startdate, -enddate
613       and -days) will be encoded as UTCTime if the dates are earlier than
614       year 2049 (included), and as GeneralizedTime if the dates are in year
615       2050 or later.
616

SEE ALSO

618       req(1), spkac(1), x509(1), CA.pl(1), config(5), x509v3_config(5)
619
621       Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
622
623       Licensed under the OpenSSL license (the "License").  You may not use
624       this file except in compliance with the License.  You can obtain a copy
625       in the file LICENSE in the source distribution or at
626       <https://www.openssl.org/source/license.html>.
627
628
629
6301.1.1d                            2019-10-03                             CA(1)
Impressum