]>
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>] | |
d618f703 DSH |
16 | [B<-crl_reason reason>] |
17 | [B<-crl_hold instruction>] | |
18 | [B<-crl_compromise time>] | |
19 | [B<-crl_CA_compromise time>] | |
bad40585 | 20 | [B<-subj arg>] |
aba3e65f DSH |
21 | [B<-crldays days>] |
22 | [B<-crlhours hours>] | |
23 | [B<-crlexts section>] | |
24 | [B<-startdate date>] | |
25 | [B<-enddate date>] | |
26 | [B<-days arg>] | |
27 | [B<-md arg>] | |
28 | [B<-policy arg>] | |
29 | [B<-keyfile arg>] | |
30 | [B<-key arg>] | |
bd08a2bd | 31 | [B<-passin arg>] |
aba3e65f | 32 | [B<-cert file>] |
d6df2b28 | 33 | [B<-selfsign>] |
aba3e65f DSH |
34 | [B<-in file>] |
35 | [B<-out file>] | |
82fc1d9c | 36 | [B<-notext>] |
aba3e65f DSH |
37 | [B<-outdir dir>] |
38 | [B<-infiles>] | |
39 | [B<-spkac file>] | |
40 | [B<-ss_cert file>] | |
41 | [B<-preserveDN>] | |
89da653f | 42 | [B<-noemailDN>] |
aba3e65f DSH |
43 | [B<-batch>] |
44 | [B<-msie_hack>] | |
45 | [B<-extensions section>] | |
dfebac32 | 46 | [B<-extfile section>] |
bfa35550 | 47 | [B<-engine id>] |
aba3e65f DSH |
48 | |
49 | =head1 DESCRIPTION | |
50 | ||
51 | The B<ca> command is a minimal CA application. It can be used | |
52 | to sign certificate requests in a variety of forms and generate | |
53 | CRLs it also maintains a text database of issued certificates | |
54 | and their status. | |
55 | ||
56 | The options descriptions will be divided into each purpose. | |
57 | ||
58 | =head1 CA OPTIONS | |
59 | ||
60 | =over 4 | |
61 | ||
62 | =item B<-config filename> | |
63 | ||
64 | specifies the configuration file to use. | |
65 | ||
8a0a9392 BM |
66 | =item B<-name section> |
67 | ||
68 | specifies the configuration file section to use (overrides | |
69 | B<default_ca> in the B<ca> section). | |
70 | ||
aba3e65f DSH |
71 | =item B<-in filename> |
72 | ||
73 | an input filename containing a single certificate request to be | |
74 | signed by the CA. | |
75 | ||
76 | =item B<-ss_cert filename> | |
77 | ||
78 | a single self signed certificate to be signed by the CA. | |
79 | ||
80 | =item B<-spkac filename> | |
81 | ||
82 | a file containing a single Netscape signed public key and challenge | |
d618f703 | 83 | and additional field values to be signed by the CA. See the B<SPKAC FORMAT> |
aba3e65f DSH |
84 | section for information on the required format. |
85 | ||
86 | =item B<-infiles> | |
87 | ||
88 | if present this should be the last option, all subsequent arguments | |
89 | are assumed to the the names of files containing certificate requests. | |
90 | ||
91 | =item B<-out filename> | |
92 | ||
93 | the output file to output certificates to. The default is standard | |
94 | output. The certificate details will also be printed out to this | |
95 | file. | |
96 | ||
97 | =item B<-outdir directory> | |
98 | ||
99 | the directory to output certificates to. The certificate will be | |
100 | written to a filename consisting of the serial number in hex with | |
101 | ".pem" appended. | |
102 | ||
103 | =item B<-cert> | |
104 | ||
105 | the CA certificate file. | |
106 | ||
107 | =item B<-keyfile filename> | |
108 | ||
109 | the private key to sign requests with. | |
110 | ||
111 | =item B<-key password> | |
112 | ||
19d2bb57 | 113 | the password used to encrypt the private key. Since on some |
aba3e65f DSH |
114 | systems the command line arguments are visible (e.g. Unix with |
115 | the 'ps' utility) this option should be used with caution. | |
116 | ||
d6df2b28 RL |
117 | =item B<-selfsign> |
118 | ||
119 | indicates the issued certificates are to be signed with the key | |
120 | the certificate requests were signed with (given with B<-keyfile>). | |
121 | Cerificate requests signed with a different key are ignored. If | |
122 | B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is | |
123 | ignored. | |
124 | ||
125 | A consequence of using B<-selfsign> is that the self-signed | |
126 | certificate appears among the entries in the certificate database | |
127 | (see the configuration option B<database>), and uses the same | |
128 | serial number counter as all other certificates sign with the | |
129 | self-signed certificate. | |
130 | ||
bd08a2bd DSH |
131 | =item B<-passin arg> |
132 | ||
133 | the key password source. For more information about the format of B<arg> | |
134 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. | |
bad40585 | 135 | |
aba3e65f DSH |
136 | =item B<-verbose> |
137 | ||
138 | this prints extra details about the operations being performed. | |
139 | ||
82fc1d9c DSH |
140 | =item B<-notext> |
141 | ||
142 | don't output the text form of a certificate to the output file. | |
143 | ||
aba3e65f DSH |
144 | =item B<-startdate date> |
145 | ||
146 | this allows the start date to be explicitly set. The format of the | |
147 | date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). | |
148 | ||
149 | =item B<-enddate date> | |
150 | ||
151 | this allows the expiry date to be explicitly set. The format of the | |
152 | date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). | |
153 | ||
154 | =item B<-days arg> | |
155 | ||
156 | the number of days to certify the certificate for. | |
157 | ||
158 | =item B<-md alg> | |
159 | ||
160 | the message digest to use. Possible values include md5, sha1 and mdc2. | |
161 | This option also applies to CRLs. | |
162 | ||
163 | =item B<-policy arg> | |
164 | ||
165 | this option defines the CA "policy" to use. This is a section in | |
166 | the configuration file which decides which fields should be mandatory | |
167 | or match the CA certificate. Check out the B<POLICY FORMAT> section | |
168 | for more information. | |
169 | ||
170 | =item B<-msie_hack> | |
171 | ||
53b1899e | 172 | this is a legacy option to make B<ca> work with very old versions of |
aba3e65f DSH |
173 | the IE certificate enrollment control "certenr3". It used UniversalStrings |
174 | for almost everything. Since the old control has various security bugs | |
175 | its use is strongly discouraged. The newer control "Xenroll" does not | |
176 | need this option. | |
177 | ||
178 | =item B<-preserveDN> | |
179 | ||
53b1899e DSH |
180 | Normally the DN order of a certificate is the same as the order of the |
181 | fields in the relevant policy section. When this option is set the order | |
19d2bb57 | 182 | is the same as the request. This is largely for compatibility with the |
53b1899e DSH |
183 | older IE enrollment control which would only accept certificates if their |
184 | DNs match the order of the request. This is not needed for Xenroll. | |
aba3e65f | 185 | |
89da653f BM |
186 | =item B<-noemailDN> |
187 | ||
188 | The DN of a certificate can contain the EMAIL field if present in the | |
189 | request DN, however it is good policy just having the e-mail set into | |
190 | the altName extension of the certificate. When this option is set the | |
191 | EMAIL field is removed from the certificate' subject and set only in | |
192 | the, eventually present, extensions. The B<email_in_dn> keyword can be | |
193 | used in the configuration file to enable this behaviour. | |
194 | ||
aba3e65f DSH |
195 | =item B<-batch> |
196 | ||
197 | this sets the batch mode. In this mode no questions will be asked | |
198 | and all certificates will be certified automatically. | |
199 | ||
200 | =item B<-extensions section> | |
201 | ||
202 | the section of the configuration file containing certificate extensions | |
dfebac32 BM |
203 | to be added when a certificate is issued (defaults to B<x509_extensions> |
204 | unless the B<-extfile> option is used). If no extension section is | |
205 | present then, a V1 certificate is created. If the extension section | |
206 | is present (even if it is empty), then a V3 certificate is created. | |
207 | ||
208 | =item B<-extfile file> | |
209 | ||
210 | an additional configuration file to read certificate extensions from | |
211 | (using the default section unless the B<-extensions> option is also | |
212 | used). | |
aba3e65f | 213 | |
bfa35550 RL |
214 | =item B<-engine id> |
215 | ||
216 | specifying an engine (by it's unique B<id> string) will cause B<req> | |
217 | to attempt to obtain a functional reference to the specified engine, | |
218 | thus initialising it if needed. The engine will then be set as the default | |
219 | for all available algorithms. | |
220 | ||
aba3e65f DSH |
221 | =back |
222 | ||
223 | =head1 CRL OPTIONS | |
224 | ||
225 | =over 4 | |
226 | ||
227 | =item B<-gencrl> | |
228 | ||
229 | this option generates a CRL based on information in the index file. | |
230 | ||
231 | =item B<-crldays num> | |
232 | ||
233 | the number of days before the next CRL is due. That is the days from | |
234 | now to place in the CRL nextUpdate field. | |
235 | ||
236 | =item B<-crlhours num> | |
237 | ||
238 | the number of hours before the next CRL is due. | |
239 | ||
240 | =item B<-revoke filename> | |
241 | ||
242 | a filename containing a certificate to revoke. | |
243 | ||
d618f703 DSH |
244 | =item B<-crl_reason reason> |
245 | ||
246 | revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>, | |
247 | B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>, | |
248 | B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case | |
249 | insensitive. Setting any revocation reason will make the CRL v2. | |
250 | ||
251 | In practive B<removeFromCRL> is not particularly useful because it is only used | |
252 | in delta CRLs which are not currently implemented. | |
253 | ||
254 | =item B<-crl_hold instruction> | |
255 | ||
256 | This sets the CRL revocation reason code to B<certificateHold> and the hold | |
257 | instruction to B<instruction> which must be an OID. Although any OID can be | |
258 | used only B<holdInstructionNone> (the use of which is discouraged by RFC2459) | |
259 | B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used. | |
260 | ||
261 | =item B<-crl_compromise time> | |
262 | ||
263 | This sets the revocation reason to B<keyCompromise> and the compromise time to | |
264 | B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>. | |
265 | ||
266 | =item B<-crl_CA_compromise time> | |
267 | ||
268 | This is the same as B<crl_compromise> except the revocation reason is set to | |
269 | B<CACompromise>. | |
270 | ||
bad40585 BM |
271 | =item B<-subj arg> |
272 | ||
c0455cbb LJ |
273 | supersedes subject name given in the request. |
274 | The arg must be formatted as I</type0=value0/type1=value1/type2=...>, | |
275 | characters may be escaped by \ (backslash), no spaces are skipped. | |
bad40585 | 276 | |
aba3e65f DSH |
277 | =item B<-crlexts section> |
278 | ||
279 | the section of the configuration file containing CRL extensions to | |
280 | include. If no CRL extension section is present then a V1 CRL is | |
281 | created, if the CRL extension section is present (even if it is | |
282 | empty) then a V2 CRL is created. The CRL extensions specified are | |
283 | CRL extensions and B<not> CRL entry extensions. It should be noted | |
284 | that some software (for example Netscape) can't handle V2 CRLs. | |
285 | ||
286 | =back | |
287 | ||
288 | =head1 CONFIGURATION FILE OPTIONS | |
289 | ||
8a0a9392 BM |
290 | The section of the configuration file containing options for B<ca> |
291 | is found as follows: If the B<-name> command line option is used, | |
292 | then it names the section to be used. Otherwise the section to | |
293 | be used must be named in the B<default_ca> option of the B<ca> section | |
294 | of the configuration file (or in the default section of the | |
295 | configuration file). Besides B<default_ca>, the following options are | |
296 | read directly from the B<ca> section: | |
297 | RANDFILE | |
298 | preserve | |
299 | msie_hack | |
300 | With the exception of B<RANDFILE>, this is probably a bug and may | |
301 | change in future releases. | |
302 | ||
303 | Many of the configuration file options are identical to command line | |
aba3e65f DSH |
304 | options. Where the option is present in the configuration file |
305 | and the command line the command line value is used. Where an | |
306 | option is described as mandatory then it must be present in | |
307 | the configuration file or the command line equivalent (if | |
308 | any) used. | |
309 | ||
310 | =over 4 | |
311 | ||
5e76807b DSH |
312 | =item B<oid_file> |
313 | ||
314 | This specifies a file containing additional B<OBJECT IDENTIFIERS>. | |
315 | Each line of the file should consist of the numerical form of the | |
316 | object identifier followed by white space then the short name followed | |
317 | by white space and finally the long name. | |
318 | ||
319 | =item B<oid_section> | |
320 | ||
321 | This specifies a section in the configuration file containing extra | |
322 | object identifiers. Each line should consist of the short name of the | |
323 | object identifier followed by B<=> and the numerical form. The short | |
324 | and long names are the same when this option is used. | |
325 | ||
aba3e65f DSH |
326 | =item B<new_certs_dir> |
327 | ||
328 | the same as the B<-outdir> command line option. It specifies | |
329 | the directory where new certificates will be placed. Mandatory. | |
330 | ||
331 | =item B<certificate> | |
332 | ||
333 | the same as B<-cert>. It gives the file containing the CA | |
334 | certificate. Mandatory. | |
335 | ||
336 | =item B<private_key> | |
337 | ||
338 | same as the B<-keyfile> option. The file containing the | |
339 | CA private key. Mandatory. | |
340 | ||
341 | =item B<RANDFILE> | |
342 | ||
a4cfd178 UM |
343 | a file used to read and write random number seed information, or |
344 | an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). | |
aba3e65f DSH |
345 | |
346 | =item B<default_days> | |
347 | ||
348 | the same as the B<-days> option. The number of days to certify | |
349 | a certificate for. | |
350 | ||
351 | =item B<default_startdate> | |
352 | ||
353 | the same as the B<-startdate> option. The start date to certify | |
354 | a certificate for. If not set the current time is used. | |
355 | ||
356 | =item B<default_enddate> | |
357 | ||
358 | the same as the B<-enddate> option. Either this option or | |
359 | B<default_days> (or the command line equivalents) must be | |
360 | present. | |
361 | ||
362 | =item B<default_crl_hours default_crl_days> | |
363 | ||
364 | the same as the B<-crlhours> and the B<-crldays> options. These | |
365 | will only be used if neither command line option is present. At | |
366 | least one of these must be present to generate a CRL. | |
367 | ||
368 | =item B<default_md> | |
369 | ||
370 | the same as the B<-md> option. The message digest to use. Mandatory. | |
371 | ||
372 | =item B<database> | |
373 | ||
374 | the text database file to use. Mandatory. This file must be present | |
375 | though initially it will be empty. | |
376 | ||
d6df2b28 RL |
377 | =item B<unique_subject> |
378 | ||
379 | if the value B<yes> is given, the valid certificate entries in the | |
380 | database must have unique subjects. if the value B<no> is given, | |
381 | several valid certificate entries may have the exact same subject. | |
382 | The default value is B<yes>, to be compatible with older (pre 0.9.8) | |
383 | versions of OpenSSL. However, to make CA certificate roll-over easier, | |
384 | it's recommended to use the value B<no>, especially if combined with | |
385 | the B<-selfsign> command line option. | |
386 | ||
c5aba56c | 387 | =item B<serial> |
aba3e65f DSH |
388 | |
389 | a text file containing the next serial number to use in hex. Mandatory. | |
390 | This file must be present and contain a valid serial number. | |
391 | ||
8fbb2af3 RL |
392 | =item B<crlnumber> |
393 | ||
394 | a text file containing the next CRL number to use in hex. The crl number | |
395 | will be inserted in the CRLs only if this file exists. If this file is | |
396 | present, it must contain a valid CRL number. | |
397 | ||
aba3e65f DSH |
398 | =item B<x509_extensions> |
399 | ||
400 | the same as B<-extensions>. | |
401 | ||
402 | =item B<crl_extensions> | |
403 | ||
404 | the same as B<-crlexts>. | |
405 | ||
406 | =item B<preserve> | |
407 | ||
408 | the same as B<-preserveDN> | |
409 | ||
89da653f BM |
410 | =item B<email_in_dn> |
411 | ||
412 | the same as B<-noemailDN>. If you want the EMAIL field to be removed | |
413 | from the DN of the certificate simply set this to 'no'. If not present | |
414 | the default is to allow for the EMAIL filed in the certificate's DN. | |
415 | ||
aba3e65f DSH |
416 | =item B<msie_hack> |
417 | ||
418 | the same as B<-msie_hack> | |
419 | ||
420 | =item B<policy> | |
421 | ||
422 | the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section | |
423 | for more information. | |
424 | ||
b325518f | 425 | =item B<name_opt>, B<cert_opt> |
e890dcdb DSH |
426 | |
427 | these options allow the format used to display the certificate details | |
428 | when asking the user to confirm signing. All the options supported by | |
429 | the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used | |
430 | here, except the B<no_signame> and B<no_sigdump> are permanently set | |
431 | and cannot be disabled (this is because the certificate signature cannot | |
432 | be displayed because the certificate has not been signed at this point). | |
433 | ||
6f2f534b | 434 | For convenience the values B<ca_default> are accepted by both to produce |
e890dcdb DSH |
435 | a reasonable output. |
436 | ||
437 | If neither option is present the format used in earlier versions of | |
438 | OpenSSL is used. Use of the old format is B<strongly> discouraged because | |
439 | it only displays fields mentioned in the B<policy> section, mishandles | |
440 | multicharacter string types and does not display extensions. | |
441 | ||
791bd0cd DSH |
442 | =item B<copy_extensions> |
443 | ||
444 | determines how extensions in certificate requests should be handled. | |
445 | If set to B<none> or this option is not present then extensions are | |
446 | ignored and not copied to the certificate. If set to B<copy> then any | |
447 | extensions present in the request that are not already present are copied | |
448 | to the certificate. If set to B<copyall> then all extensions in the | |
449 | request are copied to the certificate: if the extension is already present | |
450 | in the certificate it is deleted first. See the B<WARNINGS> section before | |
451 | using this option. | |
452 | ||
453 | The main use of this option is to allow a certificate request to supply | |
454 | values for certain extensions such as subjectAltName. | |
455 | ||
aba3e65f DSH |
456 | =back |
457 | ||
458 | =head1 POLICY FORMAT | |
459 | ||
460 | The policy section consists of a set of variables corresponding to | |
461 | certificate DN fields. If the value is "match" then the field value | |
462 | must match the same field in the CA certificate. If the value is | |
463 | "supplied" then it must be present. If the value is "optional" then | |
464 | it may be present. Any fields not mentioned in the policy section | |
465 | are silently deleted, unless the B<-preserveDN> option is set but | |
466 | this can be regarded more of a quirk than intended behaviour. | |
467 | ||
468 | =head1 SPKAC FORMAT | |
469 | ||
470 | The input to the B<-spkac> command line option is a Netscape | |
471 | signed public key and challenge. This will usually come from | |
472 | the B<KEYGEN> tag in an HTML form to create a new private key. | |
473 | It is however possible to create SPKACs using the B<spkac> utility. | |
474 | ||
475 | The file should contain the variable SPKAC set to the value of | |
476 | the SPKAC and also the required DN components as name value pairs. | |
477 | If you need to include the same component twice then it can be | |
478 | preceded by a number and a '.'. | |
479 | ||
480 | =head1 EXAMPLES | |
481 | ||
482 | Note: these examples assume that the B<ca> directory structure is | |
483 | already set up and the relevant files already exist. This usually | |
484 | involves creating a CA certificate and private key with B<req>, a | |
485 | serial number file and an empty index file and placing them in | |
486 | the relevant directories. | |
487 | ||
488 | To use the sample configuration file below the directories demoCA, | |
489 | demoCA/private and demoCA/newcerts would be created. The CA | |
490 | certificate would be copied to demoCA/cacert.pem and its private | |
491 | key to demoCA/private/cakey.pem. A file demoCA/serial would be | |
492 | created containing for example "01" and the empty index file | |
493 | demoCA/index.txt. | |
494 | ||
495 | ||
496 | Sign a certificate request: | |
497 | ||
1675f6eb | 498 | openssl ca -in req.pem -out newcert.pem |
aba3e65f | 499 | |
d428bf8c DSH |
500 | Sign a certificate request, using CA extensions: |
501 | ||
502 | openssl ca -in req.pem -extensions v3_ca -out newcert.pem | |
503 | ||
aba3e65f DSH |
504 | Generate a CRL |
505 | ||
1675f6eb | 506 | openssl ca -gencrl -out crl.pem |
aba3e65f DSH |
507 | |
508 | Sign several requests: | |
509 | ||
1675f6eb | 510 | openssl ca -infiles req1.pem req2.pem req3.pem |
aba3e65f DSH |
511 | |
512 | Certify a Netscape SPKAC: | |
513 | ||
1675f6eb | 514 | openssl ca -spkac spkac.txt |
aba3e65f DSH |
515 | |
516 | A sample SPKAC file (the SPKAC line has been truncated for clarity): | |
517 | ||
518 | SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 | |
519 | CN=Steve Test | |
520 | emailAddress=steve@openssl.org | |
521 | 0.OU=OpenSSL Group | |
522 | 1.OU=Another Group | |
523 | ||
524 | A sample configuration file with the relevant sections for B<ca>: | |
525 | ||
526 | [ ca ] | |
527 | default_ca = CA_default # The default ca section | |
528 | ||
529 | [ CA_default ] | |
530 | ||
531 | dir = ./demoCA # top dir | |
532 | database = $dir/index.txt # index file. | |
533 | new_certs_dir = $dir/newcerts # new certs dir | |
534 | ||
535 | certificate = $dir/cacert.pem # The CA cert | |
536 | serial = $dir/serial # serial no file | |
537 | private_key = $dir/private/cakey.pem# CA private key | |
538 | RANDFILE = $dir/private/.rand # random number file | |
539 | ||
540 | default_days = 365 # how long to certify for | |
541 | default_crl_days= 30 # how long before next CRL | |
542 | default_md = md5 # md to use | |
543 | ||
544 | policy = policy_any # default policy | |
89da653f | 545 | email_in_dn = no # Don't add the email into cert DN |
aba3e65f | 546 | |
b325518f RL |
547 | name_opt = ca_default # Subject name display option |
548 | cert_opt = ca_default # Certificate display option | |
791bd0cd | 549 | copy_extensions = none # Don't copy extensions from request |
e890dcdb | 550 | |
aba3e65f DSH |
551 | [ policy_any ] |
552 | countryName = supplied | |
553 | stateOrProvinceName = optional | |
554 | organizationName = optional | |
555 | organizationalUnitName = optional | |
556 | commonName = supplied | |
557 | emailAddress = optional | |
558 | ||
aba3e65f DSH |
559 | =head1 FILES |
560 | ||
561 | Note: the location of all files can change either by compile time options, | |
19d2bb57 | 562 | configuration file entries, environment variables or command line options. |
aba3e65f DSH |
563 | The values below reflect the default values. |
564 | ||
565 | /usr/local/ssl/lib/openssl.cnf - master configuration file | |
566 | ./demoCA - main CA directory | |
567 | ./demoCA/cacert.pem - CA certificate | |
568 | ./demoCA/private/cakey.pem - CA private key | |
569 | ./demoCA/serial - CA serial number file | |
570 | ./demoCA/serial.old - CA serial number backup file | |
571 | ./demoCA/index.txt - CA text database file | |
572 | ./demoCA/index.txt.old - CA text database backup file | |
573 | ./demoCA/certs - certificate output file | |
574 | ./demoCA/.rnd - CA random seed information | |
575 | ||
576 | =head1 ENVIRONMENT VARIABLES | |
577 | ||
578 | B<OPENSSL_CONF> reflects the location of master configuration file it can | |
579 | be overridden by the B<-config> command line option. | |
580 | ||
581 | =head1 RESTRICTIONS | |
582 | ||
583 | The text database index file is a critical part of the process and | |
584 | if corrupted it can be difficult to fix. It is theoretically possible | |
585 | to rebuild the index file from all the issued certificates and a current | |
586 | CRL: however there is no option to do this. | |
587 | ||
cb26a20c | 588 | V2 CRL features like delta CRLs are not currently supported. |
aba3e65f DSH |
589 | |
590 | Although several requests can be input and handled at once it is only | |
591 | possible to include one SPKAC or self signed certificate. | |
592 | ||
593 | =head1 BUGS | |
594 | ||
595 | The use of an in memory text database can cause problems when large | |
596 | numbers of certificates are present because, as the name implies | |
597 | the database has to be kept in memory. | |
598 | ||
aba3e65f DSH |
599 | The B<ca> command really needs rewriting or the required functionality |
600 | exposed at either a command or interface level so a more friendly utility | |
601 | (perl script or GUI) can handle things properly. The scripts B<CA.sh> and | |
602 | B<CA.pl> help a little but not very much. | |
603 | ||
604 | Any fields in a request that are not present in a policy are silently | |
89da653f BM |
605 | deleted. This does not happen if the B<-preserveDN> option is used. To |
606 | enforce the absence of the EMAIL field within the DN, as suggested by | |
607 | RFCs, regardless the contents of the request' subject the B<-noemailDN> | |
608 | option can be used. The behaviour should be more friendly and | |
609 | configurable. | |
aba3e65f DSH |
610 | |
611 | Cancelling some commands by refusing to certify a certificate can | |
612 | create an empty file. | |
613 | ||
791bd0cd DSH |
614 | =head1 WARNINGS |
615 | ||
1f309464 LJ |
616 | The B<ca> command is quirky and at times downright unfriendly. |
617 | ||
618 | The B<ca> utility was originally meant as an example of how to do things | |
619 | in a CA. It was not supposed to be used as a full blown CA itself: | |
620 | nevertheless some people are using it for this purpose. | |
621 | ||
622 | The B<ca> command is effectively a single user command: no locking is | |
623 | done on the various files and attempts to run more than one B<ca> command | |
624 | on the same database can have unpredictable results. | |
625 | ||
791bd0cd DSH |
626 | The B<copy_extensions> option should be used with caution. If care is |
627 | not taken then it can be a security risk. For example if a certificate | |
628 | request contains a basicConstraints extension with CA:TRUE and the | |
629 | B<copy_extensions> value is set to B<copyall> and the user does not spot | |
630 | this when the certificate is displayed then this will hand the requestor | |
631 | a valid CA certificate. | |
632 | ||
633 | This situation can be avoided by setting B<copy_extensions> to B<copy> | |
634 | and including basicConstraints with CA:FALSE in the configuration file. | |
635 | Then if the request contains a basicConstraints extension it will be | |
636 | ignored. | |
637 | ||
638 | It is advisable to also include values for other extensions such | |
639 | as B<keyUsage> to prevent a request supplying its own values. | |
640 | ||
641 | Additional restrictions can be placed on the CA certificate itself. | |
642 | For example if the CA certificate has: | |
643 | ||
644 | basicConstraints = CA:TRUE, pathlen:0 | |
645 | ||
646 | then even if a certificate is issued with CA:TRUE it will not be valid. | |
647 | ||
aba3e65f DSH |
648 | =head1 SEE ALSO |
649 | ||
bb075f88 RL |
650 | L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>, |
651 | L<config(5)|config(5)> | |
aba3e65f DSH |
652 | |
653 | =cut |