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] [-crl_reason reason] [-crl_hold instruction] [-crl_com‐
11 promise time] [-crl_CA_compromise time] [-crldays days] [-crlhours
12 hours] [-crlexts section] [-startdate date] [-enddate date] [-days arg]
13 [-md arg] [-policy arg] [-keyfile arg] [-key arg] [-passin arg] [-cert
14 file] [-selfsign] [-in file] [-out file] [-notext] [-outdir dir]
15 [-infiles] [-spkac file] [-ss_cert file] [-preserveDN] [-noemailDN]
16 [-batch] [-msie_hack] [-extensions section] [-extfile section] [-engine
17 id] [-subj arg] [-utf8] [-multivalue-rdn]
18
20 The ca command is a minimal CA application. It can be used to sign cer‐
21 tificate requests in a variety of forms and generate CRLs it also main‐
22 tains a text database of issued certificates and their status.
23 The options descriptions will be divided into each purpose.
25
27 -config filename
28 specifies the configuration file to use.
29 -name section
31 specifies the configuration file section to use (overrides
32 default_ca in the ca section).
33 -in filename
35 an input filename containing a single certificate request to be
36 signed by the CA.
37 -ss_cert filename
39 a single self signed certificate to be signed by the CA.
40 -spkac filename
42 a file containing a single Netscape signed public key and challenge
43 and additional field values to be signed by the CA. See the SPKAC
44 FORMAT section for information on the required format.
45 -infiles
47 if present this should be the last option, all subsequent arguments
48 are assumed to the the names of files containing certificate
49 requests.
50 -out filename
52 the output file to output certificates to. The default is standard
53 output. The certificate details will also be printed out to this
54 file.
55 -outdir directory
57 the directory to output certificates to. The certificate will be
58 written to a filename consisting of the serial number in hex with
59 ".pem" appended.
60 -cert
62 the CA certificate file.
63 -keyfile filename
65 the private key to sign requests with.
66 -key password
68 the password used to encrypt the private key. Since on some systems
69 the command line arguments are visible (e.g. Unix with the 'ps'
70 utility) this option should be used with caution.
71 -selfsign
73 indicates the issued certificates are to be signed with the key the
74 certificate requests were signed with (given with -keyfile). Cer‐
75 ificate requests signed with a different key are ignored. If
76 -spkac, -ss_cert or -gencrl are given, -selfsign is ignored.
77 A consequence of using -selfsign is that the self-signed certifi‐
79 cate appears among the entries in the certificate database (see the
80 configuration option database), and uses the same serial number
81 counter as all other certificates sign with the self-signed cer‐
82 tificate.
83 -passin arg
85 the key password source. For more information about the format of
86 arg see the PASS PHRASE ARGUMENTS section in openssl(1).
87 -verbose
89 this prints extra details about the operations being performed.
90 -notext
92 don't output the text form of a certificate to the output file.
93 -startdate date
95 this allows the start date to be explicitly set. The format of the
96 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
97 -enddate date
99 this allows the expiry date to be explicitly set. The format of the
100 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
101 -days arg
103 the number of days to certify the certificate for.
104 -md alg
106 the message digest to use. Possible values include md5, sha1 and
107 mdc2. This option also applies to CRLs.
108 -policy arg
110 this option defines the CA "policy" to use. This is a section in
111 the configuration file which decides which fields should be manda‐
112 tory or match the CA certificate. Check out the POLICY FORMAT sec‐
113 tion for more information.
114 -msie_hack
116 this is a legacy option to make ca work with very old versions of
117 the IE certificate enrollment control "certenr3". It used Univer‐
118 salStrings for almost everything. Since the old control has various
119 security bugs its use is strongly discouraged. The newer control
120 "Xenroll" does not need this option.
121 -preserveDN
123 Normally the DN order of a certificate is the same as the order of
124 the fields in the relevant policy section. When this option is set
125 the order is the same as the request. This is largely for compati‐
126 bility with the older IE enrollment control which would only accept
127 certificates if their DNs match the order of the request. This is
128 not needed for Xenroll.
129 -noemailDN
131 The DN of a certificate can contain the EMAIL field if present in
132 the request DN, however it is good policy just having the e-mail
133 set into the altName extension of the certificate. When this option
134 is set the EMAIL field is removed from the certificate' subject and
135 set only in the, eventually present, extensions. The email_in_dn
136 keyword can be used in the configuration file to enable this behav‐
137 iour.
138 -batch
140 this sets the batch mode. In this mode no questions will be asked
141 and all certificates will be certified automatically.
142 -extensions section
144 the section of the configuration file containing certificate exten‐
145 sions to be added when a certificate is issued (defaults to
146 x509_extensions unless the -extfile option is used). If no exten‐
147 sion section is present then, a V1 certificate is created. If the
148 extension section is present (even if it is empty), then a V3 cer‐
149 tificate is created.
150 -extfile file
152 an additional configuration file to read certificate extensions
153 from (using the default section unless the -extensions option is
154 also used).
155 -engine id
157 specifying an engine (by it's unique id string) will cause req to
158 attempt to obtain a functional reference to the specified engine,
159 thus initialising it if needed. The engine will then be set as the
160 default for all available algorithms.
161 -subj arg
163 supersedes subject name given in the request. The arg must be for‐
164 matted as /type0=value0/type1=value1/type2=..., characters may be
165 escaped by \ (backslash), no spaces are skipped.
166 -utf8
168 this option causes field values to be interpreted as UTF8 strings,
169 by default they are interpreted as ASCII. This means that the field
170 values, whether prompted from a terminal or obtained from a config‐
171 uration file, must be valid UTF8 strings.
172 -multivalue-rdn
174 this option causes the -subj argument to be interpretedt with full
175 support for multivalued RDNs. Example:
176 /DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe
178 If -multi-rdn is not used then the UID value is 123456+CN=John Doe.
180
182 -gencrl
183 this option generates a CRL based on information in the index file.
184 -crldays num
186 the number of days before the next CRL is due. That is the days
187 from now to place in the CRL nextUpdate field.
188 -crlhours num
190 the number of hours before the next CRL is due.
191 -revoke filename
193 a filename containing a certificate to revoke.
194 -crl_reason reason
196 revocation reason, where reason is one of: unspecified, keyCompro‐
197 mise, CACompromise, affiliationChanged, superseded, cessationOfOp‐
198 eration, certificateHold or removeFromCRL. The matching of reason
199 is case insensitive. Setting any revocation reason will make the
200 CRL v2.
201 In practive removeFromCRL is not particularly useful because it is
203 only used in delta CRLs which are not currently implemented.
204 -crl_hold instruction
206 This sets the CRL revocation reason code to certificateHold and the
207 hold instruction to instruction which must be an OID. Although any
208 OID can be used only holdInstructionNone (the use of which is dis‐
209 couraged by RFC2459) holdInstructionCallIssuer or holdInstruction‐
210 Reject will normally be used.
211 -crl_compromise time
213 This sets the revocation reason to keyCompromise and the compromise
214 time to time. time should be in GeneralizedTime format that is
215 YYYYMMDDHHMMSSZ.
216 -crl_CA_compromise time
218 This is the same as crl_compromise except the revocation reason is
219 set to CACompromise.
220 -crlexts section
222 the section of the configuration file containing CRL extensions to
223 include. If no CRL extension section is present then a V1 CRL is
224 created, if the CRL extension section is present (even if it is
225 empty) then a V2 CRL is created. The CRL extensions specified are
226 CRL extensions and not CRL entry extensions. It should be noted
227 that some software (for example Netscape) can't handle V2 CRLs.
228
230 The section of the configuration file containing options for ca is
231 found as follows: If the -name command line option is used, then it
232 names the section to be used. Otherwise the section to be used must be
233 named in the default_ca option of the ca section of the configuration
234 file (or in the default section of the configuration file). Besides
235 default_ca, the following options are read directly from the ca sec‐
236 tion:
237 RANDFILE
238 preserve
239 msie_hack With the exception of RANDFILE, this is probably a bug and
240 may change in future releases.
241 Many of the configuration file options are identical to command line
243 options. Where the option is present in the configuration file and the
244 command line the command line value is used. Where an option is
245 described as mandatory then it must be present in the configuration
246 file or the command line equivalent (if any) used.
247 oid_file
249 This specifies a file containing additional OBJECT IDENTIFIERS.
250 Each line of the file should consist of the numerical form of the
251 object identifier followed by white space then the short name fol‐
252 lowed by white space and finally the long name.
253 oid_section
255 This specifies a section in the configuration file containing extra
256 object identifiers. Each line should consist of the short name of
257 the object identifier followed by = and the numerical form. The
258 short and long names are the same when this option is used.
259 new_certs_dir
261 the same as the -outdir command line option. It specifies the
262 directory where new certificates will be placed. Mandatory.
263 certificate
265 the same as -cert. It gives the file containing the CA certificate.
266 Mandatory.
267 private_key
269 same as the -keyfile option. The file containing the CA private
270 key. Mandatory.
271 RANDFILE
273 a file used to read and write random number seed information, or an
274 EGD socket (see RAND_egd(3)).
275 default_days
277 the same as the -days option. The number of days to certify a cer‐
278 tificate for.
279 default_startdate
281 the same as the -startdate option. The start date to certify a cer‐
282 tificate for. If not set the current time is used.
283 default_enddate
285 the same as the -enddate option. Either this option or default_days
286 (or the command line equivalents) must be present.
287 default_crl_hours default_crl_days
289 the same as the -crlhours and the -crldays options. These will only
290 be used if neither command line option is present. At least one of
291 these must be present to generate a CRL.
292 default_md
294 the same as the -md option. The message digest to use. Mandatory.
295 database
297 the text database file to use. Mandatory. This file must be present
298 though initially it will be empty.
299 unique_subject
301 if the value yes is given, the valid certificate entries in the
302 database must have unique subjects. if the value no is given, sev‐
303 eral valid certificate entries may have the exact same subject.
304 The default value is yes, to be compatible with older (pre 0.9.8)
305 versions of OpenSSL. However, to make CA certificate roll-over
306 easier, it's recommended to use the value no, especially if com‐
307 bined with the -selfsign command line option.
308 serial
310 a text file containing the next serial number to use in hex. Manda‐
311 tory. This file must be present and contain a valid serial number.
312 crlnumber
314 a text file containing the next CRL number to use in hex. The crl
315 number will be inserted in the CRLs only if this file exists. If
316 this file is present, it must contain a valid CRL number.
317 x509_extensions
319 the same as -extensions.
320 crl_extensions
322 the same as -crlexts.
323 preserve
325 the same as -preserveDN
326 email_in_dn
328 the same as -noemailDN. If you want the EMAIL field to be removed
329 from the DN of the certificate simply set this to 'no'. If not
330 present the default is to allow for the EMAIL filed in the certifi‐
331 cate's DN.
332 msie_hack
334 the same as -msie_hack
335 policy
337 the same as -policy. Mandatory. See the POLICY FORMAT section for
338 more information.
339 name_opt, cert_opt
341 these options allow the format used to display the certificate
342 details when asking the user to confirm signing. All the options
343 supported by the x509 utilities -nameopt and -certopt switches can
344 be used here, except the no_signame and no_sigdump are permanently
345 set and cannot be disabled (this is because the certificate signa‐
346 ture cannot be displayed because the certificate has not been
347 signed at this point).
348 For convenience the values ca_default are accepted by both to pro‐
350 duce a reasonable output.
351 If neither option is present the format used in earlier versions of
353 OpenSSL is used. Use of the old format is strongly discouraged
354 because it only displays fields mentioned in the policy section,
355 mishandles multicharacter string types and does not display exten‐
356 sions.
357 copy_extensions
359 determines how extensions in certificate requests should be han‐
360 dled. If set to none or this option is not present then extensions
361 are ignored and not copied to the certificate. If set to copy then
362 any extensions present in the request that are not already present
363 are copied to the certificate. If set to copyall then all exten‐
364 sions in the request are copied to the certificate: if the exten‐
365 sion is already present in the certificate it is deleted first. See
366 the WARNINGS section before using this option.
367 The main use of this option is to allow a certificate request to
369 supply values for certain extensions such as subjectAltName.
370
372 The policy section consists of a set of variables corresponding to cer‐
373 tificate DN fields. If the value is "match" then the field value must
374 match the same field in the CA certificate. If the value is "supplied"
375 then it must be present. If the value is "optional" then it may be
376 present. Any fields not mentioned in the policy section are silently
377 deleted, unless the -preserveDN option is set but this can be regarded
378 more of a quirk than intended behaviour.
379
381 The input to the -spkac command line option is a Netscape signed public
382 key and challenge. This will usually come from the KEYGEN tag in an
383 HTML form to create a new private key. It is however possible to cre‐
384 ate SPKACs using the spkac utility.
385 The file should contain the variable SPKAC set to the value of the
387 SPKAC and also the required DN components as name value pairs. If you
388 need to include the same component twice then it can be preceded by a
389 number and a '.'.
390
392 Note: these examples assume that the ca directory structure is already
393 set up and the relevant files already exist. This usually involves cre‐
394 ating a CA certificate and private key with req, a serial number file
395 and an empty index file and placing them in the relevant directories.
396 To use the sample configuration file below the directories demoCA,
398 demoCA/private and demoCA/newcerts would be created. The CA certificate
399 would be copied to demoCA/cacert.pem and its private key to demoCA/pri‐
400 vate/cakey.pem. A file demoCA/serial would be created containing for
401 example "01" and the empty index file demoCA/index.txt.
402 Sign a certificate request:
404 openssl ca -in req.pem -out newcert.pem
406 Sign a certificate request, using CA extensions:
408 openssl ca -in req.pem -extensions v3_ca -out newcert.pem
410 Generate a CRL
412 openssl ca -gencrl -out crl.pem
414 Sign several requests:
416 openssl ca -infiles req1.pem req2.pem req3.pem
418 Certify a Netscape SPKAC:
420 openssl ca -spkac spkac.txt
422 A sample SPKAC file (the SPKAC line has been truncated for clarity):
424 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
426 CN=Steve Test
427 emailAddress=steve@openssl.org
428 0.OU=OpenSSL Group
429 1.OU=Another Group
430 A sample configuration file with the relevant sections for ca:
432 [ ca ]
434 default_ca = CA_default # The default ca section
435 [ CA_default ]
437 dir = ./demoCA # top dir
439 database = $dir/index.txt # index file.
440 new_certs_dir = $dir/newcerts # new certs dir
441 certificate = $dir/cacert.pem # The CA cert
443 serial = $dir/serial # serial no file
444 private_key = $dir/private/cakey.pem# CA private key
445 RANDFILE = $dir/private/.rand # random number file
446 default_days = 365 # how long to certify for
448 default_crl_days= 30 # how long before next CRL
449 default_md = md5 # md to use
450 policy = policy_any # default policy
452 email_in_dn = no # Don't add the email into cert DN
453 name_opt = ca_default # Subject name display option
455 cert_opt = ca_default # Certificate display option
456 copy_extensions = none # Don't copy extensions from request
457 [ policy_any ]
459 countryName = supplied
460 stateOrProvinceName = optional
461 organizationName = optional
462 organizationalUnitName = optional
463 commonName = supplied
464 emailAddress = optional
465
467 Note: the location of all files can change either by compile time
468 options, configuration file entries, environment variables or command
469 line options. The values below reflect the default values.
470 /usr/local/ssl/lib/openssl.cnf - master configuration file
472 ./demoCA - main CA directory
473 ./demoCA/cacert.pem - CA certificate
474 ./demoCA/private/cakey.pem - CA private key
475 ./demoCA/serial - CA serial number file
476 ./demoCA/serial.old - CA serial number backup file
477 ./demoCA/index.txt - CA text database file
478 ./demoCA/index.txt.old - CA text database backup file
479 ./demoCA/certs - certificate output file
480 ./demoCA/.rnd - CA random seed information
481
483 OPENSSL_CONF reflects the location of master configuration file it can
484 be overridden by the -config command line option.
485
487 The text database index file is a critical part of the process and if
488 corrupted it can be difficult to fix. It is theoretically possible to
489 rebuild the index file from all the issued certificates and a current
490 CRL: however there is no option to do this.
491 V2 CRL features like delta CRLs are not currently supported.
493 Although several requests can be input and handled at once it is only
495 possible to include one SPKAC or self signed certificate.
496
498 The use of an in memory text database can cause problems when large
499 numbers of certificates are present because, as the name implies the
500 database has to be kept in memory.
501 The ca command really needs rewriting or the required functionality
503 exposed at either a command or interface level so a more friendly util‐
504 ity (perl script or GUI) can handle things properly. The scripts CA.sh
505 and CA.pl help a little but not very much.
506 Any fields in a request that are not present in a policy are silently
508 deleted. This does not happen if the -preserveDN option is used. To
509 enforce the absence of the EMAIL field within the DN, as suggested by
510 RFCs, regardless the contents of the request' subject the -noemailDN
511 option can be used. The behaviour should be more friendly and config‐
512 urable.
513 Cancelling some commands by refusing to certify a certificate can cre‐
515 ate an empty file.
516
518 The ca command is quirky and at times downright unfriendly.
519 The ca utility was originally meant as an example of how to do things
521 in a CA. It was not supposed to be used as a full blown CA itself: nev‐
522 ertheless some people are using it for this purpose.
523 The ca command is effectively a single user command: no locking is done
525 on the various files and attempts to run more than one ca command on
526 the same database can have unpredictable results.
527 The copy_extensions option should be used with caution. If care is not
529 taken then it can be a security risk. For example if a certificate
530 request contains a basicConstraints extension with CA:TRUE and the
531 copy_extensions value is set to copyall and the user does not spot this
532 when the certificate is displayed then this will hand the requestor a
533 valid CA certificate.
534 This situation can be avoided by setting copy_extensions to copy and
536 including basicConstraints with CA:FALSE in the configuration file.
537 Then if the request contains a basicConstraints extension it will be
538 ignored.
539 It is advisable to also include values for other extensions such as
541 keyUsage to prevent a request supplying its own values.
542 Additional restrictions can be placed on the CA certificate itself.
544 For example if the CA certificate has:
545 basicConstraints = CA:TRUE, pathlen:0
547 then even if a certificate is issued with CA:TRUE it will not be valid.
549
551 req(1), spkac(1), x509(1), CA.pl(1), config(5)
5520.9.8b 2005-07-15 CA(1)