1CA(1) OpenSSL CA(1)
2
6 ca - sample minimal CA application
7
9 openssl ca [-verbose] [-config filename] [-name section] [-gencrl]
10 [-revoke file] [-status serial] [-updatedb] [-crl_reason reason]
11 [-crl_hold instruction] [-crl_compromise time] [-crl_CA_compromise
12 time] [-crldays days] [-crlhours hours] [-crlexts section] [-startdate
13 date] [-enddate date] [-days arg] [-md arg] [-policy arg] [-keyfile
14 arg] [-keyform PEM|DER] [-key arg] [-passin arg] [-cert file]
15 [-selfsign] [-in file] [-out file] [-notext] [-outdir dir] [-infiles]
16 [-spkac file] [-ss_cert file] [-preserveDN] [-noemailDN] [-batch]
17 [-msie_hack] [-extensions section] [-extfile section] [-engine id]
18 [-subj arg] [-utf8] [-multivalue-rdn]
19
21 The ca command is a minimal CA application. It can be used to sign
22 certificate requests in a variety of forms and generate CRLs it also
23 maintains a text database of issued certificates and their status.
24 The options descriptions will be divided into each purpose.
26
28 -config filename
29 specifies the configuration file to use.
30 -name section
32 specifies the configuration file section to use (overrides
33 default_ca in the ca section).
34 -in filename
36 an input filename containing a single certificate request to be
37 signed by the CA.
38 -ss_cert filename
40 a single self signed certificate to be signed by the CA.
41 -spkac filename
43 a file containing a single Netscape signed public key and challenge
44 and additional field values to be signed by the CA. See the SPKAC
45 FORMAT section for information on the required input and output
46 format.
47 -infiles
49 if present this should be the last option, all subsequent arguments
50 are assumed to the the names of files containing certificate
51 requests.
52 -out filename
54 the output file to output certificates to. The default is standard
55 output. The certificate details will also be printed out to this
56 file in PEM format (except that -spkac outputs DER format).
57 -outdir directory
59 the directory to output certificates to. The certificate will be
60 written to a filename consisting of the serial number in hex with
61 ".pem" appended.
62 -cert
64 the CA certificate file.
65 -keyfile filename
67 the private key to sign requests with.
68 -keyform PEM|DER
70 the format of the data in the private key file. The default is
71 PEM.
72 -key password
74 the password used to encrypt the private key. Since on some systems
75 the command line arguments are visible (e.g. Unix with the 'ps'
76 utility) this option should be used with caution.
77 -selfsign
79 indicates the issued certificates are to be signed with the key the
80 certificate requests were signed with (given with -keyfile).
81 Cerificate requests signed with a different key are ignored. If
82 -spkac, -ss_cert or -gencrl are given, -selfsign is ignored.
83 A consequence of using -selfsign is that the self-signed
85 certificate appears among the entries in the certificate database
86 (see the configuration option database), and uses the same serial
87 number counter as all other certificates sign with the self-signed
88 certificate.
89 -passin arg
91 the key password source. For more information about the format of
92 arg see the PASS PHRASE ARGUMENTS section in openssl(1).
93 -verbose
95 this prints extra details about the operations being performed.
96 -notext
98 don't output the text form of a certificate to the output file.
99 -startdate date
101 this allows the start date to be explicitly set. The format of the
102 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
103 -enddate date
105 this allows the expiry date to be explicitly set. The format of the
106 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
107 -days arg
109 the number of days to certify the certificate for.
110 -md alg
112 the message digest to use. Possible values include md5, sha1 and
113 mdc2. For full list of digests see openssl dgst -h output. This
114 option also applies to CRLs.
115 -policy arg
117 this option defines the CA "policy" to use. This is a section in
118 the configuration file which decides which fields should be
119 mandatory or match the CA certificate. Check out the POLICY FORMAT
120 section for more information.
121 -msie_hack
123 this is a legacy option to make ca work with very old versions of
124 the IE certificate enrollment control "certenr3". It used
125 UniversalStrings for almost everything. Since the old control has
126 various security bugs its use is strongly discouraged. The newer
127 control "Xenroll" does not need this option.
128 -preserveDN
130 Normally the DN order of a certificate is the same as the order of
131 the fields in the relevant policy section. When this option is set
132 the order is the same as the request. This is largely for
133 compatibility with the older IE enrollment control which would only
134 accept certificates if their DNs match the order of the request.
135 This is not needed for Xenroll.
136 -noemailDN
138 The DN of a certificate can contain the EMAIL field if present in
139 the request DN, however it is good policy just having the e-mail
140 set into the altName extension of the certificate. When this option
141 is set the EMAIL field is removed from the certificate' subject and
142 set only in the, eventually present, extensions. The email_in_dn
143 keyword can be used in the configuration file to enable this
144 behaviour.
145 -batch
147 this sets the batch mode. In this mode no questions will be asked
148 and all certificates will be certified automatically.
149 -extensions section
151 the section of the configuration file containing certificate
152 extensions to be added when a certificate is issued (defaults to
153 x509_extensions unless the -extfile option is used). If no
154 extension section is present then, a V1 certificate is created. If
155 the extension section is present (even if it is empty), then a V3
156 certificate is created. See the:w x509v3_config(5) manual page for
157 details of the extension section format.
158 -extfile file
160 an additional configuration file to read certificate extensions
161 from (using the default section unless the -extensions option is
162 also used).
163 -engine id
165 specifying an engine (by its unique id string) will cause ca to
166 attempt to obtain a functional reference to the specified engine,
167 thus initialising it if needed. The engine will then be set as the
168 default for all available algorithms.
169 -subj arg
171 supersedes subject name given in the request. The arg must be
172 formatted as /type0=value0/type1=value1/type2=..., characters may
173 be escaped by \ (backslash), no spaces are skipped.
174 -utf8
176 this option causes field values to be interpreted as UTF8 strings,
177 by default they are interpreted as ASCII. This means that the field
178 values, whether prompted from a terminal or obtained from a
179 configuration file, must be valid UTF8 strings.
180 -multivalue-rdn
182 this option causes the -subj argument to be interpretedt with full
183 support for multivalued RDNs. Example:
184 /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
186 If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
188
190 -gencrl
191 this option generates a CRL based on information in the index file.
192 -crldays num
194 the number of days before the next CRL is due. That is the days
195 from now to place in the CRL nextUpdate field.
196 -crlhours num
198 the number of hours before the next CRL is due.
199 -revoke filename
201 a filename containing a certificate to revoke.
202 -status serial
204 displays the revocation status of the certificate with the
205 specified serial number and exits.
206 -updatedb
208 Updates the database index to purge expired certificates.
209 -crl_reason reason
211 revocation reason, where reason is one of: unspecified,
212 keyCompromise, CACompromise, affiliationChanged, superseded,
213 cessationOfOperation, certificateHold or removeFromCRL. The
214 matching of reason is case insensitive. Setting any revocation
215 reason will make the CRL v2.
216 In practive removeFromCRL is not particularly useful because it is
218 only used in delta CRLs which are not currently implemented.
219 -crl_hold instruction
221 This sets the CRL revocation reason code to certificateHold and the
222 hold instruction to instruction which must be an OID. Although any
223 OID can be used only holdInstructionNone (the use of which is
224 discouraged by RFC2459) holdInstructionCallIssuer or
225 holdInstructionReject will normally be used.
226 -crl_compromise time
228 This sets the revocation reason to keyCompromise and the compromise
229 time to time. time should be in GeneralizedTime format that is
230 YYYYMMDDHHMMSSZ.
231 -crl_CA_compromise time
233 This is the same as crl_compromise except the revocation reason is
234 set to CACompromise.
235 -crlexts section
237 the section of the configuration file containing CRL extensions to
238 include. If no CRL extension section is present then a V1 CRL is
239 created, if the CRL extension section is present (even if it is
240 empty) then a V2 CRL is created. The CRL extensions specified are
241 CRL extensions and not CRL entry extensions. It should be noted
242 that some software (for example Netscape) can't handle V2 CRLs. See
243 x509v3_config(5) manual page for details of the extension section
244 format.
245
247 The section of the configuration file containing options for ca is
248 found as follows: If the -name command line option is used, then it
249 names the section to be used. Otherwise the section to be used must be
250 named in the default_ca option of the ca section of the configuration
251 file (or in the default section of the configuration file). Besides
252 default_ca, the following options are read directly from the ca
253 section:
254 RANDFILE preserve
255 msie_hack With the exception of RANDFILE, this is probably a bug and
256 may change in future releases.
257 Many of the configuration file options are identical to command line
259 options. Where the option is present in the configuration file and the
260 command line the command line value is used. Where an option is
261 described as mandatory then it must be present in the configuration
262 file or the command line equivalent (if any) used.
263 oid_file
265 This specifies a file containing additional OBJECT IDENTIFIERS.
266 Each line of the file should consist of the numerical form of the
267 object identifier followed by white space then the short name
268 followed by white space and finally the long name.
269 oid_section
271 This specifies a section in the configuration file containing extra
272 object identifiers. Each line should consist of the short name of
273 the object identifier followed by = and the numerical form. The
274 short and long names are the same when this option is used.
275 new_certs_dir
277 the same as the -outdir command line option. It specifies the
278 directory where new certificates will be placed. Mandatory.
279 certificate
281 the same as -cert. It gives the file containing the CA certificate.
282 Mandatory.
283 private_key
285 same as the -keyfile option. The file containing the CA private
286 key. Mandatory.
287 RANDFILE
289 a file used to read and write random number seed information, or an
290 EGD socket (see RAND_egd(3)).
291 default_days
293 the same as the -days option. The number of days to certify a
294 certificate for.
295 default_startdate
297 the same as the -startdate option. The start date to certify a
298 certificate for. If not set the current time is used.
299 default_enddate
301 the same as the -enddate option. Either this option or default_days
302 (or the command line equivalents) must be present.
303 default_crl_hours default_crl_days
305 the same as the -crlhours and the -crldays options. These will only
306 be used if neither command line option is present. At least one of
307 these must be present to generate a CRL.
308 default_md
310 the same as the -md option. The message digest to use. Mandatory.
311 database
313 the text database file to use. Mandatory. This file must be present
314 though initially it will be empty.
315 unique_subject
317 if the value yes is given, the valid certificate entries in the
318 database must have unique subjects. if the value no is given,
319 several valid certificate entries may have the exact same subject.
320 The default value is yes, to be compatible with older (pre 0.9.8)
321 versions of OpenSSL. However, to make CA certificate roll-over
322 easier, it's recommended to use the value no, especially if
323 combined with the -selfsign command line option.
324 serial
326 a text file containing the next serial number to use in hex.
327 Mandatory. This file must be present and contain a valid serial
328 number.
329 crlnumber
331 a text file containing the next CRL number to use in hex. The crl
332 number will be inserted in the CRLs only if this file exists. If
333 this file is present, it must contain a valid CRL number.
334 x509_extensions
336 the same as -extensions.
337 crl_extensions
339 the same as -crlexts.
340 preserve
342 the same as -preserveDN
343 email_in_dn
345 the same as -noemailDN. If you want the EMAIL field to be removed
346 from the DN of the certificate simply set this to 'no'. If not
347 present the default is to allow for the EMAIL filed in the
348 certificate's DN.
349 msie_hack
351 the same as -msie_hack
352 policy
354 the same as -policy. Mandatory. See the POLICY FORMAT section for
355 more information.
356 name_opt, cert_opt
358 these options allow the format used to display the certificate
359 details when asking the user to confirm signing. All the options
360 supported by the x509 utilities -nameopt and -certopt switches can
361 be used here, except the no_signame and no_sigdump are permanently
362 set and cannot be disabled (this is because the certificate
363 signature cannot be displayed because the certificate has not been
364 signed at this point).
365 For convenience the values ca_default are accepted by both to
367 produce a reasonable output.
368 If neither option is present the format used in earlier versions of
370 OpenSSL is used. Use of the old format is strongly discouraged
371 because it only displays fields mentioned in the policy section,
372 mishandles multicharacter string types and does not display
373 extensions.
374 copy_extensions
376 determines how extensions in certificate requests should be
377 handled. If set to none or this option is not present then
378 extensions are ignored and not copied to the certificate. If set to
379 copy then any extensions present in the request that are not
380 already present are copied to the certificate. If set to copyall
381 then all extensions in the request are copied to the certificate:
382 if the extension is already present in the certificate it is
383 deleted first. See the WARNINGS section before using this option.
384 The main use of this option is to allow a certificate request to
386 supply values for certain extensions such as subjectAltName.
387
389 The policy section consists of a set of variables corresponding to
390 certificate DN fields. If the value is "match" then the field value
391 must match the same field in the CA certificate. If the value is
392 "supplied" then it must be present. If the value is "optional" then it
393 may be present. Any fields not mentioned in the policy section are
394 silently deleted, unless the -preserveDN option is set but this can be
395 regarded more of a quirk than intended behaviour.
396
398 The input to the -spkac command line option is a Netscape signed public
399 key and challenge. This will usually come from the KEYGEN tag in an
400 HTML form to create a new private key. It is however possible to
401 create SPKACs using the spkac utility.
402 The file should contain the variable SPKAC set to the value of the
404 SPKAC and also the required DN components as name value pairs. If you
405 need to include the same component twice then it can be preceded by a
406 number and a '.'.
407 When processing SPKAC format, the output is DER if the -out flag is
409 used, but PEM format if sending to stdout or the -outdir flag is used.
410
412 Note: these examples assume that the ca directory structure is already
413 set up and the relevant files already exist. This usually involves
414 creating a CA certificate and private key with req, a serial number
415 file and an empty index file and placing them in the relevant
416 directories.
417 To use the sample configuration file below the directories demoCA,
419 demoCA/private and demoCA/newcerts would be created. The CA certificate
420 would be copied to demoCA/cacert.pem and its private key to
421 demoCA/private/cakey.pem. A file demoCA/serial would be created
422 containing for example "01" and the empty index file demoCA/index.txt.
423 Sign a certificate request:
425 openssl ca -in req.pem -out newcert.pem
427 Sign a certificate request, using CA extensions:
429 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
431 Generate a CRL
433 openssl ca -gencrl -out crl.pem
435 Sign several requests:
437 openssl ca -infiles req1.pem req2.pem req3.pem
439 Certify a Netscape SPKAC:
441 openssl ca -spkac spkac.txt
443 A sample SPKAC file (the SPKAC line has been truncated for clarity):
445 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
447 CN=Steve Test
448 emailAddress=steve@openssl.org
449 0.OU=OpenSSL Group
450 1.OU=Another Group
451 A sample configuration file with the relevant sections for ca:
453 [ ca ]
455 default_ca = CA_default # The default ca section
456 [ CA_default ]
458 dir = ./demoCA # top dir
460 database = $dir/index.txt # index file.
461 new_certs_dir = $dir/newcerts # new certs dir
462 certificate = $dir/cacert.pem # The CA cert
464 serial = $dir/serial # serial no file
465 private_key = $dir/private/cakey.pem# CA private key
466 RANDFILE = $dir/private/.rand # random number file
467 default_days = 365 # how long to certify for
469 default_crl_days= 30 # how long before next CRL
470 default_md = md5 # md to use
471 policy = policy_any # default policy
473 email_in_dn = no # Don't add the email into cert DN
474 name_opt = ca_default # Subject name display option
476 cert_opt = ca_default # Certificate display option
477 copy_extensions = none # Don't copy extensions from request
478 [ policy_any ]
480 countryName = supplied
481 stateOrProvinceName = optional
482 organizationName = optional
483 organizationalUnitName = optional
484 commonName = supplied
485 emailAddress = optional
486
488 Note: the location of all files can change either by compile time
489 options, configuration file entries, environment variables or command
490 line options. The values below reflect the default values.
491 /usr/local/ssl/lib/openssl.cnf - master configuration file
493 ./demoCA - main CA directory
494 ./demoCA/cacert.pem - CA certificate
495 ./demoCA/private/cakey.pem - CA private key
496 ./demoCA/serial - CA serial number file
497 ./demoCA/serial.old - CA serial number backup file
498 ./demoCA/index.txt - CA text database file
499 ./demoCA/index.txt.old - CA text database backup file
500 ./demoCA/certs - certificate output file
501 ./demoCA/.rnd - CA random seed information
502
504 OPENSSL_CONF reflects the location of master configuration file it can
505 be overridden by the -config command line option.
506
508 The text database index file is a critical part of the process and if
509 corrupted it can be difficult to fix. It is theoretically possible to
510 rebuild the index file from all the issued certificates and a current
511 CRL: however there is no option to do this.
512 V2 CRL features like delta CRLs are not currently supported.
514 Although several requests can be input and handled at once it is only
516 possible to include one SPKAC or self signed certificate.
517
519 The use of an in memory text database can cause problems when large
520 numbers of certificates are present because, as the name implies the
521 database has to be kept in memory.
522 The ca command really needs rewriting or the required functionality
524 exposed at either a command or interface level so a more friendly
525 utility (perl script or GUI) can handle things properly. The scripts
526 CA.sh and CA.pl help a little but not very much.
527 Any fields in a request that are not present in a policy are silently
529 deleted. This does not happen if the -preserveDN option is used. To
530 enforce the absence of the EMAIL field within the DN, as suggested by
531 RFCs, regardless the contents of the request' subject the -noemailDN
532 option can be used. The behaviour should be more friendly and
533 configurable.
534 Cancelling some commands by refusing to certify a certificate can
536 create an empty file.
537
539 The ca command is quirky and at times downright unfriendly.
540 The ca utility was originally meant as an example of how to do things
542 in a CA. It was not supposed to be used as a full blown CA itself:
543 nevertheless some people are using it for this purpose.
544 The ca command is effectively a single user command: no locking is done
546 on the various files and attempts to run more than one ca command on
547 the same database can have unpredictable results.
548 The copy_extensions option should be used with caution. If care is not
550 taken then it can be a security risk. For example if a certificate
551 request contains a basicConstraints extension with CA:TRUE and the
552 copy_extensions value is set to copyall and the user does not spot this
553 when the certificate is displayed then this will hand the requestor a
554 valid CA certificate.
555 This situation can be avoided by setting copy_extensions to copy and
557 including basicConstraints with CA:FALSE in the configuration file.
558 Then if the request contains a basicConstraints extension it will be
559 ignored.
560 It is advisable to also include values for other extensions such as
562 keyUsage to prevent a request supplying its own values.
563 Additional restrictions can be placed on the CA certificate itself.
565 For example if the CA certificate has:
566 basicConstraints = CA:TRUE, pathlen:0
568 then even if a certificate is issued with CA:TRUE it will not be valid.
570
572 req(1), spkac(1), x509(1), CA.pl(1), config(5), x509v3_config(5)
5731.0.2k 2019-03-12 CA(1)