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