]>
Commit | Line | Data |
---|---|---|
1 | =pod | |
2 | {- OpenSSL::safe::output_do_not_edit_headers(); -} | |
3 | ||
4 | =head1 NAME | |
5 | ||
6 | openssl-x509 - Certificate display and signing command | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<x509> | |
11 | [B<-help>] | |
12 | [B<-in> I<filename>|I<uri>] | |
13 | [B<-passin> I<arg>] | |
14 | [B<-new>] | |
15 | [B<-x509toreq>] | |
16 | [B<-req>] | |
17 | [B<-copy_extensions> I<arg>] | |
18 | [B<-inform> B<DER>|B<PEM>] | |
19 | [B<-vfyopt> I<nm>:I<v>] | |
20 | [B<-key> I<filename>|I<uri>] | |
21 | [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>] | |
22 | [B<-signkey> I<filename>|I<uri>] | |
23 | [B<-out> I<filename>] | |
24 | [B<-outform> B<DER>|B<PEM>] | |
25 | [B<-nocert>] | |
26 | [B<-noout>] | |
27 | [B<-dateopt>] | |
28 | [B<-text>] | |
29 | [B<-certopt> I<option>] | |
30 | [B<-fingerprint>] | |
31 | [B<-alias>] | |
32 | [B<-serial>] | |
33 | [B<-startdate>] | |
34 | [B<-enddate>] | |
35 | [B<-dates>] | |
36 | [B<-subject>] | |
37 | [B<-issuer>] | |
38 | {- $OpenSSL::safe::opt_name_synopsis -} | |
39 | [B<-email>] | |
40 | [B<-hash>] | |
41 | [B<-subject_hash>] | |
42 | [B<-subject_hash_old>] | |
43 | [B<-issuer_hash>] | |
44 | [B<-issuer_hash_old>] | |
45 | [B<-ext> I<extensions>] | |
46 | [B<-ocspid>] | |
47 | [B<-ocsp_uri>] | |
48 | [B<-purpose>] | |
49 | [B<-pubkey>] | |
50 | [B<-modulus>] | |
51 | [B<-checkend> I<num>] | |
52 | [B<-checkhost> I<host>] | |
53 | [B<-checkemail> I<host>] | |
54 | [B<-checkip> I<ipaddr>] | |
55 | [B<-set_serial> I<n>] | |
56 | [B<-next_serial>] | |
57 | [B<-not_before> I<date>] | |
58 | [B<-not_after> I<date>] | |
59 | [B<-days> I<arg>] | |
60 | [B<-preserve_dates>] | |
61 | [B<-set_issuer> I<arg>] | |
62 | [B<-set_subject> I<arg>] | |
63 | [B<-subj> I<arg>] | |
64 | [B<-force_pubkey> I<filename>] | |
65 | [B<-clrext>] | |
66 | [B<-extfile> I<filename>] | |
67 | [B<-extensions> I<section>] | |
68 | [B<-sigopt> I<nm>:I<v>] | |
69 | [B<-badsig>] | |
70 | [B<-I<digest>>] | |
71 | [B<-CA> I<filename>|I<uri>] | |
72 | [B<-CAform> B<DER>|B<PEM>|B<P12>] | |
73 | [B<-CAkey> I<filename>|I<uri>] | |
74 | [B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>] | |
75 | [B<-CAserial> I<filename>] | |
76 | [B<-CAcreateserial>] | |
77 | [B<-trustout>] | |
78 | [B<-setalias> I<arg>] | |
79 | [B<-clrtrust>] | |
80 | [B<-addtrust> I<arg>] | |
81 | [B<-clrreject>] | |
82 | [B<-addreject> I<arg>] | |
83 | {- $OpenSSL::safe::opt_r_synopsis -} | |
84 | {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} | |
85 | ||
86 | =head1 DESCRIPTION | |
87 | ||
88 | This command is a multi-purposes certificate handling command. | |
89 | It can be used to print certificate information, | |
90 | convert certificates to various forms, edit certificate trust settings, | |
91 | generate certificates from scratch or from certification requests | |
92 | and then self-signing them or signing them like a "micro CA". | |
93 | ||
94 | Generated certificates bear X.509 version 3. | |
95 | Unless specified otherwise, | |
96 | key identifier extensions are included as described in L<x509v3_config(5)>. | |
97 | ||
98 | Since there are a large number of options they will split up into | |
99 | various sections. | |
100 | ||
101 | =head1 OPTIONS | |
102 | ||
103 | =head2 Input, Output, and General Purpose Options | |
104 | ||
105 | =over 4 | |
106 | ||
107 | =item B<-help> | |
108 | ||
109 | Print out a usage message. | |
110 | ||
111 | =item B<-in> I<filename>|I<uri> | |
112 | ||
113 | This specifies the input to read a certificate from | |
114 | or the input file for reading a certificate request if the B<-req> flag is used. | |
115 | In both cases this defaults to standard input. | |
116 | ||
117 | This option cannot be combined with the B<-new> flag. | |
118 | ||
119 | =item B<-passin> I<arg> | |
120 | ||
121 | The key and certificate file password source. | |
122 | For more information about the format of I<arg> | |
123 | see L<openssl-passphrase-options(1)>. | |
124 | ||
125 | =item B<-new> | |
126 | ||
127 | Generate a certificate from scratch, not using an input certificate | |
128 | or certificate request. | |
129 | So this excludes the B<-in> and B<-req> options. | |
130 | Instead, the B<-set_subject> option needs to be given. | |
131 | The public key to include can be given with the B<-force_pubkey> option | |
132 | and defaults to the key given with the B<-key> (or B<-signkey>) option, | |
133 | which implies self-signature. | |
134 | ||
135 | =item B<-x509toreq> | |
136 | ||
137 | Output a PKCS#10 certificate request (rather than a certificate). | |
138 | The B<-key> (or B<-signkey>) option must be used to provide the private key for | |
139 | self-signing; the corresponding public key is placed in the subjectPKInfo field. | |
140 | ||
141 | X.509 extensions included in a certificate input are not copied by default. | |
142 | X.509 extensions to be added can be specified using the B<-extfile> option. | |
143 | ||
144 | =item B<-req> | |
145 | ||
146 | By default a certificate is expected on input. | |
147 | With this option a PKCS#10 certificate request is expected instead, | |
148 | which must be correctly self-signed. | |
149 | ||
150 | X.509 extensions included in the request are not copied by default. | |
151 | X.509 extensions to be added can be specified using the B<-extfile> option. | |
152 | ||
153 | =item B<-copy_extensions> I<arg> | |
154 | ||
155 | Determines how to handle X.509 extensions | |
156 | when converting from a certificate to a request using the B<-x509toreq> option | |
157 | or converting from a request to a certificate using the B<-req> option. | |
158 | If I<arg> is B<none> or this option is not present then extensions are ignored. | |
159 | If I<arg> is B<copy> or B<copyall> then all extensions are copied, | |
160 | except that subject identifier and authority key identifier extensions | |
161 | are not taken over when producing a certificate request. | |
162 | ||
163 | The B<-ext> option can be used to further restrict which extensions to copy. | |
164 | ||
165 | =item B<-inform> B<DER>|B<PEM> | |
166 | ||
167 | The input file format to use; by default PEM is tried first. | |
168 | See L<openssl-format-options(1)> for details. | |
169 | ||
170 | =item B<-vfyopt> I<nm>:I<v> | |
171 | ||
172 | Pass options to the signature algorithm during verify operations. | |
173 | Names and values of these options are algorithm-specific. | |
174 | ||
175 | =item B<-key> I<filename>|I<uri> | |
176 | ||
177 | This option provides the private key for signing a new certificate or | |
178 | certificate request. | |
179 | Unless B<-force_pubkey> is given, the corresponding public key is placed in | |
180 | the new certificate or certificate request, resulting in a self-signature. | |
181 | ||
182 | This option cannot be used in conjunction with the B<-CA> option. | |
183 | ||
184 | It sets the issuer name to the subject name (i.e., makes it self-issued). | |
185 | Unless the B<-preserve_dates> option is supplied, | |
186 | it sets the validity start date to the current time | |
187 | and the end date to a value determined by the B<-days> option. | |
188 | Start date and end date can also be explicitly supplied with options | |
189 | B<-not_before> and B<-not_after>. | |
190 | ||
191 | =item B<-signkey> I<filename>|I<uri> | |
192 | ||
193 | This option is an alias of B<-key>. | |
194 | ||
195 | =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE> | |
196 | ||
197 | The key input format; unspecified by default. | |
198 | See L<openssl-format-options(1)> for details. | |
199 | ||
200 | =item B<-out> I<filename> | |
201 | ||
202 | This specifies the output filename to write to or standard output by default. | |
203 | ||
204 | =item B<-outform> B<DER>|B<PEM> | |
205 | ||
206 | The output format; the default is B<PEM>. | |
207 | See L<openssl-format-options(1)> for details. | |
208 | ||
209 | =item B<-nocert> | |
210 | ||
211 | Do not output a certificate (except for printing as requested by below options). | |
212 | ||
213 | =item B<-noout> | |
214 | ||
215 | This option prevents output except for printing as requested by below options. | |
216 | ||
217 | =back | |
218 | ||
219 | =head2 Certificate Printing Options | |
220 | ||
221 | Note: the B<-alias> and B<-purpose> options are also printing options | |
222 | but are described in the L</Trust Settings> section. | |
223 | ||
224 | =over 4 | |
225 | ||
226 | =item B<-dateopt> | |
227 | ||
228 | Specify the date output format. Values are: rfc_822 and iso_8601. | |
229 | Defaults to rfc_822. | |
230 | ||
231 | =item B<-text> | |
232 | ||
233 | Prints out the certificate in text form. Full details are printed including the | |
234 | public key, signature algorithms, issuer and subject names, serial number | |
235 | any extensions present and any trust settings. | |
236 | ||
237 | =item B<-certopt> I<option> | |
238 | ||
239 | Customise the print format used with B<-text>. The I<option> argument | |
240 | can be a single option or multiple options separated by commas. | |
241 | The B<-certopt> switch may be also be used more than once to set multiple | |
242 | options. See the L</Text Printing Flags> section for more information. | |
243 | ||
244 | =item B<-fingerprint> | |
245 | ||
246 | Calculates and prints the digest of the DER encoded version of the entire | |
247 | certificate (see digest options). | |
248 | This is commonly called a "fingerprint". Because of the nature of message | |
249 | digests, the fingerprint of a certificate is unique to that certificate and | |
250 | two certificates with the same fingerprint can be considered to be the same. | |
251 | ||
252 | =item B<-alias> | |
253 | ||
254 | Prints the certificate "alias" (nickname), if any. | |
255 | ||
256 | =item B<-serial> | |
257 | ||
258 | Prints the certificate serial number. | |
259 | ||
260 | =item B<-startdate> | |
261 | ||
262 | Prints out the start date of the certificate, that is the notBefore date. | |
263 | ||
264 | =item B<-enddate> | |
265 | ||
266 | Prints out the expiry date of the certificate, that is the notAfter date. | |
267 | ||
268 | =item B<-dates> | |
269 | ||
270 | Prints out the start and expiry dates of a certificate. | |
271 | ||
272 | =item B<-subject> | |
273 | ||
274 | Prints the subject name. | |
275 | ||
276 | =item B<-issuer> | |
277 | ||
278 | Prints the issuer name. | |
279 | ||
280 | {- $OpenSSL::safe::opt_name_item -} | |
281 | ||
282 | =item B<-email> | |
283 | ||
284 | Prints the email address(es) if any. | |
285 | ||
286 | =item B<-hash> | |
287 | ||
288 | Synonym for "-subject_hash" for backward compatibility reasons. | |
289 | ||
290 | =item B<-subject_hash> | |
291 | ||
292 | Prints the "hash" of the certificate subject name. This is used in OpenSSL to | |
293 | form an index to allow certificates in a directory to be looked up by subject | |
294 | name. | |
295 | ||
296 | =item B<-subject_hash_old> | |
297 | ||
298 | Prints the "hash" of the certificate subject name using the older algorithm | |
299 | as used by OpenSSL before version 1.0.0. | |
300 | ||
301 | =item B<-issuer_hash> | |
302 | ||
303 | Prints the "hash" of the certificate issuer name. | |
304 | ||
305 | =item B<-issuer_hash_old> | |
306 | ||
307 | Prints the "hash" of the certificate issuer name using the older algorithm | |
308 | as used by OpenSSL before version 1.0.0. | |
309 | ||
310 | =item B<-ext> I<extensions> | |
311 | ||
312 | Prints out the certificate extensions in text form. | |
313 | Can also be used to restrict which extensions to copy. | |
314 | Extensions are specified | |
315 | with a comma separated string, e.g., "subjectAltName, subjectKeyIdentifier". | |
316 | See the L<x509v3_config(5)> manual page for the extension names. | |
317 | ||
318 | =item B<-ocspid> | |
319 | ||
320 | Prints the OCSP hash values for the subject name and public key. | |
321 | ||
322 | =item B<-ocsp_uri> | |
323 | ||
324 | Prints the OCSP responder address(es) if any. | |
325 | ||
326 | =item B<-purpose> | |
327 | ||
328 | This option performs tests on the certificate extensions and outputs | |
329 | the results. For a more complete description see | |
330 | L<openssl-verification-options(1)/Certificate Extensions>. | |
331 | ||
332 | =item B<-pubkey> | |
333 | ||
334 | Prints the certificate's SubjectPublicKeyInfo block in PEM format. | |
335 | ||
336 | =item B<-modulus> | |
337 | ||
338 | This option prints out the value of the modulus of the public key | |
339 | contained in the certificate. | |
340 | ||
341 | =back | |
342 | ||
343 | =head2 Certificate Checking Options | |
344 | ||
345 | =over 4 | |
346 | ||
347 | =item B<-checkend> I<arg> | |
348 | ||
349 | Checks if the certificate expires within the next I<arg> seconds and exits | |
350 | nonzero if yes it will expire or zero if not. | |
351 | ||
352 | =item B<-checkhost> I<host> | |
353 | ||
354 | Check that the certificate matches the specified host. | |
355 | ||
356 | =item B<-checkemail> I<email> | |
357 | ||
358 | Check that the certificate matches the specified email address. | |
359 | ||
360 | =item B<-checkip> I<ipaddr> | |
361 | ||
362 | Check that the certificate matches the specified IP address. | |
363 | ||
364 | =back | |
365 | ||
366 | =head2 Certificate Output Options | |
367 | ||
368 | =over 4 | |
369 | ||
370 | =item B<-set_serial> I<n> | |
371 | ||
372 | Specifies the serial number to use. | |
373 | This option can be used with the B<-key>, B<-signkey>, or B<-CA> options. | |
374 | If used in conjunction with the B<-CA> option | |
375 | the serial number file (as specified by the B<-CAserial> option) is not used. | |
376 | ||
377 | The serial number can be decimal or hex (if preceded by C<0x>). | |
378 | ||
379 | =item B<-next_serial> | |
380 | ||
381 | Set the serial to be one more than the number in the certificate. | |
382 | ||
383 | =item B<-not_before> I<date> | |
384 | ||
385 | This allows the start date to be explicitly set. The format of the | |
386 | date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or | |
387 | YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In | |
388 | both formats, seconds SS and timezone Z must be present. | |
389 | Alternatively, you can also use "today". | |
390 | ||
391 | Cannot be used together with the B<-preserve_dates> option. | |
392 | ||
393 | =item B<-not_after> I<date> | |
394 | ||
395 | This allows the expiry date to be explicitly set. The format of the | |
396 | date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or | |
397 | YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In | |
398 | both formats, seconds SS and timezone Z must be present. | |
399 | Alternatively, you can also use "today". | |
400 | ||
401 | Cannot be used together with the B<-preserve_dates> option. | |
402 | This overrides the option B<-days>. | |
403 | ||
404 | =item B<-days> I<arg> | |
405 | ||
406 | Specifies the number of days from today until a newly generated certificate expires. | |
407 | The default is 30. | |
408 | ||
409 | Cannot be used together with the option B<-preserve_dates>. | |
410 | If option B<-not_after> is set, the explicit expiry date takes precedence. | |
411 | ||
412 | =item B<-preserve_dates> | |
413 | ||
414 | When signing a certificate, preserve "notBefore" and "notAfter" dates of any | |
415 | input certificate instead of adjusting them to current time and duration. | |
416 | Cannot be used together with the options B<-days>, B<-not_before> and B<-not_after>. | |
417 | ||
418 | =item B<-set_issuer> I<arg> | |
419 | ||
420 | When a certificate is created set its issuer name to the given value. | |
421 | ||
422 | See B<-set_subject> on how the arg must be formatted. | |
423 | ||
424 | =item B<-set_subject> I<arg> | |
425 | ||
426 | When a certificate is created set its subject name to the given value. | |
427 | When the certificate is self-signed the issuer name is set to the same value, | |
428 | unless the B<-set_issuer> option is given. | |
429 | ||
430 | The arg must be formatted as C</type0=value0/type1=value1/type2=...>. | |
431 | Special characters may be escaped by C<\> (backslash), whitespace is retained. | |
432 | Empty values are permitted, but the corresponding type will not be included | |
433 | in the certificate. | |
434 | Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN). | |
435 | Multi-valued RDNs can be formed by placing a C<+> character instead of a C</> | |
436 | between the AttributeValueAssertions (AVAs) that specify the members of the set. | |
437 | Example: | |
438 | ||
439 | C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> | |
440 | ||
441 | This option can be used with the B<-new> and B<-force_pubkey> options to create | |
442 | a new certificate without providing an input certificate or certificate request. | |
443 | ||
444 | =item B<-subj> I<arg> | |
445 | ||
446 | This option is an alias of B<-set_subject>. | |
447 | ||
448 | =item B<-force_pubkey> I<filename> | |
449 | ||
450 | When a new certificate or certificate request is created | |
451 | set its public key to the given key | |
452 | instead of the key contained in the input | |
453 | or given with the B<-key> (or B<-signkey>) option. | |
454 | If the input contains no public key but a private key, its public part is used. | |
455 | ||
456 | This option can be used in conjunction with b<-new> and B<-set_subject> | |
457 | to directly generate a certificate containing any desired public key. | |
458 | ||
459 | This option is also useful for creating self-issued certificates that are not | |
460 | self-signed, for instance when the key cannot be used for signing, such as DH. | |
461 | ||
462 | =item B<-clrext> | |
463 | ||
464 | When transforming a certificate to a new certificate | |
465 | by default all certificate extensions are retained. | |
466 | ||
467 | When transforming a certificate or certificate request, | |
468 | the B<-clrext> option prevents taking over any extensions from the source. | |
469 | In any case, when producing a certificate request, | |
470 | neither subject identifier nor authority key identifier extensions are included. | |
471 | ||
472 | =item B<-extfile> I<filename> | |
473 | ||
474 | Configuration file containing certificate and request X.509 extensions to add. | |
475 | ||
476 | =item B<-extensions> I<section> | |
477 | ||
478 | The section in the extfile to add X.509 extensions from. | |
479 | If this option is not | |
480 | specified then the extensions should either be contained in the unnamed | |
481 | (default) section or the default section should contain a variable called | |
482 | "extensions" which contains the section to use. | |
483 | ||
484 | See the L<x509v3_config(5)> manual page for details of the | |
485 | extension section format. | |
486 | ||
487 | Unless specified otherwise, | |
488 | key identifier extensions are included as described in L<x509v3_config(5)>. | |
489 | ||
490 | =item B<-sigopt> I<nm>:I<v> | |
491 | ||
492 | Pass options to the signature algorithm during sign operations. | |
493 | This option may be given multiple times. | |
494 | Names and values provided using this option are algorithm-specific. | |
495 | ||
496 | =item B<-badsig> | |
497 | ||
498 | Corrupt the signature before writing it; this can be useful | |
499 | for testing. | |
500 | ||
501 | =item B<-I<digest>> | |
502 | ||
503 | The digest to use. | |
504 | This affects any signing or printing option that uses a message | |
505 | digest, such as the B<-fingerprint>, B<-key>, and B<-CA> options. | |
506 | Any digest supported by the L<openssl-dgst(1)> command can be used. | |
507 | If not specified then SHA1 is used with B<-fingerprint> or | |
508 | the default digest for the signing algorithm is used, typically SHA256. | |
509 | ||
510 | =back | |
511 | ||
512 | =head2 Micro-CA Options | |
513 | ||
514 | =over 4 | |
515 | ||
516 | =item B<-CA> I<filename>|I<uri> | |
517 | ||
518 | Specifies the "CA" certificate to be used for signing. | |
519 | When present, this behaves like a "micro CA" as follows: | |
520 | The subject name of the "CA" certificate is placed as issuer name in the new | |
521 | certificate, which is then signed using the "CA" key given as detailed below. | |
522 | ||
523 | This option cannot be used in conjunction with B<-key> (or B<-signkey>). | |
524 | This option is normally combined with the B<-req> option referencing a CSR. | |
525 | Without the B<-req> option the input must be an existing certificate | |
526 | unless the B<-new> option is given, which generates a certificate from scratch. | |
527 | ||
528 | =item B<-CAform> B<DER>|B<PEM>|B<P12>, | |
529 | ||
530 | The format for the CA certificate; unspecified by default. | |
531 | See L<openssl-format-options(1)> for details. | |
532 | ||
533 | =item B<-CAkey> I<filename>|I<uri> | |
534 | ||
535 | Sets the CA private key to sign a certificate with. | |
536 | The private key must match the public key of the certificate given with B<-CA>. | |
537 | If this option is not provided then the key must be present in the B<-CA> input. | |
538 | ||
539 | =item B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE> | |
540 | ||
541 | The format for the CA key; unspecified by default. | |
542 | See L<openssl-format-options(1)> for details. | |
543 | ||
544 | =item B<-CAserial> I<filename> | |
545 | ||
546 | Sets the CA serial number file to use. | |
547 | ||
548 | When creating a certificate with this option and with the B<-CA> option, | |
549 | the certificate serial number is stored in the given file. | |
550 | This file consists of one line containing | |
551 | an even number of hex digits with the serial number used last time. | |
552 | After reading this number, it is incremented and used, and the file is updated. | |
553 | ||
554 | The default filename consists of the CA certificate file base name with | |
555 | F<.srl> appended. For example if the CA certificate file is called | |
556 | F<mycacert.pem> it expects to find a serial number file called | |
557 | F<mycacert.srl>. | |
558 | ||
559 | If the B<-CA> option is specified and neither <-CAserial> or <-CAcreateserial> | |
560 | is given and the default serial number file does not exist, | |
561 | a random number is generated; this is the recommended practice. | |
562 | ||
563 | =item B<-CAcreateserial> | |
564 | ||
565 | With this option and the B<-CA> option | |
566 | the CA serial number file is created if it does not exist. | |
567 | A random number is generated, used for the certificate, | |
568 | and saved into the serial number file determined as described above. | |
569 | ||
570 | =back | |
571 | ||
572 | =head2 Trust Settings | |
573 | ||
574 | A B<trusted certificate> is an ordinary certificate which has several | |
575 | additional pieces of information attached to it such as the permitted | |
576 | and prohibited uses of the certificate and possibly an "alias" (nickname). | |
577 | ||
578 | Normally when a certificate is being verified at least one certificate | |
579 | must be "trusted". By default a trusted certificate must be stored | |
580 | locally and must be a root CA: any certificate chain ending in this CA | |
581 | is then usable for any purpose. | |
582 | ||
583 | Trust settings currently are only used with a root CA. | |
584 | They allow a finer control over the purposes the root CA can be used for. | |
585 | For example, a CA may be trusted for SSL client but not SSL server use. | |
586 | ||
587 | See L<openssl-verification-options(1)> for more information | |
588 | on the meaning of trust settings. | |
589 | ||
590 | Future versions of OpenSSL will recognize trust settings on any | |
591 | certificate: not just root CAs. | |
592 | ||
593 | =over 4 | |
594 | ||
595 | =item B<-trustout> | |
596 | ||
597 | Mark any certificate PEM output as <trusted> certificate rather than ordinary. | |
598 | An ordinary or trusted certificate can be input but by default an ordinary | |
599 | certificate is output and any trust settings are discarded. | |
600 | With the B<-trustout> option a trusted certificate is output. A trusted | |
601 | certificate is automatically output if any trust settings are modified. | |
602 | ||
603 | =item B<-setalias> I<arg> | |
604 | ||
605 | Sets the "alias" of the certificate. This will allow the certificate | |
606 | to be referred to using a nickname for example "Steve's Certificate". | |
607 | ||
608 | =item B<-clrtrust> | |
609 | ||
610 | Clears all the permitted or trusted uses of the certificate. | |
611 | ||
612 | =item B<-addtrust> I<arg> | |
613 | ||
614 | Adds a trusted certificate use. | |
615 | Any object name can be used here but currently only B<clientAuth>, | |
616 | B<serverAuth>, B<emailProtection>, and B<anyExtendedKeyUsage> are defined. | |
617 | As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or | |
618 | enables all purposes when trusted. | |
619 | Other OpenSSL applications may define additional uses. | |
620 | ||
621 | =item B<-clrreject> | |
622 | ||
623 | Clears all the prohibited or rejected uses of the certificate. | |
624 | ||
625 | =item B<-addreject> I<arg> | |
626 | ||
627 | Adds a prohibited trust anchor purpose. | |
628 | It accepts the same values as the B<-addtrust> option. | |
629 | ||
630 | =back | |
631 | ||
632 | =head2 Generic options | |
633 | ||
634 | =over 4 | |
635 | ||
636 | {- $OpenSSL::safe::opt_r_item -} | |
637 | ||
638 | {- $OpenSSL::safe::opt_engine_item -} | |
639 | ||
640 | {- $OpenSSL::safe::opt_provider_item -} | |
641 | ||
642 | =back | |
643 | ||
644 | =head2 Text Printing Flags | |
645 | ||
646 | As well as customising the name printing format, it is also possible to | |
647 | customise the actual fields printed using the B<certopt> option when | |
648 | the B<text> option is present. The default behaviour is to print all fields. | |
649 | ||
650 | =over 4 | |
651 | ||
652 | =item B<compatible> | |
653 | ||
654 | Use the old format. This is equivalent to specifying no printing options at all. | |
655 | ||
656 | =item B<no_header> | |
657 | ||
658 | Don't print header information: that is the lines saying "Certificate" | |
659 | and "Data". | |
660 | ||
661 | =item B<no_version> | |
662 | ||
663 | Don't print out the version number. | |
664 | ||
665 | =item B<no_serial> | |
666 | ||
667 | Don't print out the serial number. | |
668 | ||
669 | =item B<no_signame> | |
670 | ||
671 | Don't print out the signature algorithm used. | |
672 | ||
673 | =item B<no_validity> | |
674 | ||
675 | Don't print the validity, that is the B<notBefore> and B<notAfter> fields. | |
676 | ||
677 | =item B<no_subject> | |
678 | ||
679 | Don't print out the subject name. | |
680 | ||
681 | =item B<no_issuer> | |
682 | ||
683 | Don't print out the issuer name. | |
684 | ||
685 | =item B<no_pubkey> | |
686 | ||
687 | Don't print out the public key. | |
688 | ||
689 | =item B<no_sigdump> | |
690 | ||
691 | Don't give a hexadecimal dump of the certificate signature. | |
692 | ||
693 | =item B<no_aux> | |
694 | ||
695 | Don't print out certificate trust information. | |
696 | ||
697 | =item B<no_extensions> | |
698 | ||
699 | Don't print out any X509V3 extensions. | |
700 | ||
701 | =item B<ext_default> | |
702 | ||
703 | Retain default extension behaviour: attempt to print out unsupported | |
704 | certificate extensions. | |
705 | ||
706 | =item B<ext_error> | |
707 | ||
708 | Print an error message for unsupported certificate extensions. | |
709 | ||
710 | =item B<ext_parse> | |
711 | ||
712 | ASN1 parse unsupported extensions. | |
713 | ||
714 | =item B<ext_dump> | |
715 | ||
716 | Hex dump unsupported extensions. | |
717 | ||
718 | =item B<ca_default> | |
719 | ||
720 | The value used by L<openssl-ca(1)>, equivalent to B<no_issuer>, B<no_pubkey>, | |
721 | B<no_header>, and B<no_version>. | |
722 | ||
723 | =back | |
724 | ||
725 | =head1 EXAMPLES | |
726 | ||
727 | Note: in these examples the '\' means the example should be all on one | |
728 | line. | |
729 | ||
730 | Print the contents of a certificate: | |
731 | ||
732 | openssl x509 -in cert.pem -noout -text | |
733 | ||
734 | Print the "Subject Alternative Name" extension of a certificate: | |
735 | ||
736 | openssl x509 -in cert.pem -noout -ext subjectAltName | |
737 | ||
738 | Print more extensions of a certificate: | |
739 | ||
740 | openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType | |
741 | ||
742 | Print the certificate serial number: | |
743 | ||
744 | openssl x509 -in cert.pem -noout -serial | |
745 | ||
746 | Print the certificate subject name: | |
747 | ||
748 | openssl x509 -in cert.pem -noout -subject | |
749 | ||
750 | Print the certificate subject name in RFC2253 form: | |
751 | ||
752 | openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 | |
753 | ||
754 | Print the certificate subject name in oneline form on a terminal | |
755 | supporting UTF8: | |
756 | ||
757 | openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb | |
758 | ||
759 | Print the certificate SHA1 fingerprint: | |
760 | ||
761 | openssl x509 -sha1 -in cert.pem -noout -fingerprint | |
762 | ||
763 | Convert a certificate from PEM to DER format: | |
764 | ||
765 | openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER | |
766 | ||
767 | Convert a certificate to a certificate request: | |
768 | ||
769 | openssl x509 -x509toreq -in cert.pem -out req.pem -key key.pem | |
770 | ||
771 | Convert a certificate request into a self-signed certificate using | |
772 | extensions for a CA: | |
773 | ||
774 | openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \ | |
775 | -key key.pem -out cacert.pem | |
776 | ||
777 | Sign a certificate request using the CA certificate above and add user | |
778 | certificate extensions: | |
779 | ||
780 | openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \ | |
781 | -CA cacert.pem -CAkey key.pem -CAcreateserial | |
782 | ||
783 | Set a certificate to be trusted for SSL client use and change set its alias to | |
784 | "Steve's Class 1 CA" | |
785 | ||
786 | openssl x509 -in cert.pem -addtrust clientAuth \ | |
787 | -setalias "Steve's Class 1 CA" -out trust.pem | |
788 | ||
789 | =head1 NOTES | |
790 | ||
791 | The conversion to UTF8 format used with the name options assumes that | |
792 | T61Strings use the ISO8859-1 character set. This is wrong but Netscape | |
793 | and MSIE do this as do many certificates. So although this is incorrect | |
794 | it is more likely to print the majority of certificates correctly. | |
795 | ||
796 | The B<-email> option searches the subject name and the subject alternative | |
797 | name extension. Only unique email addresses will be printed out: it will | |
798 | not print the same address more than once. | |
799 | ||
800 | =head1 BUGS | |
801 | ||
802 | It is possible to produce invalid certificates or requests by specifying the | |
803 | wrong private key, using unsuitable X.509 extensions, | |
804 | or using inconsistent options in some cases: these should be checked. | |
805 | ||
806 | There should be options to explicitly set such things as start and end | |
807 | dates rather than an offset from the current time. | |
808 | ||
809 | =head1 SEE ALSO | |
810 | ||
811 | L<openssl(1)>, | |
812 | L<openssl-req(1)>, | |
813 | L<openssl-ca(1)>, | |
814 | L<openssl-genrsa(1)>, | |
815 | L<openssl-gendsa(1)>, | |
816 | L<openssl-verify(1)>, | |
817 | L<x509v3_config(5)> | |
818 | ||
819 | =head1 HISTORY | |
820 | ||
821 | The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options | |
822 | before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding | |
823 | of the distinguished name. In OpenSSL 1.0.0 and later it is based on a canonical | |
824 | version of the DN using SHA1. This means that any directories using the old | |
825 | form must have their links rebuilt using L<openssl-rehash(1)> or similar. | |
826 | ||
827 | The B<-signkey> option has been renamed to B<-key> in OpenSSL 3.0, | |
828 | keeping the old name as an alias. | |
829 | ||
830 | The B<-engine> option was deprecated in OpenSSL 3.0. | |
831 | ||
832 | The B<-C> option was removed in OpenSSL 3.0. | |
833 | ||
834 | Since OpenSSL 3.2, generated certificates bear X.509 version 3, | |
835 | and key identifier extensions are included by default. | |
836 | ||
837 | =head1 COPYRIGHT | |
838 | ||
839 | Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved. | |
840 | ||
841 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
842 | this file except in compliance with the License. You can obtain a copy | |
843 | in the file LICENSE in the source distribution or at | |
844 | L<https://www.openssl.org/source/license.html>. | |
845 | ||
846 | =cut |