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] [-create_serial]
19 [-rand_serial] [-multivalue-rdn] [-rand file...] [-writerand file]
20
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 The options descriptions will be divided into each purpose.
27
29 -help
30 Print out a usage message.
31 -verbose
33 This prints extra details about the operations being performed.
34 -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 -name section
41 Specifies the configuration file section to use (overrides
42 default_ca in the ca section).
43 -in filename
45 An input filename containing a single certificate request to be
46 signed by the CA.
47 -ss_cert filename
49 A single self-signed certificate to be signed by the CA.
50 -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 -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 -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 -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 -cert
72 The CA certificate file.
73 -keyfile filename
75 The private key to sign requests with.
76 -keyform PEM|DER
78 The format of the data in the private key file. The default is
79 PEM.
80 -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 -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 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 -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 -notext
103 Don't output the text form of a certificate to the output file.
104 -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 -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 -days arg
118 The number of days to certify the certificate for.
119 -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 -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 -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 -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 -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 -batch
156 This sets the batch mode. In this mode no questions will be asked
157 and all certificates will be certified automatically.
158 -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 -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 -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 -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 -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 -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 -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 -multivalue-rdn
204 This option causes the -subj argument to be interpreted with full
205 support for multivalued RDNs. Example:
206 /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
208 If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
210 -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 [-writerand file]
218 Writes random data to the specified file upon exit. This can be
219 used with a subsequent -rand flag.
220
222 -gencrl
223 This option generates a CRL based on information in the index file.
224 -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 -crlhours num
230 The number of hours before the next CRL is due.
231 -revoke filename
233 A filename containing a certificate to revoke.
234 -valid filename
236 A filename containing a certificate to add a Valid certificate
237 entry.
238 -status serial
240 Displays the revocation status of the certificate with the
241 specified serial number and exits.
242 -updatedb
244 Updates the database index to purge expired certificates.
245 -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 In practice removeFromCRL is not particularly useful because it is
254 only used in delta CRLs which are not currently implemented.
255 -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 -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 -crl_CA_compromise time
269 This is the same as crl_compromise except the revocation reason is
270 set to CACompromise.
271 -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
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 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 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 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 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 certificate
318 The same as -cert. It gives the file containing the CA certificate.
319 Mandatory.
320 private_key
322 Same as the -keyfile option. The file containing the CA private
323 key. Mandatory.
324 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 default_days
330 The same as the -days option. The number of days to certify a
331 certificate for.
332 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 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 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 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 database
351 The text database file to use. Mandatory. This file must be present
352 though initially it will be empty.
353 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 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 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 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 x509_extensions
378 The same as -extensions.
379 crl_extensions
381 The same as -crlexts.
382 preserve
384 The same as -preserveDN
385 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 msie_hack
393 The same as -msie_hack
394 policy
396 The same as -policy. Mandatory. See the POLICY FORMAT section for
397 more information.
398 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 For convenience the values ca_default are accepted by both to
409 produce a reasonable output.
410 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 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 The main use of this option is to allow a certificate request to
428 supply values for certain extensions such as subjectAltName.
429
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
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 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 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
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 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 Sign a certificate request:
467 openssl ca -in req.pem -out newcert.pem
469 Sign a certificate request, using CA extensions:
471 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
473 Generate a CRL
475 openssl ca -gencrl -out crl.pem
477 Sign several requests:
479 openssl ca -infiles req1.pem req2.pem req3.pem
481 Certify a Netscape SPKAC:
483 openssl ca -spkac spkac.txt
485 A sample SPKAC file (the SPKAC line has been truncated for clarity):
487 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
489 CN=Steve Test
490 emailAddress=steve@openssl.org
491 0.OU=OpenSSL Group
492 1.OU=Another Group
493 A sample configuration file with the relevant sections for ca:
495 [ ca ]
497 default_ca = CA_default # The default ca section
498 [ CA_default ]
500 dir = ./demoCA # top dir
502 database = $dir/index.txt # index file.
503 new_certs_dir = $dir/newcerts # new certs dir
504 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 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 policy = policy_any # default policy
516 email_in_dn = no # Don't add the email into cert DN
517 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 [ policy_any ]
523 countryName = supplied
524 stateOrProvinceName = optional
525 organizationName = optional
526 organizationalUnitName = optional
527 commonName = supplied
528 emailAddress = optional
529
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 /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
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 V2 CRL features like delta CRLs are not currently supported.
553 Although several requests can be input and handled at once it is only
555 possible to include one SPKAC or self-signed certificate.
556
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 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 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 Canceling some commands by refusing to certify a certificate can create
575 an empty file.
576
578 The ca command is quirky and at times downright unfriendly.
579 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 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 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 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 It is advisable to also include values for other extensions such as
601 keyUsage to prevent a request supplying its own values.
602 Additional restrictions can be placed on the CA certificate itself.
604 For example if the CA certificate has:
605 basicConstraints = CA:TRUE, pathlen:0
607 then even if a certificate is issued with CA:TRUE it will not be valid.
609
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
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 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>.
6271.1.1c 2019-05-28 CA(1)