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