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