]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | |
2 | =pod | |
3 | ||
4 | =head1 NAME | |
5 | ||
6 | ca - sample minimal CA application | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<ca> | |
11 | [B<-verbose>] | |
12 | [B<-config filename>] | |
13 | [B<-name section>] | |
14 | [B<-gencrl>] | |
15 | [B<-revoke file>] | |
bad40585 | 16 | [B<-subj arg>] |
aba3e65f DSH |
17 | [B<-crldays days>] |
18 | [B<-crlhours hours>] | |
19 | [B<-crlexts section>] | |
20 | [B<-startdate date>] | |
21 | [B<-enddate date>] | |
22 | [B<-days arg>] | |
23 | [B<-md arg>] | |
24 | [B<-policy arg>] | |
25 | [B<-keyfile arg>] | |
26 | [B<-key arg>] | |
bd08a2bd | 27 | [B<-passin arg>] |
aba3e65f DSH |
28 | [B<-cert file>] |
29 | [B<-in file>] | |
30 | [B<-out file>] | |
82fc1d9c | 31 | [B<-notext>] |
aba3e65f DSH |
32 | [B<-outdir dir>] |
33 | [B<-infiles>] | |
34 | [B<-spkac file>] | |
35 | [B<-ss_cert file>] | |
36 | [B<-preserveDN>] | |
37 | [B<-batch>] | |
38 | [B<-msie_hack>] | |
39 | [B<-extensions section>] | |
dfebac32 | 40 | [B<-extfile section>] |
aba3e65f DSH |
41 | |
42 | =head1 DESCRIPTION | |
43 | ||
44 | The B<ca> command is a minimal CA application. It can be used | |
45 | to sign certificate requests in a variety of forms and generate | |
46 | CRLs it also maintains a text database of issued certificates | |
47 | and their status. | |
48 | ||
49 | The options descriptions will be divided into each purpose. | |
50 | ||
51 | =head1 CA OPTIONS | |
52 | ||
53 | =over 4 | |
54 | ||
55 | =item B<-config filename> | |
56 | ||
57 | specifies the configuration file to use. | |
58 | ||
59 | =item B<-in filename> | |
60 | ||
61 | an input filename containing a single certificate request to be | |
62 | signed by the CA. | |
63 | ||
64 | =item B<-ss_cert filename> | |
65 | ||
66 | a single self signed certificate to be signed by the CA. | |
67 | ||
68 | =item B<-spkac filename> | |
69 | ||
70 | a file containing a single Netscape signed public key and challenge | |
71 | and additional field values to be signed by the CA. See the B<NOTES> | |
72 | section for information on the required format. | |
73 | ||
74 | =item B<-infiles> | |
75 | ||
76 | if present this should be the last option, all subsequent arguments | |
77 | are assumed to the the names of files containing certificate requests. | |
78 | ||
79 | =item B<-out filename> | |
80 | ||
81 | the output file to output certificates to. The default is standard | |
82 | output. The certificate details will also be printed out to this | |
83 | file. | |
84 | ||
85 | =item B<-outdir directory> | |
86 | ||
87 | the directory to output certificates to. The certificate will be | |
88 | written to a filename consisting of the serial number in hex with | |
89 | ".pem" appended. | |
90 | ||
91 | =item B<-cert> | |
92 | ||
93 | the CA certificate file. | |
94 | ||
95 | =item B<-keyfile filename> | |
96 | ||
97 | the private key to sign requests with. | |
98 | ||
99 | =item B<-key password> | |
100 | ||
19d2bb57 | 101 | the password used to encrypt the private key. Since on some |
aba3e65f DSH |
102 | systems the command line arguments are visible (e.g. Unix with |
103 | the 'ps' utility) this option should be used with caution. | |
104 | ||
bd08a2bd DSH |
105 | =item B<-passin arg> |
106 | ||
107 | the key password source. For more information about the format of B<arg> | |
108 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. | |
bad40585 | 109 | |
aba3e65f DSH |
110 | =item B<-verbose> |
111 | ||
112 | this prints extra details about the operations being performed. | |
113 | ||
82fc1d9c DSH |
114 | =item B<-notext> |
115 | ||
116 | don't output the text form of a certificate to the output file. | |
117 | ||
aba3e65f DSH |
118 | =item B<-startdate date> |
119 | ||
120 | this allows the start date to be explicitly set. The format of the | |
121 | date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). | |
122 | ||
123 | =item B<-enddate date> | |
124 | ||
125 | this allows the expiry date to be explicitly set. The format of the | |
126 | date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). | |
127 | ||
128 | =item B<-days arg> | |
129 | ||
130 | the number of days to certify the certificate for. | |
131 | ||
132 | =item B<-md alg> | |
133 | ||
134 | the message digest to use. Possible values include md5, sha1 and mdc2. | |
135 | This option also applies to CRLs. | |
136 | ||
137 | =item B<-policy arg> | |
138 | ||
139 | this option defines the CA "policy" to use. This is a section in | |
140 | the configuration file which decides which fields should be mandatory | |
141 | or match the CA certificate. Check out the B<POLICY FORMAT> section | |
142 | for more information. | |
143 | ||
144 | =item B<-msie_hack> | |
145 | ||
53b1899e | 146 | this is a legacy option to make B<ca> work with very old versions of |
aba3e65f DSH |
147 | the IE certificate enrollment control "certenr3". It used UniversalStrings |
148 | for almost everything. Since the old control has various security bugs | |
149 | its use is strongly discouraged. The newer control "Xenroll" does not | |
150 | need this option. | |
151 | ||
152 | =item B<-preserveDN> | |
153 | ||
53b1899e DSH |
154 | Normally the DN order of a certificate is the same as the order of the |
155 | fields in the relevant policy section. When this option is set the order | |
19d2bb57 | 156 | is the same as the request. This is largely for compatibility with the |
53b1899e DSH |
157 | older IE enrollment control which would only accept certificates if their |
158 | DNs match the order of the request. This is not needed for Xenroll. | |
aba3e65f DSH |
159 | |
160 | =item B<-batch> | |
161 | ||
162 | this sets the batch mode. In this mode no questions will be asked | |
163 | and all certificates will be certified automatically. | |
164 | ||
165 | =item B<-extensions section> | |
166 | ||
167 | the section of the configuration file containing certificate extensions | |
dfebac32 BM |
168 | to be added when a certificate is issued (defaults to B<x509_extensions> |
169 | unless the B<-extfile> option is used). If no extension section is | |
170 | present then, a V1 certificate is created. If the extension section | |
171 | is present (even if it is empty), then a V3 certificate is created. | |
172 | ||
173 | =item B<-extfile file> | |
174 | ||
175 | an additional configuration file to read certificate extensions from | |
176 | (using the default section unless the B<-extensions> option is also | |
177 | used). | |
aba3e65f DSH |
178 | |
179 | =back | |
180 | ||
181 | =head1 CRL OPTIONS | |
182 | ||
183 | =over 4 | |
184 | ||
185 | =item B<-gencrl> | |
186 | ||
187 | this option generates a CRL based on information in the index file. | |
188 | ||
189 | =item B<-crldays num> | |
190 | ||
191 | the number of days before the next CRL is due. That is the days from | |
192 | now to place in the CRL nextUpdate field. | |
193 | ||
194 | =item B<-crlhours num> | |
195 | ||
196 | the number of hours before the next CRL is due. | |
197 | ||
198 | =item B<-revoke filename> | |
199 | ||
200 | a filename containing a certificate to revoke. | |
201 | ||
bad40585 BM |
202 | =item B<-subj arg> |
203 | ||
204 | supersedes subject name given in the request | |
205 | ||
aba3e65f DSH |
206 | =item B<-crlexts section> |
207 | ||
208 | the section of the configuration file containing CRL extensions to | |
209 | include. If no CRL extension section is present then a V1 CRL is | |
210 | created, if the CRL extension section is present (even if it is | |
211 | empty) then a V2 CRL is created. The CRL extensions specified are | |
212 | CRL extensions and B<not> CRL entry extensions. It should be noted | |
213 | that some software (for example Netscape) can't handle V2 CRLs. | |
214 | ||
215 | =back | |
216 | ||
217 | =head1 CONFIGURATION FILE OPTIONS | |
218 | ||
219 | The options for B<ca> are contained in the B<ca> section of the | |
220 | configuration file. Many of these are identical to command line | |
221 | options. Where the option is present in the configuration file | |
222 | and the command line the command line value is used. Where an | |
223 | option is described as mandatory then it must be present in | |
224 | the configuration file or the command line equivalent (if | |
225 | any) used. | |
226 | ||
227 | =over 4 | |
228 | ||
5e76807b DSH |
229 | =item B<oid_file> |
230 | ||
231 | This specifies a file containing additional B<OBJECT IDENTIFIERS>. | |
232 | Each line of the file should consist of the numerical form of the | |
233 | object identifier followed by white space then the short name followed | |
234 | by white space and finally the long name. | |
235 | ||
236 | =item B<oid_section> | |
237 | ||
238 | This specifies a section in the configuration file containing extra | |
239 | object identifiers. Each line should consist of the short name of the | |
240 | object identifier followed by B<=> and the numerical form. The short | |
241 | and long names are the same when this option is used. | |
242 | ||
aba3e65f DSH |
243 | =item B<new_certs_dir> |
244 | ||
245 | the same as the B<-outdir> command line option. It specifies | |
246 | the directory where new certificates will be placed. Mandatory. | |
247 | ||
248 | =item B<certificate> | |
249 | ||
250 | the same as B<-cert>. It gives the file containing the CA | |
251 | certificate. Mandatory. | |
252 | ||
253 | =item B<private_key> | |
254 | ||
255 | same as the B<-keyfile> option. The file containing the | |
256 | CA private key. Mandatory. | |
257 | ||
258 | =item B<RANDFILE> | |
259 | ||
a4cfd178 UM |
260 | a file used to read and write random number seed information, or |
261 | an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). | |
aba3e65f DSH |
262 | |
263 | =item B<default_days> | |
264 | ||
265 | the same as the B<-days> option. The number of days to certify | |
266 | a certificate for. | |
267 | ||
268 | =item B<default_startdate> | |
269 | ||
270 | the same as the B<-startdate> option. The start date to certify | |
271 | a certificate for. If not set the current time is used. | |
272 | ||
273 | =item B<default_enddate> | |
274 | ||
275 | the same as the B<-enddate> option. Either this option or | |
276 | B<default_days> (or the command line equivalents) must be | |
277 | present. | |
278 | ||
279 | =item B<default_crl_hours default_crl_days> | |
280 | ||
281 | the same as the B<-crlhours> and the B<-crldays> options. These | |
282 | will only be used if neither command line option is present. At | |
283 | least one of these must be present to generate a CRL. | |
284 | ||
285 | =item B<default_md> | |
286 | ||
287 | the same as the B<-md> option. The message digest to use. Mandatory. | |
288 | ||
289 | =item B<database> | |
290 | ||
291 | the text database file to use. Mandatory. This file must be present | |
292 | though initially it will be empty. | |
293 | ||
294 | =item B<serialfile> | |
295 | ||
296 | a text file containing the next serial number to use in hex. Mandatory. | |
297 | This file must be present and contain a valid serial number. | |
298 | ||
299 | =item B<x509_extensions> | |
300 | ||
301 | the same as B<-extensions>. | |
302 | ||
303 | =item B<crl_extensions> | |
304 | ||
305 | the same as B<-crlexts>. | |
306 | ||
307 | =item B<preserve> | |
308 | ||
309 | the same as B<-preserveDN> | |
310 | ||
311 | =item B<msie_hack> | |
312 | ||
313 | the same as B<-msie_hack> | |
314 | ||
315 | =item B<policy> | |
316 | ||
317 | the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section | |
318 | for more information. | |
319 | ||
320 | =back | |
321 | ||
322 | =head1 POLICY FORMAT | |
323 | ||
324 | The policy section consists of a set of variables corresponding to | |
325 | certificate DN fields. If the value is "match" then the field value | |
326 | must match the same field in the CA certificate. If the value is | |
327 | "supplied" then it must be present. If the value is "optional" then | |
328 | it may be present. Any fields not mentioned in the policy section | |
329 | are silently deleted, unless the B<-preserveDN> option is set but | |
330 | this can be regarded more of a quirk than intended behaviour. | |
331 | ||
332 | =head1 SPKAC FORMAT | |
333 | ||
334 | The input to the B<-spkac> command line option is a Netscape | |
335 | signed public key and challenge. This will usually come from | |
336 | the B<KEYGEN> tag in an HTML form to create a new private key. | |
337 | It is however possible to create SPKACs using the B<spkac> utility. | |
338 | ||
339 | The file should contain the variable SPKAC set to the value of | |
340 | the SPKAC and also the required DN components as name value pairs. | |
341 | If you need to include the same component twice then it can be | |
342 | preceded by a number and a '.'. | |
343 | ||
344 | =head1 EXAMPLES | |
345 | ||
346 | Note: these examples assume that the B<ca> directory structure is | |
347 | already set up and the relevant files already exist. This usually | |
348 | involves creating a CA certificate and private key with B<req>, a | |
349 | serial number file and an empty index file and placing them in | |
350 | the relevant directories. | |
351 | ||
352 | To use the sample configuration file below the directories demoCA, | |
353 | demoCA/private and demoCA/newcerts would be created. The CA | |
354 | certificate would be copied to demoCA/cacert.pem and its private | |
355 | key to demoCA/private/cakey.pem. A file demoCA/serial would be | |
356 | created containing for example "01" and the empty index file | |
357 | demoCA/index.txt. | |
358 | ||
359 | ||
360 | Sign a certificate request: | |
361 | ||
1675f6eb | 362 | openssl ca -in req.pem -out newcert.pem |
aba3e65f | 363 | |
d428bf8c DSH |
364 | Sign a certificate request, using CA extensions: |
365 | ||
366 | openssl ca -in req.pem -extensions v3_ca -out newcert.pem | |
367 | ||
aba3e65f DSH |
368 | Generate a CRL |
369 | ||
1675f6eb | 370 | openssl ca -gencrl -out crl.pem |
aba3e65f DSH |
371 | |
372 | Sign several requests: | |
373 | ||
1675f6eb | 374 | openssl ca -infiles req1.pem req2.pem req3.pem |
aba3e65f DSH |
375 | |
376 | Certify a Netscape SPKAC: | |
377 | ||
1675f6eb | 378 | openssl ca -spkac spkac.txt |
aba3e65f DSH |
379 | |
380 | A sample SPKAC file (the SPKAC line has been truncated for clarity): | |
381 | ||
382 | SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 | |
383 | CN=Steve Test | |
384 | emailAddress=steve@openssl.org | |
385 | 0.OU=OpenSSL Group | |
386 | 1.OU=Another Group | |
387 | ||
388 | A sample configuration file with the relevant sections for B<ca>: | |
389 | ||
390 | [ ca ] | |
391 | default_ca = CA_default # The default ca section | |
392 | ||
393 | [ CA_default ] | |
394 | ||
395 | dir = ./demoCA # top dir | |
396 | database = $dir/index.txt # index file. | |
397 | new_certs_dir = $dir/newcerts # new certs dir | |
398 | ||
399 | certificate = $dir/cacert.pem # The CA cert | |
400 | serial = $dir/serial # serial no file | |
401 | private_key = $dir/private/cakey.pem# CA private key | |
402 | RANDFILE = $dir/private/.rand # random number file | |
403 | ||
404 | default_days = 365 # how long to certify for | |
405 | default_crl_days= 30 # how long before next CRL | |
406 | default_md = md5 # md to use | |
407 | ||
408 | policy = policy_any # default policy | |
409 | ||
410 | [ policy_any ] | |
411 | countryName = supplied | |
412 | stateOrProvinceName = optional | |
413 | organizationName = optional | |
414 | organizationalUnitName = optional | |
415 | commonName = supplied | |
416 | emailAddress = optional | |
417 | ||
418 | =head1 WARNINGS | |
419 | ||
420 | The B<ca> command is quirky and at times downright unfriendly. | |
421 | ||
422 | The B<ca> utility was originally meant as an example of how to do things | |
423 | in a CA. It was not supposed be be used as a full blown CA itself: | |
424 | nevertheless some people are using it for this purpose. | |
425 | ||
426 | The B<ca> command is effectively a single user command: no locking is | |
427 | done on the various files and attempts to run more than one B<ca> command | |
428 | on the same database can have unpredictable results. | |
429 | ||
430 | =head1 FILES | |
431 | ||
432 | Note: the location of all files can change either by compile time options, | |
19d2bb57 | 433 | configuration file entries, environment variables or command line options. |
aba3e65f DSH |
434 | The values below reflect the default values. |
435 | ||
436 | /usr/local/ssl/lib/openssl.cnf - master configuration file | |
437 | ./demoCA - main CA directory | |
438 | ./demoCA/cacert.pem - CA certificate | |
439 | ./demoCA/private/cakey.pem - CA private key | |
440 | ./demoCA/serial - CA serial number file | |
441 | ./demoCA/serial.old - CA serial number backup file | |
442 | ./demoCA/index.txt - CA text database file | |
443 | ./demoCA/index.txt.old - CA text database backup file | |
444 | ./demoCA/certs - certificate output file | |
445 | ./demoCA/.rnd - CA random seed information | |
446 | ||
447 | =head1 ENVIRONMENT VARIABLES | |
448 | ||
449 | B<OPENSSL_CONF> reflects the location of master configuration file it can | |
450 | be overridden by the B<-config> command line option. | |
451 | ||
452 | =head1 RESTRICTIONS | |
453 | ||
454 | The text database index file is a critical part of the process and | |
455 | if corrupted it can be difficult to fix. It is theoretically possible | |
456 | to rebuild the index file from all the issued certificates and a current | |
457 | CRL: however there is no option to do this. | |
458 | ||
459 | CRL entry extensions cannot currently be created: only CRL extensions | |
460 | can be added. | |
461 | ||
462 | V2 CRL features like delta CRL support and CRL numbers are not currently | |
463 | supported. | |
464 | ||
465 | Although several requests can be input and handled at once it is only | |
466 | possible to include one SPKAC or self signed certificate. | |
467 | ||
468 | =head1 BUGS | |
469 | ||
470 | The use of an in memory text database can cause problems when large | |
471 | numbers of certificates are present because, as the name implies | |
472 | the database has to be kept in memory. | |
473 | ||
474 | Certificate request extensions are ignored: some kind of "policy" should | |
475 | be included to use certain static extensions and certain extensions | |
476 | from the request. | |
477 | ||
478 | It is not possible to certify two certificates with the same DN: this | |
479 | is a side effect of how the text database is indexed and it cannot easily | |
b38f9f66 | 480 | be fixed without introducing other problems. Some S/MIME clients can use |
aba3e65f DSH |
481 | two certificates with the same DN for separate signing and encryption |
482 | keys. | |
483 | ||
484 | The B<ca> command really needs rewriting or the required functionality | |
485 | exposed at either a command or interface level so a more friendly utility | |
486 | (perl script or GUI) can handle things properly. The scripts B<CA.sh> and | |
487 | B<CA.pl> help a little but not very much. | |
488 | ||
489 | Any fields in a request that are not present in a policy are silently | |
490 | deleted. This does not happen if the B<-preserveDN> option is used but | |
491 | the extra fields are not displayed when the user is asked to certify | |
492 | a request. The behaviour should be more friendly and configurable. | |
493 | ||
494 | Cancelling some commands by refusing to certify a certificate can | |
495 | create an empty file. | |
496 | ||
497 | =head1 SEE ALSO | |
498 | ||
bb075f88 RL |
499 | L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>, |
500 | L<config(5)|config(5)> | |
aba3e65f DSH |
501 | |
502 | =cut |