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:w 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=..., characters may
182 be escaped by \ (backslash), no spaces are skipped.
183 -utf8
185 This option causes field values to be interpreted as UTF8 strings,
186 by default they are interpreted as ASCII. This means that the field
187 values, whether prompted from a terminal or obtained from a
188 configuration file, must be valid UTF8 strings.
189 -create_serial
191 If reading serial from the text file as specified in the
192 configuration fails, specifying this option creates a new random
193 serial to be used as next serial number. To get random serial
194 numbers, use the -rand_serial flag instead; this should only be
195 used for simple error-recovery.
196 -rand_serial
198 Generate a large random number to use as the serial number. This
199 overrides any option or configuration to use a serial number file.
200 -multivalue-rdn
202 This option causes the -subj argument to be interpreted with full
203 support for multivalued RDNs. Example:
204 /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
206 If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
208 -rand file...
210 A file or files containing random data used to seed the random
211 number generator. Multiple files can be specified separated by an
212 OS-dependent character. The separator is ; for MS-Windows, , for
213 OpenVMS, and : for all others.
214 [-writerand file]
216 Writes random data to the specified file upon exit. This can be
217 used with a subsequent -rand flag.
218
220 -gencrl
221 This option generates a CRL based on information in the index file.
222 -crldays num
224 The number of days before the next CRL is due. That is the days
225 from now to place in the CRL nextUpdate field.
226 -crlhours num
228 The number of hours before the next CRL is due.
229 -revoke filename
231 A filename containing a certificate to revoke.
232 -valid filename
234 A filename containing a certificate to add a Valid certificate
235 entry.
236 -status serial
238 Displays the revocation status of the certificate with the
239 specified serial number and exits.
240 -updatedb
242 Updates the database index to purge expired certificates.
243 -crl_reason reason
245 Revocation reason, where reason is one of: unspecified,
246 keyCompromise, CACompromise, affiliationChanged, superseded,
247 cessationOfOperation, certificateHold or removeFromCRL. The
248 matching of reason is case insensitive. Setting any revocation
249 reason will make the CRL v2.
250 In practice removeFromCRL is not particularly useful because it is
252 only used in delta CRLs which are not currently implemented.
253 -crl_hold instruction
255 This sets the CRL revocation reason code to certificateHold and the
256 hold instruction to instruction which must be an OID. Although any
257 OID can be used only holdInstructionNone (the use of which is
258 discouraged by RFC2459) holdInstructionCallIssuer or
259 holdInstructionReject will normally be used.
260 -crl_compromise time
262 This sets the revocation reason to keyCompromise and the compromise
263 time to time. time should be in GeneralizedTime format that is
264 YYYYMMDDHHMMSSZ.
265 -crl_CA_compromise time
267 This is the same as crl_compromise except the revocation reason is
268 set to CACompromise.
269 -crlexts section
271 The section of the configuration file containing CRL extensions to
272 include. If no CRL extension section is present then a V1 CRL is
273 created, if the CRL extension section is present (even if it is
274 empty) then a V2 CRL is created. The CRL extensions specified are
275 CRL extensions and not CRL entry extensions. It should be noted
276 that some software (for example Netscape) can't handle V2 CRLs. See
277 x509v3_config(5) manual page for details of the extension section
278 format.
279
281 The section of the configuration file containing options for ca is
282 found as follows: If the -name command line option is used, then it
283 names the section to be used. Otherwise the section to be used must be
284 named in the default_ca option of the ca section of the configuration
285 file (or in the default section of the configuration file). Besides
286 default_ca, the following options are read directly from the ca
287 section:
288 RANDFILE
289 preserve
290 msie_hack With the exception of RANDFILE, this is probably a bug and
291 may change in future releases.
292 Many of the configuration file options are identical to command line
294 options. Where the option is present in the configuration file and the
295 command line the command line value is used. Where an option is
296 described as mandatory then it must be present in the configuration
297 file or the command line equivalent (if any) used.
298 oid_file
300 This specifies a file containing additional OBJECT IDENTIFIERS.
301 Each line of the file should consist of the numerical form of the
302 object identifier followed by white space then the short name
303 followed by white space and finally the long name.
304 oid_section
306 This specifies a section in the configuration file containing extra
307 object identifiers. Each line should consist of the short name of
308 the object identifier followed by = and the numerical form. The
309 short and long names are the same when this option is used.
310 new_certs_dir
312 The same as the -outdir command line option. It specifies the
313 directory where new certificates will be placed. Mandatory.
314 certificate
316 The same as -cert. It gives the file containing the CA certificate.
317 Mandatory.
318 private_key
320 Same as the -keyfile option. The file containing the CA private
321 key. Mandatory.
322 RANDFILE
324 At startup the specified file is loaded into the random number
325 generator, and at exit 256 bytes will be written to it.
326 default_days
328 The same as the -days option. The number of days to certify a
329 certificate for.
330 default_startdate
332 The same as the -startdate option. The start date to certify a
333 certificate for. If not set the current time is used.
334 default_enddate
336 The same as the -enddate option. Either this option or default_days
337 (or the command line equivalents) must be present.
338 default_crl_hours default_crl_days
340 The same as the -crlhours and the -crldays options. These will only
341 be used if neither command line option is present. At least one of
342 these must be present to generate a CRL.
343 default_md
345 The same as the -md option. Mandatory except where the signing
346 algorithm does not require a digest (i.e. Ed25519 and Ed448).
347 database
349 The text database file to use. Mandatory. This file must be present
350 though initially it will be empty.
351 unique_subject
353 If the value yes is given, the valid certificate entries in the
354 database must have unique subjects. if the value no is given,
355 several valid certificate entries may have the exact same subject.
356 The default value is yes, to be compatible with older (pre 0.9.8)
357 versions of OpenSSL. However, to make CA certificate roll-over
358 easier, it's recommended to use the value no, especially if
359 combined with the -selfsign command line option.
360 Note that it is valid in some circumstances for certificates to be
362 created without any subject. In the case where there are multiple
363 certificates without subjects this does not count as a duplicate.
364 serial
366 A text file containing the next serial number to use in hex.
367 Mandatory. This file must be present and contain a valid serial
368 number.
369 crlnumber
371 A text file containing the next CRL number to use in hex. The crl
372 number will be inserted in the CRLs only if this file exists. If
373 this file is present, it must contain a valid CRL number.
374 x509_extensions
376 The same as -extensions.
377 crl_extensions
379 The same as -crlexts.
380 preserve
382 The same as -preserveDN
383 email_in_dn
385 The same as -noemailDN. If you want the EMAIL field to be removed
386 from the DN of the certificate simply set this to 'no'. If not
387 present the default is to allow for the EMAIL filed in the
388 certificate's DN.
389 msie_hack
391 The same as -msie_hack
392 policy
394 The same as -policy. Mandatory. See the POLICY FORMAT section for
395 more information.
396 name_opt, cert_opt
398 These options allow the format used to display the certificate
399 details when asking the user to confirm signing. All the options
400 supported by the x509 utilities -nameopt and -certopt switches can
401 be used here, except the no_signame and no_sigdump are permanently
402 set and cannot be disabled (this is because the certificate
403 signature cannot be displayed because the certificate has not been
404 signed at this point).
405 For convenience the values ca_default are accepted by both to
407 produce a reasonable output.
408 If neither option is present the format used in earlier versions of
410 OpenSSL is used. Use of the old format is strongly discouraged
411 because it only displays fields mentioned in the policy section,
412 mishandles multicharacter string types and does not display
413 extensions.
414 copy_extensions
416 Determines how extensions in certificate requests should be
417 handled. If set to none or this option is not present then
418 extensions are ignored and not copied to the certificate. If set to
419 copy then any extensions present in the request that are not
420 already present are copied to the certificate. If set to copyall
421 then all extensions in the request are copied to the certificate:
422 if the extension is already present in the certificate it is
423 deleted first. See the WARNINGS section before using this option.
424 The main use of this option is to allow a certificate request to
426 supply values for certain extensions such as subjectAltName.
427
429 The policy section consists of a set of variables corresponding to
430 certificate DN fields. If the value is "match" then the field value
431 must match the same field in the CA certificate. If the value is
432 "supplied" then it must be present. If the value is "optional" then it
433 may be present. Any fields not mentioned in the policy section are
434 silently deleted, unless the -preserveDN option is set but this can be
435 regarded more of a quirk than intended behaviour.
436
438 The input to the -spkac command line option is a Netscape signed public
439 key and challenge. This will usually come from the KEYGEN tag in an
440 HTML form to create a new private key. It is however possible to
441 create SPKACs using the spkac utility.
442 The file should contain the variable SPKAC set to the value of the
444 SPKAC and also the required DN components as name value pairs. If you
445 need to include the same component twice then it can be preceded by a
446 number and a '.'.
447 When processing SPKAC format, the output is DER if the -out flag is
449 used, but PEM format if sending to stdout or the -outdir flag is used.
450
452 Note: these examples assume that the ca directory structure is already
453 set up and the relevant files already exist. This usually involves
454 creating a CA certificate and private key with req, a serial number
455 file and an empty index file and placing them in the relevant
456 directories.
457 To use the sample configuration file below the directories demoCA,
459 demoCA/private and demoCA/newcerts would be created. The CA certificate
460 would be copied to demoCA/cacert.pem and its private key to
461 demoCA/private/cakey.pem. A file demoCA/serial would be created
462 containing for example "01" and the empty index file demoCA/index.txt.
463 Sign a certificate request:
465 openssl ca -in req.pem -out newcert.pem
467 Sign a certificate request, using CA extensions:
469 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
471 Generate a CRL
473 openssl ca -gencrl -out crl.pem
475 Sign several requests:
477 openssl ca -infiles req1.pem req2.pem req3.pem
479 Certify a Netscape SPKAC:
481 openssl ca -spkac spkac.txt
483 A sample SPKAC file (the SPKAC line has been truncated for clarity):
485 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
487 CN=Steve Test
488 emailAddress=steve@openssl.org
489 0.OU=OpenSSL Group
490 1.OU=Another Group
491 A sample configuration file with the relevant sections for ca:
493 [ ca ]
495 default_ca = CA_default # The default ca section
496 [ CA_default ]
498 dir = ./demoCA # top dir
500 database = $dir/index.txt # index file.
501 new_certs_dir = $dir/newcerts # new certs dir
502 certificate = $dir/cacert.pem # The CA cert
504 serial = $dir/serial # serial no file
505 #rand_serial = yes # for random serial#'s
506 private_key = $dir/private/cakey.pem# CA private key
507 RANDFILE = $dir/private/.rand # random number file
508 default_days = 365 # how long to certify for
510 default_crl_days= 30 # how long before next CRL
511 default_md = md5 # md to use
512 policy = policy_any # default policy
514 email_in_dn = no # Don't add the email into cert DN
515 name_opt = ca_default # Subject name display option
517 cert_opt = ca_default # Certificate display option
518 copy_extensions = none # Don't copy extensions from request
519 [ policy_any ]
521 countryName = supplied
522 stateOrProvinceName = optional
523 organizationName = optional
524 organizationalUnitName = optional
525 commonName = supplied
526 emailAddress = optional
527
529 Note: the location of all files can change either by compile time
530 options, configuration file entries, environment variables or command
531 line options. The values below reflect the default values.
532 /usr/local/ssl/lib/openssl.cnf - master configuration file
534 ./demoCA - main CA directory
535 ./demoCA/cacert.pem - CA certificate
536 ./demoCA/private/cakey.pem - CA private key
537 ./demoCA/serial - CA serial number file
538 ./demoCA/serial.old - CA serial number backup file
539 ./demoCA/index.txt - CA text database file
540 ./demoCA/index.txt.old - CA text database backup file
541 ./demoCA/certs - certificate output file
542 ./demoCA/.rnd - CA random seed information
543
545 The text database index file is a critical part of the process and if
546 corrupted it can be difficult to fix. It is theoretically possible to
547 rebuild the index file from all the issued certificates and a current
548 CRL: however there is no option to do this.
549 V2 CRL features like delta CRLs are not currently supported.
551 Although several requests can be input and handled at once it is only
553 possible to include one SPKAC or self-signed certificate.
554
556 The use of an in-memory text database can cause problems when large
557 numbers of certificates are present because, as the name implies the
558 database has to be kept in memory.
559 The ca command really needs rewriting or the required functionality
561 exposed at either a command or interface level so a more friendly
562 utility (perl script or GUI) can handle things properly. The script
563 CA.pl helps a little but not very much.
564 Any fields in a request that are not present in a policy are silently
566 deleted. This does not happen if the -preserveDN option is used. To
567 enforce the absence of the EMAIL field within the DN, as suggested by
568 RFCs, regardless the contents of the request' subject the -noemailDN
569 option can be used. The behaviour should be more friendly and
570 configurable.
571 Canceling some commands by refusing to certify a certificate can create
573 an empty file.
574
576 The ca command is quirky and at times downright unfriendly.
577 The ca utility was originally meant as an example of how to do things
579 in a CA. It was not supposed to be used as a full blown CA itself:
580 nevertheless some people are using it for this purpose.
581 The ca command is effectively a single user command: no locking is done
583 on the various files and attempts to run more than one ca command on
584 the same database can have unpredictable results.
585 The copy_extensions option should be used with caution. If care is not
587 taken then it can be a security risk. For example if a certificate
588 request contains a basicConstraints extension with CA:TRUE and the
589 copy_extensions value is set to copyall and the user does not spot this
590 when the certificate is displayed then this will hand the requester a
591 valid CA certificate.
592 This situation can be avoided by setting copy_extensions to copy and
594 including basicConstraints with CA:FALSE in the configuration file.
595 Then if the request contains a basicConstraints extension it will be
596 ignored.
597 It is advisable to also include values for other extensions such as
599 keyUsage to prevent a request supplying its own values.
600 Additional restrictions can be placed on the CA certificate itself.
602 For example if the CA certificate has:
603 basicConstraints = CA:TRUE, pathlen:0
605 then even if a certificate is issued with CA:TRUE it will not be valid.
607
609 Since OpenSSL 1.1.1, the program follows RFC5280. Specifically,
610 certificate validity period (specified by any of -startdate, -enddate
611 and -days) will be encoded as UTCTime if the dates are earlier than
612 year 2049 (included), and as GeneralizedTime if the dates are in year
613 2050 or later.
614
616 req(1), spkac(1), x509(1), CA.pl(1), config(5), x509v3_config(5)
617
619 Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
620 Licensed under the OpenSSL license (the "License"). You may not use
622 this file except in compliance with the License. You can obtain a copy
623 in the file LICENSE in the source distribution or at
624 <https://www.openssl.org/source/license.html>.
6251.1.1 2018-09-11 CA(1)