]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | |
2 | =pod | |
3 | ||
4 | =head1 NAME | |
5 | ||
6 | x509 - Certificate display and signing utility | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<x509> | |
11 | [B<-inform DER|PEM|NET>] | |
12 | [B<-outform DER|PEM|NET>] | |
13 | [B<-keyform DER|PEM>] | |
14 | [B<-CAform DER|PEM>] | |
15 | [B<-CAkeyform DER|PEM>] | |
16 | [B<-in filename>] | |
17 | [B<-out filename>] | |
18 | [B<-serial>] | |
19 | [B<-hash>] | |
20 | [B<-subject>] | |
21 | [B<-issuer>] | |
bd4e1527 | 22 | [B<-nameopt option>] |
a91dedca | 23 | [B<-email>] |
aba3e65f DSH |
24 | [B<-startdate>] |
25 | [B<-enddate>] | |
26 | [B<-purpose>] | |
27 | [B<-dates>] | |
28 | [B<-modulus>] | |
29 | [B<-fingerprint>] | |
30 | [B<-alias>] | |
31 | [B<-noout>] | |
32 | [B<-trustout>] | |
33 | [B<-clrtrust>] | |
9868232a | 34 | [B<-clrreject>] |
aba3e65f | 35 | [B<-addtrust arg>] |
9868232a | 36 | [B<-addreject arg>] |
aba3e65f DSH |
37 | [B<-setalias arg>] |
38 | [B<-days arg>] | |
39 | [B<-signkey filename>] | |
40 | [B<-x509toreq>] | |
41 | [B<-req>] | |
42 | [B<-CA filename>] | |
43 | [B<-CAkey filename>] | |
44 | [B<-CAcreateserial>] | |
45 | [B<-CAserial filename>] | |
46 | [B<-text>] | |
47 | [B<-C>] | |
48 | [B<-md2|-md5|-sha1|-mdc2>] | |
49 | [B<-clrext>] | |
50 | [B<-extfile filename>] | |
51 | [B<-extensions section>] | |
52 | ||
53 | =head1 DESCRIPTION | |
54 | ||
55 | The B<x509> command is a multi purpose certificate utility. It can be | |
56 | used to display certificate information, convert certificates to | |
57 | various forms, sign certificate requests like a "mini CA" or edit | |
58 | certificate trust settings. | |
59 | ||
60 | Since there are a large number of options they will split up into | |
61 | various sections. | |
62 | ||
63 | ||
9868232a | 64 | =head1 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS |
aba3e65f DSH |
65 | |
66 | =over 4 | |
67 | ||
68 | =item B<-inform DER|PEM|NET> | |
69 | ||
70 | This specifies the input format normally the command will expect an X509 | |
71 | certificate but this can change if other options such as B<-req> are | |
72 | present. The DER format is the DER encoding of the certificate and PEM | |
73 | is the base64 encoding of the DER encoding with header and footer lines | |
74 | added. The NET option is an obscure Netscape server format that is now | |
75 | obsolete. | |
76 | ||
77 | =item B<-outform DER|PEM|NET> | |
78 | ||
79 | This specifies the output format, the options have the same meaning as the | |
80 | B<-inform> option. | |
81 | ||
82 | =item B<-in filename> | |
83 | ||
84 | This specifies the input filename to read a certificate from or standard input | |
85 | if this option is not specified. | |
86 | ||
87 | =item B<-out filename> | |
88 | ||
89 | This specifies the output filename to write to or standard output by | |
90 | default. | |
91 | ||
9868232a DSH |
92 | =item B<-md2|-md5|-sha1|-mdc2> |
93 | ||
94 | the digest to use. This affects any signing or display option that uses a message | |
95 | digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not | |
96 | specified then MD5 is used. If the key being used to sign with is a DSA key then | |
97 | this option has no effect: SHA1 is always used with DSA keys. | |
98 | ||
99 | ||
aba3e65f DSH |
100 | =back |
101 | ||
102 | =head1 DISPLAY OPTIONS | |
103 | ||
104 | Note: the B<-alias> and B<-purpose> options are also display options | |
19d2bb57 | 105 | but are described in the B<TRUST OPTIONS> section. |
aba3e65f DSH |
106 | |
107 | =over 4 | |
108 | ||
109 | =item B<-text> | |
110 | ||
111 | prints out the certificate in text form. Full details are output including the | |
112 | public key, signature algorithms, issuer and subject names, serial number | |
113 | any extensions present and any trust settings. | |
114 | ||
115 | =item B<-noout> | |
116 | ||
117 | this option prevents output of the encoded version of the request. | |
118 | ||
119 | =item B<-modulus> | |
120 | ||
121 | this option prints out the value of the modulus of the public key | |
122 | contained in the certificate. | |
123 | ||
124 | =item B<-serial> | |
125 | ||
126 | outputs the certificate serial number. | |
127 | ||
128 | =item B<-hash> | |
129 | ||
938ead8f DSH |
130 | outputs the "hash" of the certificate subject name. This is used in OpenSSL to |
131 | form an index to allow certificates in a directory to be looked up by subject | |
aba3e65f DSH |
132 | name. |
133 | ||
134 | =item B<-subject> | |
135 | ||
136 | outputs the subject name. | |
137 | ||
138 | =item B<-issuer> | |
139 | ||
140 | outputs the issuer name. | |
141 | ||
bd4e1527 DSH |
142 | =item B<-nameopt option> |
143 | ||
144 | option which determine how the subject or issuer names are displayed. This | |
145 | option may be used more than once to set multiple options. See the B<NAME | |
146 | OPTIONS> section for more information. | |
147 | ||
a91dedca DSH |
148 | =item B<-email> |
149 | ||
150 | outputs the email address(es) if any. | |
151 | ||
aba3e65f DSH |
152 | =item B<-startdate> |
153 | ||
154 | prints out the start date of the certificate, that is the notBefore date. | |
155 | ||
156 | =item B<-enddate> | |
157 | ||
158 | prints out the expiry date of the certificate, that is the notAfter date. | |
159 | ||
160 | =item B<-dates> | |
161 | ||
162 | prints out the start and expiry dates of a certificate. | |
163 | ||
164 | =item B<-fingerprint> | |
165 | ||
9868232a | 166 | prints out the digest of the DER encoded version of the whole certificate. |
aba3e65f DSH |
167 | |
168 | =item B<-C> | |
169 | ||
170 | this outputs the certificate in the form of a C source file. | |
171 | ||
172 | =back | |
173 | ||
174 | =head1 TRUST SETTINGS | |
175 | ||
176 | Please note these options are currently experimental and may well change. | |
177 | ||
178 | A B<trusted certificate> is an ordinary certificate which has several | |
179 | additional pieces of information attached to it such as the permitted | |
180 | and prohibited uses of the certificate and an "alias". | |
181 | ||
182 | Normally when a certificate is being verified at least one certificate | |
183 | must be "trusted". By default a trusted certificate must be stored | |
184 | locally and must be a root CA: any certificate chain ending in this CA | |
185 | is then usable for any purpose. | |
186 | ||
13938ace DSH |
187 | Trust settings currently are only used with a root CA. They allow a finer |
188 | control over the purposes the root CA can be used for. For example a CA | |
189 | may be trusted for SSL client but not SSL server use. | |
aba3e65f DSH |
190 | |
191 | See the description of the B<verify> utility for more information on the | |
192 | meaning of trust settings. | |
193 | ||
657e60fa | 194 | Future versions of OpenSSL will recognize trust settings on any |
13938ace DSH |
195 | certificate: not just root CAs. |
196 | ||
197 | ||
aba3e65f DSH |
198 | =over 4 |
199 | ||
200 | =item B<-trustout> | |
201 | ||
202 | this causes B<x509> to output a B<trusted> certificate. An ordinary | |
203 | or trusted certificate can be input but by default an ordinary | |
204 | certificate is output and any trust settings are discarded. With the | |
205 | B<-trustout> option a trusted certificate is output. A trusted | |
206 | certificate is automatically output if any trust settings are modified. | |
207 | ||
208 | =item B<-setalias arg> | |
209 | ||
210 | sets the alias of the certificate. This will allow the certificate | |
19d2bb57 | 211 | to be referred to using a nickname for example "Steve's Certificate". |
aba3e65f DSH |
212 | |
213 | =item B<-alias> | |
214 | ||
215 | outputs the certificate alias, if any. | |
216 | ||
217 | =item B<-clrtrust> | |
218 | ||
219 | clears all the permitted or trusted uses of the certificate. | |
220 | ||
9868232a | 221 | =item B<-clrreject> |
aba3e65f | 222 | |
13938ace | 223 | clears all the prohibited or rejected uses of the certificate. |
aba3e65f DSH |
224 | |
225 | =item B<-addtrust arg> | |
226 | ||
555b22cf DSH |
227 | adds a trusted certificate use. Any object name can be used here |
228 | but currently only B<clientAuth> (SSL client use), B<serverAuth> | |
229 | (SSL server use) and B<emailProtection> (S/MIME email) are used. | |
230 | Other OpenSSL applications may define additional uses. | |
aba3e65f | 231 | |
9868232a | 232 | =item B<-addreject arg> |
aba3e65f DSH |
233 | |
234 | adds a prohibited use. It accepts the same values as the B<-addtrust> | |
235 | option. | |
236 | ||
237 | =item B<-purpose> | |
238 | ||
239 | this option performs tests on the certificate extensions and outputs | |
5f2f0b55 DSH |
240 | the results. For a more complete description see the B<CERTIFICATE |
241 | EXTENSIONS> section. | |
aba3e65f DSH |
242 | |
243 | =back | |
244 | ||
245 | =head1 SIGNING OPTIONS | |
246 | ||
247 | The B<x509> utility can be used to sign certificates and requests: it | |
248 | can thus behave like a "mini CA". | |
249 | ||
250 | =over 4 | |
251 | ||
252 | =item B<-signkey filename> | |
253 | ||
254 | this option causes the input file to be self signed using the supplied | |
255 | private key. | |
256 | ||
257 | If the input file is a certificate it sets the issuer name to the | |
258 | subject name (i.e. makes it self signed) changes the public key to the | |
259 | supplied value and changes the start and end dates. The start date is | |
260 | set to the current time and the end date is set to a value determined | |
261 | by the B<-days> option. Any certificate extensions are retained unless | |
262 | the B<-clrext> option is supplied. | |
263 | ||
264 | If the input is a certificate request then a self signed certificate | |
265 | is created using the supplied private key using the subject name in | |
266 | the request. | |
267 | ||
268 | =item B<-clrext> | |
269 | ||
270 | delete any extensions from a certificate. This option is used when a | |
271 | certificate is being created from another certificate (for example with | |
272 | the B<-signkey> or the B<-CA> options). Normally all extensions are | |
273 | retained. | |
274 | ||
275 | =item B<-keyform PEM|DER> | |
276 | ||
277 | specifies the format (DER or PEM) of the private key file used in the | |
278 | B<-signkey> option. | |
279 | ||
280 | =item B<-days arg> | |
281 | ||
282 | specifies the number of days to make a certificate valid for. The default | |
283 | is 30 days. | |
284 | ||
285 | =item B<-x509toreq> | |
286 | ||
287 | converts a certificate into a certificate request. The B<-signkey> option | |
288 | is used to pass the required private key. | |
289 | ||
290 | =item B<-req> | |
291 | ||
292 | by default a certificate is expected on input. With this option a | |
293 | certificate request is expected instead. | |
294 | ||
295 | =item B<-CA filename> | |
296 | ||
297 | specifies the CA certificate to be used for signing. When this option is | |
298 | present B<x509> behaves like a "mini CA". The input file is signed by this | |
299 | CA using this option: that is its issuer name is set to the subject name | |
300 | of the CA and it is digitally signed using the CAs private key. | |
301 | ||
302 | This option is normally combined with the B<-req> option. Without the | |
303 | B<-req> option the input is a certificate which must be self signed. | |
304 | ||
305 | =item B<-CAkey filename> | |
306 | ||
307 | sets the CA private key to sign a certificate with. If this option is | |
308 | not specified then it is assumed that the CA private key is present in | |
309 | the CA certificate file. | |
310 | ||
311 | =item B<-CAserial filename> | |
312 | ||
313 | sets the CA serial number file to use. | |
314 | ||
315 | When the B<-CA> option is used to sign a certificate it uses a serial | |
316 | number specified in a file. This file consist of one line containing | |
317 | an even number of hex digits with the serial number to use. After each | |
318 | use the serial number is incremented and written out to the file again. | |
319 | ||
320 | The default filename consists of the CA certificate file base name with | |
321 | ".srl" appended. For example if the CA certificate file is called | |
322 | "mycacert.pem" it expects to find a serial number file called "mycacert.srl". | |
323 | ||
324 | =item B<-CAcreateserial filename> | |
325 | ||
326 | with this option the CA serial number file is created if it does not exist: | |
8100490a DSH |
327 | it will contain the serial number "02" and the certificate being signed will |
328 | have the 1 as its serial number. Normally if the B<-CA> option is specified | |
329 | and the serial number file does not exist it is an error. | |
aba3e65f | 330 | |
aba3e65f DSH |
331 | =item B<-extfile filename> |
332 | ||
333 | file containing certificate extensions to use. If not specified then | |
334 | no extensions are added to the certificate. | |
335 | ||
336 | =item B<-extensions section> | |
337 | ||
338 | the section to add certificate extensions from. If this option is not | |
339 | specified then the extensions should either be contained in the unnamed | |
340 | (default) section or the default section should contain a variable called | |
341 | "extensions" which contains the section to use. | |
342 | ||
343 | =back | |
344 | ||
bd4e1527 DSH |
345 | =head1 NAME OPTIONS |
346 | ||
347 | The B<nameopt> command line switch determines how the subject and issuer | |
348 | names are displayed. If no B<nameopt> switch is present the default "oneline" | |
349 | format is used which is compatible with previous versions of OpenSSL. | |
350 | Each option is described in detail below, all options can be preceded by | |
351 | a B<-> to turn the option off. Only the first four will normally be used. | |
352 | ||
353 | =over 4 | |
354 | ||
355 | =item B<compat> | |
356 | ||
357 | use the old format. This is equivalent to specifying no name options at all. | |
358 | ||
359 | =item B<RFC2253> | |
360 | ||
361 | displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>, | |
362 | B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>, | |
363 | B<sep_comma_plus>, B<dn_rev> and B<sname>. | |
364 | ||
365 | =item B<oneline> | |
366 | ||
367 | a oneline format which is more readable than RFC2253. It is equivalent to | |
368 | specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>, | |
369 | B<dump_der>, B<use_quote>, B<sep_comma_plus_spc>, B<spc_eq> and B<sname> | |
370 | options. | |
371 | ||
372 | =item B<multiline> | |
373 | ||
374 | a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, | |
375 | B<spc_eq> and B<lname>. | |
376 | ||
377 | =item B<esc_2253> | |
378 | ||
379 | escape the "special" characters required by RFC2253 in a field That is | |
380 | B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginnging of a string | |
381 | and a space character at the beginning or end of a string. | |
382 | ||
383 | =item B<esc_ctrl> | |
384 | ||
385 | escape and control characters. That is those with ASCII values less than | |
386 | 0x20 (space) and the delete (0x7f) character. They are escaped using the | |
387 | RFC2253 \XX notation (where XX are two hex digits representing the | |
388 | character value). | |
389 | ||
390 | =item B<esc_msb> | |
391 | ||
392 | escape characters with the MSB set, that is with ASCII values larger than | |
393 | 127. | |
394 | ||
395 | =item B<use_quote> | |
396 | ||
397 | escapes some characters by surrounding the whole string with B<"> characters, | |
398 | without the option all escaping is done with the B<\> character. | |
399 | ||
400 | =item B<utf8> | |
401 | ||
402 | convert all strings to UTF8 format first. This is required by RFC2253. If | |
403 | you are lucky enough to have a UTF8 compatible terminal then the use | |
404 | of this option (and B<not> setting B<esc_msb>) may result in the correct | |
405 | display of multibyte (international) characters. Is this option is not | |
406 | present then multibyte characters larger than 0xff will be represented | |
407 | using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits. | |
408 | Also if this option is off any UTF8Strings will be converted to their | |
409 | character form first. | |
410 | ||
411 | =item B<no_type> | |
412 | ||
413 | this option does not attempt to interpret multibyte characters in any | |
414 | way. That is their content octets are merely dumped as though one octet | |
415 | represents each character. This is useful for diagnostic purposes but | |
416 | will result in rather odd looking output. | |
417 | ||
418 | =item B<show_type> | |
419 | ||
420 | show the type of the ASN1 character string. The type precedes the | |
421 | field contents. For example "BMPSTRING: Hello World". | |
422 | ||
423 | =item B<dump_der> | |
424 | ||
425 | when this option is set any fields that need to be hexdumped will | |
426 | be dumped using the DER encoding of the field. Otherwise just the | |
427 | content octets will be displayed. Both options use the RFC2253 | |
428 | B<#XXXX...> format. | |
429 | ||
430 | =item B<dump_nostr> | |
431 | ||
432 | dump non character string types (for example OCTET STRING) if this | |
433 | option is not set then non character string types will be displayed | |
434 | as though each content octet repesents a single character. | |
435 | ||
436 | =item B<dump_all> | |
437 | ||
438 | dump all fields. This option when used with B<dump_der> allows the | |
439 | DER encoding of the structure to be unambiguously determined. | |
440 | ||
441 | =item B<dump_unknown> | |
442 | ||
443 | dump any field whose OID is not recognised by OpenSSL. | |
444 | ||
445 | =item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>, | |
446 | B<sep_multiline> | |
447 | ||
448 | these options determine the field separators. The first character is | |
449 | between RDNs and the second between multiple AVAs (multiple AVAs are | |
450 | very rare and their use is discouraged). The options ending in | |
451 | "space" additionally place a space after the separator to make it | |
452 | more readable. The B<sep_multiline> uses a linefeed character for | |
453 | the RDN separator and a spaced B<+> for the AVA separator. It also | |
454 | indents the fields by four characters. | |
455 | ||
456 | =item B<dn_rev> | |
457 | ||
458 | reverse the fields of the DN. This is required by RFC2253. As a side | |
459 | effect this also reveress the order of multiple AVAs but this is | |
460 | permissible. | |
461 | ||
462 | =item B<nofname>, B<sname>, B<lname>, B<oid> | |
463 | ||
464 | these options alter how the field name is displayed. B<nofname> does | |
465 | not display the field at all. B<sname> uses the "short name" form | |
466 | (CN for commonName for example). B<lname> uses the long form. | |
467 | B<oid> represents the OID in numerical form and is useful for | |
468 | diagnostic purpose. | |
469 | ||
470 | =item B<spc_eq> | |
471 | ||
472 | places spaces round the B<=> character which follows the field | |
473 | name. | |
474 | ||
475 | =back | |
476 | ||
aba3e65f DSH |
477 | =head1 EXAMPLES |
478 | ||
479 | Note: in these examples the '\' means the example should be all on one | |
480 | line. | |
481 | ||
482 | Display the contents of a certificate: | |
483 | ||
1675f6eb | 484 | openssl x509 -in cert.pem -noout -text |
aba3e65f | 485 | |
9868232a | 486 | Display the certificate serial number: |
aba3e65f | 487 | |
1675f6eb | 488 | openssl x509 -in cert.pem -noout -serial |
aba3e65f | 489 | |
bd4e1527 DSH |
490 | Display the certificate subject name: |
491 | ||
492 | openssl x509 -in cert.pem -noout -subject | |
493 | ||
494 | Display the certificate subject name in RFC2253 form: | |
495 | ||
496 | openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 | |
497 | ||
498 | Display the certificate subject name in oneline form on a terminal | |
499 | supporting UTF8: | |
500 | ||
501 | openssl x509 -in cert.pem -noout -subject -nameopt oneline -nameopt -escmsb | |
502 | ||
9868232a DSH |
503 | Display the certificate MD5 fingerprint: |
504 | ||
1675f6eb | 505 | openssl x509 -in cert.pem -noout -fingerprint |
9868232a DSH |
506 | |
507 | Display the certificate SHA1 fingerprint: | |
508 | ||
1675f6eb | 509 | openssl x509 -sha1 -in cert.pem -noout -fingerprint |
aba3e65f DSH |
510 | |
511 | Convert a certificate from PEM to DER format: | |
512 | ||
1675f6eb | 513 | openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER |
aba3e65f DSH |
514 | |
515 | Convert a certificate to a certificate request: | |
516 | ||
1675f6eb | 517 | openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem |
aba3e65f DSH |
518 | |
519 | Convert a certificate request into a self signed certificate using | |
520 | extensions for a CA: | |
521 | ||
1675f6eb RL |
522 | openssl x509 -req -in careq.pem -config openssl.cnf -extensions v3_ca \ |
523 | -signkey key.pem -out cacert.pem | |
aba3e65f | 524 | |
19d2bb57 | 525 | Sign a certificate request using the CA certificate above and add user |
aba3e65f DSH |
526 | certificate extensions: |
527 | ||
1675f6eb RL |
528 | openssl x509 -req -in req.pem -config openssl.cnf -extensions v3_usr \ |
529 | -CA cacert.pem -CAkey key.pem -CAcreateserial | |
aba3e65f DSH |
530 | |
531 | ||
532 | Set a certificate to be trusted for SSL client use and change set its alias to | |
533 | "Steve's Class 1 CA" | |
534 | ||
1675f6eb RL |
535 | openssl x509 -in cert.pem -addtrust sslclient \ |
536 | -alias "Steve's Class 1 CA" -out trust.pem | |
aba3e65f | 537 | |
0286d944 DSH |
538 | =head1 NOTES |
539 | ||
540 | The PEM format uses the header and footer lines: | |
541 | ||
542 | -----BEGIN CERTIFICATE---- | |
543 | -----END CERTIFICATE---- | |
544 | ||
545 | it will also handle files containing: | |
546 | ||
547 | -----BEGIN X509 CERTIFICATE---- | |
548 | -----END X509 CERTIFICATE---- | |
549 | ||
9868232a DSH |
550 | Trusted certificates have the lines |
551 | ||
552 | -----BEGIN TRUSTED CERTIFICATE---- | |
553 | -----END TRUSTED CERTIFICATE---- | |
554 | ||
bd4e1527 DSH |
555 | The conversion to UTF8 format used with the name options assumes that |
556 | T61Strings use the ISO8859-1 character set. This is wrong but Netscape | |
557 | and MSIE do this as do many certificates. So although this is incorrect | |
558 | it is more likely to display the majority of certificates correctly. | |
559 | ||
9868232a DSH |
560 | The B<-fingerprint> option takes the digest of the DER encoded certificate. |
561 | This is commonly called a "fingerprint". Because of the nature of message | |
562 | digests the fingerprint of a certificate is unique to that certificate and | |
563 | two certificates with the same fingerprint can be considered to be the same. | |
564 | ||
565 | The Netscape fingerprint uses MD5 whereas MSIE uses SHA1. | |
566 | ||
a91dedca DSH |
567 | The B<-email> option searches the subject name and the subject alternative |
568 | name extension. Only unique email addresses will be printed out: it will | |
569 | not print the same address more than once. | |
570 | ||
5f2f0b55 DSH |
571 | =head1 CERTIFICATE EXTENSIONS |
572 | ||
573 | The B<-purpose> option checks the certificate extensions and determines | |
574 | what the certificate can be used for. The actual checks done are rather | |
575 | complex and include various hacks and workarounds to handle broken | |
576 | certificates and software. | |
577 | ||
578 | The same code is used when verifying untrusted certificates in chains | |
579 | so this section is useful if a chain is rejected by the verify code. | |
580 | ||
581 | The basicConstraints extension CA flag is used to determine whether the | |
582 | certificate can be used as a CA. If the CA flag is true then it is a CA, | |
583 | if the CA flag is false then it is not a CA. B<All> CAs should have the | |
584 | CA flag set to true. | |
585 | ||
586 | If the basicConstraints extension is absent then the certificate is | |
587 | considered to be a "possible CA" other extensions are checked according | |
588 | to the intended use of the certificate. A warning is given in this case | |
589 | because the certificate should really not be regarded as a CA: however | |
590 | it is allowed to be a CA to work around some broken software. | |
591 | ||
592 | If the certificate is a V1 certificate (and thus has no extensions) and | |
593 | it is self signed it is also assumed to be a CA but a warning is again | |
594 | given: this is to work around the problem of Verisign roots which are V1 | |
595 | self signed certificates. | |
596 | ||
597 | If the keyUsage extension is present then additional restraints are | |
598 | made on the uses of the certificate. A CA certificate B<must> have the | |
599 | keyCertSign bit set if the keyUsage extension is present. | |
600 | ||
601 | The extended key usage extension places additional restrictions on the | |
602 | certificate uses. If this extension is present (whether critical or not) | |
603 | the key can only be used for the purposes specified. | |
604 | ||
605 | A complete description of each test is given below. The comments about | |
606 | basicConstraints and keyUsage and V1 certificates above apply to B<all> | |
607 | CA certificates. | |
608 | ||
609 | ||
610 | =over 4 | |
611 | ||
612 | =item B<SSL Client> | |
613 | ||
614 | The extended key usage extension must be absent or include the "web client | |
615 | authentication" OID. keyUsage must be absent or it must have the | |
616 | digitalSignature bit set. Netscape certificate type must be absent or it must | |
617 | have the SSL client bit set. | |
618 | ||
619 | =item B<SSL Client CA> | |
620 | ||
621 | The extended key usage extension must be absent or include the "web client | |
622 | authentication" OID. Netscape certificate type must be absent or it must have | |
623 | the SSL CA bit set: this is used as a work around if the basicConstraints | |
624 | extension is absent. | |
625 | ||
626 | =item B<SSL Server> | |
627 | ||
628 | The extended key usage extension must be absent or include the "web server | |
629 | authentication" and/or one of the SGC OIDs. keyUsage must be absent or it | |
630 | must have the digitalSignature, the keyEncipherment set or both bits set. | |
631 | Netscape certificate type must be absent or have the SSL server bit set. | |
632 | ||
633 | =item B<SSL Server CA> | |
634 | ||
635 | The extended key usage extension must be absent or include the "web server | |
636 | authentication" and/or one of the SGC OIDs. Netscape certificate type must | |
637 | be absent or the SSL CA bit must be set: this is used as a work around if the | |
638 | basicConstraints extension is absent. | |
639 | ||
640 | =item B<Netscape SSL Server> | |
641 | ||
642 | For Netscape SSL clients to connect to an SSL server it must have the | |
643 | keyEncipherment bit set if the keyUsage extension is present. This isn't | |
644 | always valid because some cipher suites use the key for digital signing. | |
645 | Otherwise it is the same as a normal SSL server. | |
646 | ||
647 | =item B<Common S/MIME Client Tests> | |
648 | ||
649 | The extended key usage extension must be absent or include the "email | |
650 | protection" OID. Netscape certificate type must be absent or should have the | |
651 | S/MIME bit set. If the S/MIME bit is not set in netscape certificate type | |
652 | then the SSL client bit is tolerated as an alternative but a warning is shown: | |
653 | this is because some Verisign certificates don't set the S/MIME bit. | |
654 | ||
655 | =item B<S/MIME Signing> | |
656 | ||
657 | In addition to the common S/MIME client tests the digitalSignature bit must | |
658 | be set if the keyUsage extension is present. | |
659 | ||
660 | =item B<S/MIME Encryption> | |
661 | ||
662 | In addition to the common S/MIME tests the keyEncipherment bit must be set | |
663 | if the keyUsage extension is present. | |
664 | ||
665 | =item B<S/MIME CA> | |
666 | ||
667 | The extended key usage extension must be absent or include the "email | |
668 | protection" OID. Netscape certificate type must be absent or must have the | |
669 | S/MIME CA bit set: this is used as a work around if the basicConstraints | |
670 | extension is absent. | |
671 | ||
672 | =item B<CRL Signing> | |
673 | ||
674 | The keyUsage extension must be absent or it must have the CRL signing bit | |
675 | set. | |
676 | ||
677 | =item B<CRL Signing CA> | |
678 | ||
679 | The normal CA tests apply. Except in this case the basicConstraints extension | |
680 | must be present. | |
681 | ||
682 | =back | |
683 | ||
aba3e65f DSH |
684 | =head1 BUGS |
685 | ||
aba3e65f DSH |
686 | Extensions in certificates are not transferred to certificate requests and |
687 | vice versa. | |
688 | ||
689 | It is possible to produce invalid certificates or requests by specifying the | |
690 | wrong private key or using inconsistent options in some cases: these should | |
691 | be checked. | |
692 | ||
9868232a | 693 | There should be options to explicitly set such things as start and end |
aba3e65f DSH |
694 | dates rather than an offset from the current time. |
695 | ||
696 | The code to implement the verify behaviour described in the B<TRUST SETTINGS> | |
697 | is currently being developed. It thus describes the intended behavior rather | |
698 | than the current behaviour. It is hoped that it will represent reality in | |
699 | OpenSSL 0.9.5 and later. | |
700 | ||
aba3e65f DSH |
701 | =head1 SEE ALSO |
702 | ||
bb075f88 RL |
703 | L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, |
704 | L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)> | |
aba3e65f DSH |
705 | |
706 | =cut |