2 {- OpenSSL::safe::output_do_not_edit_headers(); -}
6 openssl-x509 - Certificate display and signing command
12 [B<-in> I<filename>|I<uri>]
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>]
24 [B<-outform> B<DER>|B<PEM>]
29 [B<-certopt> I<option>]
38 {- $OpenSSL::safe::opt_name_synopsis -}
42 [B<-subject_hash_old>]
45 [B<-ext> I<extensions>]
52 [B<-checkhost> I<host>]
53 [B<-checkemail> I<host>]
54 [B<-checkip> I<ipaddr>]
60 [B<-force_pubkey> I<filename>]
62 [B<-extfile> I<filename>]
63 [B<-extensions> I<section>]
64 [B<-sigopt> I<nm>:I<v>]
67 [B<-CA> I<filename>|I<uri>]
68 [B<-CAform> B<DER>|B<PEM>|B<P12>]
69 [B<-CAkey> I<filename>|I<uri>]
70 [B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
71 [B<-CAserial> I<filename>]
78 [B<-addreject> I<arg>]
79 {- $OpenSSL::safe::opt_r_synopsis -}
80 {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
84 This command is a multi-purposes certificate handling command.
85 It can be used to print certificate information,
86 convert certificates to various forms, edit certificate trust settings,
87 generate certificates from scratch or from certification requests
88 and then self-signing them or signing them like a "micro CA".
90 Generated certificates bear X.509 version 3.
91 Unless specified otherwise,
92 key identifier extensions are included as described in L<x509v3_config(5)>.
94 Since there are a large number of options they will split up into
99 =head2 Input, Output, and General Purpose Options
105 Print out a usage message.
107 =item B<-in> I<filename>|I<uri>
109 This specifies the input to read a certificate from
110 or the input file for reading a certificate request if the B<-req> flag is used.
111 In both cases this defaults to standard input.
113 This option cannot be combined with the B<-new> flag.
115 =item B<-passin> I<arg>
117 The key and certificate file password source.
118 For more information about the format of I<arg>
119 see L<openssl-passphrase-options(1)>.
123 Generate a certificate from scratch, not using an input certificate
124 or certificate request.
125 So this excludes the B<-in> and B<-req> options.
126 Instead, the B<-subj> option needs to be given.
127 The public key to include can be given with the B<-force_pubkey> option
128 and defaults to the key given with the B<-key> (or B<-signkey>) option,
129 which implies self-signature.
133 Output a PKCS#10 certificate request (rather than a certificate).
134 The B<-key> (or B<-signkey>) option must be used to provide the private key for
135 self-signing; the corresponding public key is placed in the subjectPKInfo field.
137 X.509 extensions included in a certificate input are not copied by default.
138 X.509 extensions to be added can be specified using the B<-extfile> option.
142 By default a certificate is expected on input.
143 With this option a PKCS#10 certificate request is expected instead,
144 which must be correctly self-signed.
146 X.509 extensions included in the request are not copied by default.
147 X.509 extensions to be added can be specified using the B<-extfile> option.
149 =item B<-copy_extensions> I<arg>
151 Determines how to handle X.509 extensions
152 when converting from a certificate to a request using the B<-x509toreq> option
153 or converting from a request to a certificate using the B<-req> option.
154 If I<arg> is B<none> or this option is not present then extensions are ignored.
155 If I<arg> is B<copy> or B<copyall> then all extensions are copied,
156 except that subject identifier and authority key identifier extensions
157 are not taken over when producing a certificate request.
159 The B<-ext> option can be used to further restrict which extensions to copy.
161 =item B<-inform> B<DER>|B<PEM>
163 The input file format to use; by default PEM is tried first.
164 See L<openssl-format-options(1)> for details.
166 =item B<-vfyopt> I<nm>:I<v>
168 Pass options to the signature algorithm during verify operations.
169 Names and values of these options are algorithm-specific.
171 =item B<-key> I<filename>|I<uri>
173 This option provides the private key for signing a new certificate or
175 Unless B<-force_pubkey> is given, the corresponding public key is placed in
176 the new certificate or certificate request, resulting in a self-signature.
178 This option cannot be used in conjunction with the B<-CA> option.
180 It sets the issuer name to the subject name (i.e., makes it self-issued).
181 Unless the B<-preserve_dates> option is supplied,
182 it sets the validity start date to the current time
183 and the end date to a value determined by the B<-days> option.
185 =item B<-signkey> I<filename>|I<uri>
187 This option is an alias of B<-key>.
189 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
191 The key input format; unspecified by default.
192 See L<openssl-format-options(1)> for details.
194 =item B<-out> I<filename>
196 This specifies the output filename to write to or standard output by default.
198 =item B<-outform> B<DER>|B<PEM>
200 The output format; the default is B<PEM>.
201 See L<openssl-format-options(1)> for details.
205 Do not output a certificate (except for printing as requested by below options).
209 This option prevents output except for printing as requested by below options.
213 =head2 Certificate Printing Options
215 Note: the B<-alias> and B<-purpose> options are also printing options
216 but are described in the L</Trust Settings> section.
222 Specify the date output format. Values are: rfc_822 and iso_8601.
227 Prints out the certificate in text form. Full details are printed including the
228 public key, signature algorithms, issuer and subject names, serial number
229 any extensions present and any trust settings.
231 =item B<-certopt> I<option>
233 Customise the print format used with B<-text>. The I<option> argument
234 can be a single option or multiple options separated by commas.
235 The B<-certopt> switch may be also be used more than once to set multiple
236 options. See the L</Text Printing Flags> section for more information.
238 =item B<-fingerprint>
240 Calculates and prints the digest of the DER encoded version of the entire
241 certificate (see digest options).
242 This is commonly called a "fingerprint". Because of the nature of message
243 digests, the fingerprint of a certificate is unique to that certificate and
244 two certificates with the same fingerprint can be considered to be the same.
248 Prints the certificate "alias" (nickname), if any.
252 Prints the certificate serial number.
256 Prints out the start date of the certificate, that is the notBefore date.
260 Prints out the expiry date of the certificate, that is the notAfter date.
264 Prints out the start and expiry dates of a certificate.
268 Prints the subject name.
272 Prints the issuer name.
274 {- $OpenSSL::safe::opt_name_item -}
278 Prints the email address(es) if any.
282 Synonym for "-subject_hash" for backward compatibility reasons.
284 =item B<-subject_hash>
286 Prints the "hash" of the certificate subject name. This is used in OpenSSL to
287 form an index to allow certificates in a directory to be looked up by subject
290 =item B<-subject_hash_old>
292 Prints the "hash" of the certificate subject name using the older algorithm
293 as used by OpenSSL before version 1.0.0.
295 =item B<-issuer_hash>
297 Prints the "hash" of the certificate issuer name.
299 =item B<-issuer_hash_old>
301 Prints the "hash" of the certificate issuer name using the older algorithm
302 as used by OpenSSL before version 1.0.0.
304 =item B<-ext> I<extensions>
306 Prints out the certificate extensions in text form.
307 Can also be used to restrict which extensions to copy.
308 Extensions are specified
309 with a comma separated string, e.g., "subjectAltName, subjectKeyIdentifier".
310 See the L<x509v3_config(5)> manual page for the extension names.
314 Prints the OCSP hash values for the subject name and public key.
318 Prints the OCSP responder address(es) if any.
322 This option performs tests on the certificate extensions and outputs
323 the results. For a more complete description see
324 L<openssl-verification-options(1)/Certificate Extensions>.
328 Prints the certificate's SubjectPublicKeyInfo block in PEM format.
332 This option prints out the value of the modulus of the public key
333 contained in the certificate.
337 =head2 Certificate Checking Options
341 =item B<-checkend> I<arg>
343 Checks if the certificate expires within the next I<arg> seconds and exits
344 nonzero if yes it will expire or zero if not.
346 =item B<-checkhost> I<host>
348 Check that the certificate matches the specified host.
350 =item B<-checkemail> I<email>
352 Check that the certificate matches the specified email address.
354 =item B<-checkip> I<ipaddr>
356 Check that the certificate matches the specified IP address.
360 =head2 Certificate Output Options
364 =item B<-set_serial> I<n>
366 Specifies the serial number to use.
367 This option can be used with the B<-key>, B<-signkey>, or B<-CA> options.
368 If used in conjunction with the B<-CA> option
369 the serial number file (as specified by the B<-CAserial> option) is not used.
371 The serial number can be decimal or hex (if preceded by C<0x>).
373 =item B<-next_serial>
375 Set the serial to be one more than the number in the certificate.
377 =item B<-days> I<arg>
379 Specifies the number of days until a newly generated certificate expires.
381 Cannot be used together with the B<-preserve_dates> option.
383 =item B<-preserve_dates>
385 When signing a certificate, preserve "notBefore" and "notAfter" dates of any
386 input certificate instead of adjusting them to current time and duration.
387 Cannot be used together with the B<-days> option.
389 =item B<-subj> I<arg>
391 When a certificate is created set its subject name to the given value.
392 When the certificate is self-signed the issuer name is set to the same value.
394 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
395 Special characters may be escaped by C<\> (backslash), whitespace is retained.
396 Empty values are permitted, but the corresponding type will not be included
398 Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
399 Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
400 between the AttributeValueAssertions (AVAs) that specify the members of the set.
403 C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
405 This option can be used with the B<-new> and B<-force_pubkey> options to create
406 a new certificate without providing an input certificate or certificate request.
408 =item B<-force_pubkey> I<filename>
410 When a new certificate or certificate request is created
411 set its public key to the given key
412 instead of the key contained in the input
413 or given with the B<-key> (or B<-signkey>) option.
414 If the input contains no public key but a private key, its public part is used.
416 This option can be used in conjunction with b<-new> and B<-subj>
417 to directly generate a certificate containing any desired public key.
419 This option is also useful for creating self-issued certificates that are not
420 self-signed, for instance when the key cannot be used for signing, such as DH.
424 When transforming a certificate to a new certificate
425 by default all certificate extensions are retained.
427 When transforming a certificate or certificate request,
428 the B<-clrext> option prevents taking over any extensions from the source.
429 In any case, when producing a certificate request,
430 neither subject identifier nor authority key identifier extensions are included.
432 =item B<-extfile> I<filename>
434 Configuration file containing certificate and request X.509 extensions to add.
436 =item B<-extensions> I<section>
438 The section in the extfile to add X.509 extensions from.
439 If this option is not
440 specified then the extensions should either be contained in the unnamed
441 (default) section or the default section should contain a variable called
442 "extensions" which contains the section to use.
444 See the L<x509v3_config(5)> manual page for details of the
445 extension section format.
447 Unless specified otherwise,
448 key identifier extensions are included as described in L<x509v3_config(5)>.
450 =item B<-sigopt> I<nm>:I<v>
452 Pass options to the signature algorithm during sign operations.
453 This option may be given multiple times.
454 Names and values provided using this option are algorithm-specific.
458 Corrupt the signature before writing it; this can be useful
464 This affects any signing or printing option that uses a message
465 digest, such as the B<-fingerprint>, B<-key>, and B<-CA> options.
466 Any digest supported by the L<openssl-dgst(1)> command can be used.
467 If not specified then SHA1 is used with B<-fingerprint> or
468 the default digest for the signing algorithm is used, typically SHA256.
472 =head2 Micro-CA Options
476 =item B<-CA> I<filename>|I<uri>
478 Specifies the "CA" certificate to be used for signing.
479 When present, this behaves like a "micro CA" as follows:
480 The subject name of the "CA" certificate is placed as issuer name in the new
481 certificate, which is then signed using the "CA" key given as detailed below.
483 This option cannot be used in conjunction with B<-key> (or B<-signkey>).
484 This option is normally combined with the B<-req> option referencing a CSR.
485 Without the B<-req> option the input must be an existing certificate
486 unless the B<-new> option is given, which generates a certificate from scratch.
488 =item B<-CAform> B<DER>|B<PEM>|B<P12>,
490 The format for the CA certificate; unspecified by default.
491 See L<openssl-format-options(1)> for details.
493 =item B<-CAkey> I<filename>|I<uri>
495 Sets the CA private key to sign a certificate with.
496 The private key must match the public key of the certificate given with B<-CA>.
497 If this option is not provided then the key must be present in the B<-CA> input.
499 =item B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
501 The format for the CA key; unspecified by default.
502 See L<openssl-format-options(1)> for details.
504 =item B<-CAserial> I<filename>
506 Sets the CA serial number file to use.
508 When creating a certificate with this option and with the B<-CA> option,
509 the certificate serial number is stored in the given file.
510 This file consists of one line containing
511 an even number of hex digits with the serial number used last time.
512 After reading this number, it is incremented and used, and the file is updated.
514 The default filename consists of the CA certificate file base name with
515 F<.srl> appended. For example if the CA certificate file is called
516 F<mycacert.pem> it expects to find a serial number file called
519 If the B<-CA> option is specified and neither <-CAserial> or <-CAcreateserial>
520 is given and the default serial number file does not exist,
521 a random number is generated; this is the recommended practice.
523 =item B<-CAcreateserial>
525 With this option and the B<-CA> option
526 the CA serial number file is created if it does not exist.
527 A random number is generated, used for the certificate,
528 and saved into the serial number file determined as described above.
532 =head2 Trust Settings
534 A B<trusted certificate> is an ordinary certificate which has several
535 additional pieces of information attached to it such as the permitted
536 and prohibited uses of the certificate and possibly an "alias" (nickname).
538 Normally when a certificate is being verified at least one certificate
539 must be "trusted". By default a trusted certificate must be stored
540 locally and must be a root CA: any certificate chain ending in this CA
541 is then usable for any purpose.
543 Trust settings currently are only used with a root CA.
544 They allow a finer control over the purposes the root CA can be used for.
545 For example, a CA may be trusted for SSL client but not SSL server use.
547 See L<openssl-verification-options(1)> for more information
548 on the meaning of trust settings.
550 Future versions of OpenSSL will recognize trust settings on any
551 certificate: not just root CAs.
557 Mark any certificate PEM output as <trusted> certificate rather than ordinary.
558 An ordinary or trusted certificate can be input but by default an ordinary
559 certificate is output and any trust settings are discarded.
560 With the B<-trustout> option a trusted certificate is output. A trusted
561 certificate is automatically output if any trust settings are modified.
563 =item B<-setalias> I<arg>
565 Sets the "alias" of the certificate. This will allow the certificate
566 to be referred to using a nickname for example "Steve's Certificate".
570 Clears all the permitted or trusted uses of the certificate.
572 =item B<-addtrust> I<arg>
574 Adds a trusted certificate use.
575 Any object name can be used here but currently only B<clientAuth>,
576 B<serverAuth>, B<emailProtection>, and B<anyExtendedKeyUsage> are defined.
577 As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
578 enables all purposes when trusted.
579 Other OpenSSL applications may define additional uses.
583 Clears all the prohibited or rejected uses of the certificate.
585 =item B<-addreject> I<arg>
587 Adds a prohibited trust anchor purpose.
588 It accepts the same values as the B<-addtrust> option.
592 =head2 Generic options
596 {- $OpenSSL::safe::opt_r_item -}
598 {- $OpenSSL::safe::opt_engine_item -}
600 {- $OpenSSL::safe::opt_provider_item -}
604 =head2 Text Printing Flags
606 As well as customising the name printing format, it is also possible to
607 customise the actual fields printed using the B<certopt> option when
608 the B<text> option is present. The default behaviour is to print all fields.
614 Use the old format. This is equivalent to specifying no printing options at all.
618 Don't print header information: that is the lines saying "Certificate"
623 Don't print out the version number.
627 Don't print out the serial number.
631 Don't print out the signature algorithm used.
635 Don't print the validity, that is the B<notBefore> and B<notAfter> fields.
639 Don't print out the subject name.
643 Don't print out the issuer name.
647 Don't print out the public key.
651 Don't give a hexadecimal dump of the certificate signature.
655 Don't print out certificate trust information.
657 =item B<no_extensions>
659 Don't print out any X509V3 extensions.
663 Retain default extension behaviour: attempt to print out unsupported
664 certificate extensions.
668 Print an error message for unsupported certificate extensions.
672 ASN1 parse unsupported extensions.
676 Hex dump unsupported extensions.
680 The value used by L<openssl-ca(1)>, equivalent to B<no_issuer>, B<no_pubkey>,
681 B<no_header>, and B<no_version>.
687 Note: in these examples the '\' means the example should be all on one
690 Print the contents of a certificate:
692 openssl x509 -in cert.pem -noout -text
694 Print the "Subject Alternative Name" extension of a certificate:
696 openssl x509 -in cert.pem -noout -ext subjectAltName
698 Print more extensions of a certificate:
700 openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType
702 Print the certificate serial number:
704 openssl x509 -in cert.pem -noout -serial
706 Print the certificate subject name:
708 openssl x509 -in cert.pem -noout -subject
710 Print the certificate subject name in RFC2253 form:
712 openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
714 Print the certificate subject name in oneline form on a terminal
717 openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
719 Print the certificate SHA1 fingerprint:
721 openssl x509 -sha1 -in cert.pem -noout -fingerprint
723 Convert a certificate from PEM to DER format:
725 openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
727 Convert a certificate to a certificate request:
729 openssl x509 -x509toreq -in cert.pem -out req.pem -key key.pem
731 Convert a certificate request into a self-signed certificate using
734 openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
735 -key key.pem -out cacert.pem
737 Sign a certificate request using the CA certificate above and add user
738 certificate extensions:
740 openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
741 -CA cacert.pem -CAkey key.pem -CAcreateserial
743 Set a certificate to be trusted for SSL client use and change set its alias to
746 openssl x509 -in cert.pem -addtrust clientAuth \
747 -setalias "Steve's Class 1 CA" -out trust.pem
751 The conversion to UTF8 format used with the name options assumes that
752 T61Strings use the ISO8859-1 character set. This is wrong but Netscape
753 and MSIE do this as do many certificates. So although this is incorrect
754 it is more likely to print the majority of certificates correctly.
756 The B<-email> option searches the subject name and the subject alternative
757 name extension. Only unique email addresses will be printed out: it will
758 not print the same address more than once.
762 It is possible to produce invalid certificates or requests by specifying the
763 wrong private key, using unsuitable X.509 extensions,
764 or using inconsistent options in some cases: these should be checked.
766 There should be options to explicitly set such things as start and end
767 dates rather than an offset from the current time.
774 L<openssl-genrsa(1)>,
775 L<openssl-gendsa(1)>,
776 L<openssl-verify(1)>,
781 The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
782 before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
783 of the distinguished name. In OpenSSL 1.0.0 and later it is based on a canonical
784 version of the DN using SHA1. This means that any directories using the old
785 form must have their links rebuilt using L<openssl-rehash(1)> or similar.
787 The B<-signkey> option has been renamed to B<-key> in OpenSSL 3.0,
788 keeping the old name as an alias.
790 The B<-engine> option was deprecated in OpenSSL 3.0.
792 The B<-C> option was removed in OpenSSL 3.0.
794 Since OpenSSL 3.2, generated certificates bear X.509 version 3,
795 and key identifier extensions are included by default.
799 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
801 Licensed under the Apache License 2.0 (the "License"). You may not use
802 this file except in compliance with the License. You can obtain a copy
803 in the file LICENSE in the source distribution or at
804 L<https://www.openssl.org/source/license.html>.