1X509(1) OpenSSL X509(1)
2
6 x509 - Certificate display and signing utility
7
9 openssl x509 [-inform DER|PEM|NET] [-outform DER|PEM|NET] [-keyform
10 DER|PEM] [-CAform DER|PEM] [-CAkeyform DER|PEM] [-in filename] [-out
11 filename] [-serial] [-hash] [-subject_hash] [-issuer_hash] [-ocspid]
12 [-subject] [-issuer] [-nameopt option] [-email] [-ocsp_uri]
13 [-startdate] [-enddate] [-purpose] [-dates] [-checkend num] [-modulus]
14 [-pubkey] [-fingerprint] [-alias] [-noout] [-trustout] [-clrtrust]
15 [-clrreject] [-addtrust arg] [-addreject arg] [-setalias arg] [-days
16 arg] [-set_serial n] [-signkey filename] [-passin arg] [-x509toreq]
17 [-req] [-CA filename] [-CAkey filename] [-CAcreateserial] [-CAserial
18 filename] [-force_pubkey key] [-text] [-certopt option] [-C]
19 [-md2|-md5|-sha1|-mdc2] [-clrext] [-extfile filename] [-extensions
20 section] [-engine id]
21
23 The x509 command is a multi purpose certificate utility. It can be used
24 to display certificate information, convert certificates to various
25 forms, sign certificate requests like a "mini CA" or edit certificate
26 trust settings.
27 Since there are a large number of options they will split up into
29 various sections.
30
32 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
33 -inform DER|PEM|NET
34 This specifies the input format normally the command will expect an
35 X509 certificate but this can change if other options such as -req
36 are present. The DER format is the DER encoding of the certificate
37 and PEM is the base64 encoding of the DER encoding with header and
38 footer lines added. The NET option is an obscure Netscape server
39 format that is now obsolete.
40 -outform DER|PEM|NET
42 This specifies the output format, the options have the same meaning
43 as the -inform option.
44 -in filename
46 This specifies the input filename to read a certificate from or
47 standard input if this option is not specified.
48 -out filename
50 This specifies the output filename to write to or standard output
51 by default.
52 -md2|-md5|-sha1|-mdc2
54 the digest to use. This affects any signing or display option that
55 uses a message digest, such as the -fingerprint, -signkey and -CA
56 options. If not specified then SHA1 is used. If the key being used
57 to sign with is a DSA key then this option has no effect: SHA1 is
58 always used with DSA keys. For full list of digests see openssl
59 dgst -h output.
60 -engine id
62 specifying an engine (by its unique id string) will cause x509 to
63 attempt to obtain a functional reference to the specified engine,
64 thus initialising it if needed. The engine will then be set as the
65 default for all available algorithms.
66 DISPLAY OPTIONS
68 Note: the -alias and -purpose options are also display options but are
69 described in the TRUST SETTINGS section.
70 -text
72 prints out the certificate in text form. Full details are output
73 including the public key, signature algorithms, issuer and subject
74 names, serial number any extensions present and any trust settings.
75 -certopt option
77 customise the output format used with -text. The option argument
78 can be a single option or multiple options separated by commas. The
79 -certopt switch may be also be used more than once to set multiple
80 options. See the TEXT OPTIONS section for more information.
81 -noout
83 this option prevents output of the encoded version of the request.
84 -pubkey
86 outputs the the certificate's SubjectPublicKeyInfo block in PEM
87 format.
88 -modulus
90 this option prints out the value of the modulus of the public key
91 contained in the certificate.
92 -serial
94 outputs the certificate serial number.
95 -subject_hash
97 outputs the "hash" of the certificate subject name. This is used in
98 OpenSSL to form an index to allow certificates in a directory to be
99 looked up by subject name.
100 -issuer_hash
102 outputs the "hash" of the certificate issuer name.
103 -ocspid
105 outputs the OCSP hash values for the subject name and public key.
106 -hash
108 synonym for "-subject_hash" for backward compatibility reasons.
109 -subject_hash_old
111 outputs the "hash" of the certificate subject name using the older
112 algorithm as used by OpenSSL versions before 1.0.0.
113 -issuer_hash_old
115 outputs the "hash" of the certificate issuer name using the older
116 algorithm as used by OpenSSL versions before 1.0.0.
117 -subject
119 outputs the subject name.
120 -issuer
122 outputs the issuer name.
123 -nameopt option
125 option which determines how the subject or issuer names are
126 displayed. The option argument can be a single option or multiple
127 options separated by commas. Alternatively the -nameopt switch may
128 be used more than once to set multiple options. See the NAME
129 OPTIONS section for more information.
130 -email
132 outputs the email address(es) if any.
133 -ocsp_uri
135 outputs the OCSP responder address(es) if any.
136 -startdate
138 prints out the start date of the certificate, that is the notBefore
139 date.
140 -enddate
142 prints out the expiry date of the certificate, that is the notAfter
143 date.
144 -dates
146 prints out the start and expiry dates of a certificate.
147 -checkend arg
149 checks if the certificate expires within the next arg seconds and
150 exits non-zero if yes it will expire or zero if not.
151 -fingerprint
153 prints out the digest of the DER encoded version of the whole
154 certificate (see digest options).
155 -C this outputs the certificate in the form of a C source file.
157 TRUST SETTINGS
159 Please note these options are currently experimental and may well
160 change.
161 A trusted certificate is an ordinary certificate which has several
163 additional pieces of information attached to it such as the permitted
164 and prohibited uses of the certificate and an "alias".
165 Normally when a certificate is being verified at least one certificate
167 must be "trusted". By default a trusted certificate must be stored
168 locally and must be a root CA: any certificate chain ending in this CA
169 is then usable for any purpose.
170 Trust settings currently are only used with a root CA. They allow a
172 finer control over the purposes the root CA can be used for. For
173 example a CA may be trusted for SSL client but not SSL server use.
174 See the description of the verify utility for more information on the
176 meaning of trust settings.
177 Future versions of OpenSSL will recognize trust settings on any
179 certificate: not just root CAs.
180 -trustout
182 this causes x509 to output a trusted certificate. An ordinary or
183 trusted certificate can be input but by default an ordinary
184 certificate is output and any trust settings are discarded. With
185 the -trustout option a trusted certificate is output. A trusted
186 certificate is automatically output if any trust settings are
187 modified.
188 -setalias arg
190 sets the alias of the certificate. This will allow the certificate
191 to be referred to using a nickname for example "Steve's
192 Certificate".
193 -alias
195 outputs the certificate alias, if any.
196 -clrtrust
198 clears all the permitted or trusted uses of the certificate.
199 -clrreject
201 clears all the prohibited or rejected uses of the certificate.
202 -addtrust arg
204 adds a trusted certificate use. Any object name can be used here
205 but currently only clientAuth (SSL client use), serverAuth (SSL
206 server use) and emailProtection (S/MIME email) are used. Other
207 OpenSSL applications may define additional uses.
208 -addreject arg
210 adds a prohibited use. It accepts the same values as the -addtrust
211 option.
212 -purpose
214 this option performs tests on the certificate extensions and
215 outputs the results. For a more complete description see the
216 CERTIFICATE EXTENSIONS section.
217 SIGNING OPTIONS
219 The x509 utility can be used to sign certificates and requests: it can
220 thus behave like a "mini CA".
221 -signkey filename
223 this option causes the input file to be self signed using the
224 supplied private key.
225 If the input file is a certificate it sets the issuer name to the
227 subject name (i.e. makes it self signed) changes the public key to
228 the supplied value and changes the start and end dates. The start
229 date is set to the current time and the end date is set to a value
230 determined by the -days option. Any certificate extensions are
231 retained unless the -clrext option is supplied.
232 If the input is a certificate request then a self signed
234 certificate is created using the supplied private key using the
235 subject name in the request.
236 -passin arg
238 the key password source. For more information about the format of
239 arg see the PASS PHRASE ARGUMENTS section in openssl(1).
240 -clrext
242 delete any extensions from a certificate. This option is used when
243 a certificate is being created from another certificate (for
244 example with the -signkey or the -CA options). Normally all
245 extensions are retained.
246 -keyform PEM|DER
248 specifies the format (DER or PEM) of the private key file used in
249 the -signkey option.
250 -days arg
252 specifies the number of days to make a certificate valid for. The
253 default is 30 days.
254 -x509toreq
256 converts a certificate into a certificate request. The -signkey
257 option is used to pass the required private key.
258 -req
260 by default a certificate is expected on input. With this option a
261 certificate request is expected instead.
262 -set_serial n
264 specifies the serial number to use. This option can be used with
265 either the -signkey or -CA options. If used in conjunction with the
266 -CA option the serial number file (as specified by the -CAserial or
267 -CAcreateserial options) is not used.
268 The serial number can be decimal or hex (if preceded by 0x).
270 Negative serial numbers can also be specified but their use is not
271 recommended.
272 -CA filename
274 specifies the CA certificate to be used for signing. When this
275 option is present x509 behaves like a "mini CA". The input file is
276 signed by this CA using this option: that is its issuer name is set
277 to the subject name of the CA and it is digitally signed using the
278 CAs private key.
279 This option is normally combined with the -req option. Without the
281 -req option the input is a certificate which must be self signed.
282 -CAkey filename
284 sets the CA private key to sign a certificate with. If this option
285 is not specified then it is assumed that the CA private key is
286 present in the CA certificate file.
287 -CAserial filename
289 sets the CA serial number file to use.
290 When the -CA option is used to sign a certificate it uses a serial
292 number specified in a file. This file consist of one line
293 containing an even number of hex digits with the serial number to
294 use. After each use the serial number is incremented and written
295 out to the file again.
296 The default filename consists of the CA certificate file base name
298 with ".srl" appended. For example if the CA certificate file is
299 called "mycacert.pem" it expects to find a serial number file
300 called "mycacert.srl".
301 -CAcreateserial
303 with this option the CA serial number file is created if it does
304 not exist: it will contain the serial number "02" and the
305 certificate being signed will have the 1 as its serial number.
306 Normally if the -CA option is specified and the serial number file
307 does not exist it is an error.
308 -extfile filename
310 file containing certificate extensions to use. If not specified
311 then no extensions are added to the certificate.
312 -extensions section
314 the section to add certificate extensions from. If this option is
315 not specified then the extensions should either be contained in the
316 unnamed (default) section or the default section should contain a
317 variable called "extensions" which contains the section to use. See
318 the x509v3_config(5) manual page for details of the extension
319 section format.
320 -force_pubkey key
322 when a certificate is created set its public key to key instead of
323 the key in the certificate or certificate request. This option is
324 useful for creating certificates where the algorithm can't normally
325 sign requests, for example DH.
326 The format or key can be specified using the -keyform option.
328 NAME OPTIONS
330 The nameopt command line switch determines how the subject and issuer
331 names are displayed. If no nameopt switch is present the default
332 "oneline" format is used which is compatible with previous versions of
333 OpenSSL. Each option is described in detail below, all options can be
334 preceded by a - to turn the option off. Only the first four will
335 normally be used.
336 compat
338 use the old format. This is equivalent to specifying no name
339 options at all.
340 RFC2253
342 displays names compatible with RFC2253 equivalent to esc_2253,
343 esc_ctrl, esc_msb, utf8, dump_nostr, dump_unknown, dump_der,
344 sep_comma_plus, dn_rev and sname.
345 oneline
347 a oneline format which is more readable than RFC2253. It is
348 equivalent to specifying the esc_2253, esc_ctrl, esc_msb, utf8,
349 dump_nostr, dump_der, use_quote, sep_comma_plus_space, space_eq and
350 sname options.
351 multiline
353 a multiline format. It is equivalent esc_ctrl, esc_msb,
354 sep_multiline, space_eq, lname and align.
355 esc_2253
357 escape the "special" characters required by RFC2253 in a field That
358 is ,+"<>;. Additionally # is escaped at the beginning of a string
359 and a space character at the beginning or end of a string.
360 esc_ctrl
362 escape control characters. That is those with ASCII values less
363 than 0x20 (space) and the delete (0x7f) character. They are escaped
364 using the RFC2253 \XX notation (where XX are two hex digits
365 representing the character value).
366 esc_msb
368 escape characters with the MSB set, that is with ASCII values
369 larger than 127.
370 use_quote
372 escapes some characters by surrounding the whole string with "
373 characters, without the option all escaping is done with the \
374 character.
375 utf8
377 convert all strings to UTF8 format first. This is required by
378 RFC2253. If you are lucky enough to have a UTF8 compatible terminal
379 then the use of this option (and not setting esc_msb) may result in
380 the correct display of multibyte (international) characters. Is
381 this option is not present then multibyte characters larger than
382 0xff will be represented using the format \UXXXX for 16 bits and
383 \WXXXXXXXX for 32 bits. Also if this option is off any UTF8Strings
384 will be converted to their character form first.
385 ignore_type
387 this option does not attempt to interpret multibyte characters in
388 any way. That is their content octets are merely dumped as though
389 one octet represents each character. This is useful for diagnostic
390 purposes but will result in rather odd looking output.
391 show_type
393 show the type of the ASN1 character string. The type precedes the
394 field contents. For example "BMPSTRING: Hello World".
395 dump_der
397 when this option is set any fields that need to be hexdumped will
398 be dumped using the DER encoding of the field. Otherwise just the
399 content octets will be displayed. Both options use the RFC2253
400 #XXXX... format.
401 dump_nostr
403 dump non character string types (for example OCTET STRING) if this
404 option is not set then non character string types will be displayed
405 as though each content octet represents a single character.
406 dump_all
408 dump all fields. This option when used with dump_der allows the DER
409 encoding of the structure to be unambiguously determined.
410 dump_unknown
412 dump any field whose OID is not recognised by OpenSSL.
413 sep_comma_plus, sep_comma_plus_space, sep_semi_plus_space,
415 sep_multiline
416 these options determine the field separators. The first character
417 is between RDNs and the second between multiple AVAs (multiple AVAs
418 are very rare and their use is discouraged). The options ending in
419 "space" additionally place a space after the separator to make it
420 more readable. The sep_multiline uses a linefeed character for the
421 RDN separator and a spaced + for the AVA separator. It also indents
422 the fields by four characters. If no field separator is specified
423 then sep_comma_plus_space is used by default.
424 dn_rev
426 reverse the fields of the DN. This is required by RFC2253. As a
427 side effect this also reverses the order of multiple AVAs but this
428 is permissible.
429 nofname, sname, lname, oid
431 these options alter how the field name is displayed. nofname does
432 not display the field at all. sname uses the "short name" form (CN
433 for commonName for example). lname uses the long form. oid
434 represents the OID in numerical form and is useful for diagnostic
435 purpose.
436 align
438 align field values for a more readable output. Only usable with
439 sep_multiline.
440 space_eq
442 places spaces round the = character which follows the field name.
443 TEXT OPTIONS
445 As well as customising the name output format, it is also possible to
446 customise the actual fields printed using the certopt options when the
447 text option is present. The default behaviour is to print all fields.
448 compatible
450 use the old format. This is equivalent to specifying no output
451 options at all.
452 no_header
454 don't print header information: that is the lines saying
455 "Certificate" and "Data".
456 no_version
458 don't print out the version number.
459 no_serial
461 don't print out the serial number.
462 no_signame
464 don't print out the signature algorithm used.
465 no_validity
467 don't print the validity, that is the notBefore and notAfter
468 fields.
469 no_subject
471 don't print out the subject name.
472 no_issuer
474 don't print out the issuer name.
475 no_pubkey
477 don't print out the public key.
478 no_sigdump
480 don't give a hexadecimal dump of the certificate signature.
481 no_aux
483 don't print out certificate trust information.
484 no_extensions
486 don't print out any X509V3 extensions.
487 ext_default
489 retain default extension behaviour: attempt to print out
490 unsupported certificate extensions.
491 ext_error
493 print an error message for unsupported certificate extensions.
494 ext_parse
496 ASN1 parse unsupported extensions.
497 ext_dump
499 hex dump unsupported extensions.
500 ca_default
502 the value used by the ca utility, equivalent to no_issuer,
503 no_pubkey, no_header, and no_version.
504
506 Note: in these examples the '\' means the example should be all on one
507 line.
508 Display the contents of a certificate:
510 openssl x509 -in cert.pem -noout -text
512 Display the certificate serial number:
514 openssl x509 -in cert.pem -noout -serial
516 Display the certificate subject name:
518 openssl x509 -in cert.pem -noout -subject
520 Display the certificate subject name in RFC2253 form:
522 openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
524 Display the certificate subject name in oneline form on a terminal
526 supporting UTF8:
527 openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
529 Display the certificate MD5 fingerprint:
531 openssl x509 -in cert.pem -noout -fingerprint
533 Display the certificate SHA1 fingerprint:
535 openssl x509 -sha1 -in cert.pem -noout -fingerprint
537 Convert a certificate from PEM to DER format:
539 openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
541 Convert a certificate to a certificate request:
543 openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
545 Convert a certificate request into a self signed certificate using
547 extensions for a CA:
548 openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
550 -signkey key.pem -out cacert.pem
551 Sign a certificate request using the CA certificate above and add user
553 certificate extensions:
554 openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
556 -CA cacert.pem -CAkey key.pem -CAcreateserial
557 Set a certificate to be trusted for SSL client use and change set its
559 alias to "Steve's Class 1 CA"
560 openssl x509 -in cert.pem -addtrust clientAuth \
562 -setalias "Steve's Class 1 CA" -out trust.pem
563
565 The PEM format uses the header and footer lines:
566 -----BEGIN CERTIFICATE-----
568 -----END CERTIFICATE-----
569 it will also handle files containing:
571 -----BEGIN X509 CERTIFICATE-----
573 -----END X509 CERTIFICATE-----
574 Trusted certificates have the lines
576 -----BEGIN TRUSTED CERTIFICATE-----
578 -----END TRUSTED CERTIFICATE-----
579 The conversion to UTF8 format used with the name options assumes that
581 T61Strings use the ISO8859-1 character set. This is wrong but Netscape
582 and MSIE do this as do many certificates. So although this is incorrect
583 it is more likely to display the majority of certificates correctly.
584 The -fingerprint option takes the digest of the DER encoded
586 certificate. This is commonly called a "fingerprint". Because of the
587 nature of message digests the fingerprint of a certificate is unique to
588 that certificate and two certificates with the same fingerprint can be
589 considered to be the same.
590 The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
592 The -email option searches the subject name and the subject alternative
594 name extension. Only unique email addresses will be printed out: it
595 will not print the same address more than once.
596
598 The -purpose option checks the certificate extensions and determines
599 what the certificate can be used for. The actual checks done are rather
600 complex and include various hacks and workarounds to handle broken
601 certificates and software.
602 The same code is used when verifying untrusted certificates in chains
604 so this section is useful if a chain is rejected by the verify code.
605 The basicConstraints extension CA flag is used to determine whether the
607 certificate can be used as a CA. If the CA flag is true then it is a
608 CA, if the CA flag is false then it is not a CA. All CAs should have
609 the CA flag set to true.
610 If the basicConstraints extension is absent then the certificate is
612 considered to be a "possible CA" other extensions are checked according
613 to the intended use of the certificate. A warning is given in this case
614 because the certificate should really not be regarded as a CA: however
615 it is allowed to be a CA to work around some broken software.
616 If the certificate is a V1 certificate (and thus has no extensions) and
618 it is self signed it is also assumed to be a CA but a warning is again
619 given: this is to work around the problem of Verisign roots which are
620 V1 self signed certificates.
621 If the keyUsage extension is present then additional restraints are
623 made on the uses of the certificate. A CA certificate must have the
624 keyCertSign bit set if the keyUsage extension is present.
625 The extended key usage extension places additional restrictions on the
627 certificate uses. If this extension is present (whether critical or
628 not) the key can only be used for the purposes specified.
629 A complete description of each test is given below. The comments about
631 basicConstraints and keyUsage and V1 certificates above apply to all CA
632 certificates.
633 SSL Client
635 The extended key usage extension must be absent or include the "web
636 client authentication" OID. keyUsage must be absent or it must
637 have the digitalSignature bit set. Netscape certificate type must
638 be absent or it must have the SSL client bit set.
639 SSL Client CA
641 The extended key usage extension must be absent or include the "web
642 client authentication" OID. Netscape certificate type must be
643 absent or it must have the SSL CA bit set: this is used as a work
644 around if the basicConstraints extension is absent.
645 SSL Server
647 The extended key usage extension must be absent or include the "web
648 server authentication" and/or one of the SGC OIDs. keyUsage must
649 be absent or it must have the digitalSignature, the keyEncipherment
650 set or both bits set. Netscape certificate type must be absent or
651 have the SSL server bit set.
652 SSL Server CA
654 The extended key usage extension must be absent or include the "web
655 server authentication" and/or one of the SGC OIDs. Netscape
656 certificate type must be absent or the SSL CA bit must be set: this
657 is used as a work around if the basicConstraints extension is
658 absent.
659 Netscape SSL Server
661 For Netscape SSL clients to connect to an SSL server it must have
662 the keyEncipherment bit set if the keyUsage extension is present.
663 This isn't always valid because some cipher suites use the key for
664 digital signing. Otherwise it is the same as a normal SSL server.
665 Common S/MIME Client Tests
667 The extended key usage extension must be absent or include the
668 "email protection" OID. Netscape certificate type must be absent or
669 should have the S/MIME bit set. If the S/MIME bit is not set in
670 netscape certificate type then the SSL client bit is tolerated as
671 an alternative but a warning is shown: this is because some
672 Verisign certificates don't set the S/MIME bit.
673 S/MIME Signing
675 In addition to the common S/MIME client tests the digitalSignature
676 bit must be set if the keyUsage extension is present.
677 S/MIME Encryption
679 In addition to the common S/MIME tests the keyEncipherment bit must
680 be set if the keyUsage extension is present.
681 S/MIME CA
683 The extended key usage extension must be absent or include the
684 "email protection" OID. Netscape certificate type must be absent or
685 must have the S/MIME CA bit set: this is used as a work around if
686 the basicConstraints extension is absent.
687 CRL Signing
689 The keyUsage extension must be absent or it must have the CRL
690 signing bit set.
691 CRL Signing CA
693 The normal CA tests apply. Except in this case the basicConstraints
694 extension must be present.
695
697 Extensions in certificates are not transferred to certificate requests
698 and vice versa.
699 It is possible to produce invalid certificates or requests by
701 specifying the wrong private key or using inconsistent options in some
702 cases: these should be checked.
703 There should be options to explicitly set such things as start and end
705 dates rather than an offset from the current time.
706 The code to implement the verify behaviour described in the TRUST
708 SETTINGS is currently being developed. It thus describes the intended
709 behaviour rather than the current behaviour. It is hoped that it will
710 represent reality in OpenSSL 0.9.5 and later.
711
713 req(1), ca(1), genrsa(1), gendsa(1), verify(1), x509v3_config(5)
714
716 Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
717 The hash algorithm used in the -subject_hash and -issuer_hash options
719 before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the
720 encoding of the distinguished name. In OpenSSL 1.0.0 and later it is
721 based on a canonical version of the DN using SHA1. This means that any
722 directories using the old form must have their links rebuilt using
723 c_rehash or similar.
7241.0.2k 2019-03-12 X509(1)