1X509(1)                             OpenSSL                            X509(1)
2
3
4

NAME

6       x509 - Certificate display and signing utility
7

SYNOPSIS

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] [-subject]
12       [-issuer] [-nameopt option] [-email] [-ocsp_uri] [-startdate]
13       [-enddate] [-purpose] [-dates] [-modulus] [-pubkey] [-fingerprint]
14       [-alias] [-noout] [-trustout] [-clrtrust] [-clrreject] [-addtrust arg]
15       [-addreject arg] [-setalias arg] [-days arg] [-set_serial n] [-signkey
16       filename] [-x509toreq] [-req] [-CA filename] [-CAkey filename]
17       [-CAcreateserial] [-CAserial filename] [-text] [-C]
18       [-md2|-md5|-sha1|-mdc2] [-clrext] [-extfile filename] [-extensions
19       section] [-engine id]
20

DESCRIPTION

22       The x509 command is a multi purpose certificate utility. It can be used
23       to display certificate information, convert certificates to various
24       forms, sign certificate requests like a "mini CA" or edit certificate
25       trust settings.
26
27       Since there are a large number of options they will split up into
28       various sections.
29

OPTIONS

31   INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
32       -inform DER|PEM|NET
33           This specifies the input format normally the command will expect an
34           X509 certificate but this can change if other options such as -req
35           are present. The DER format is the DER encoding of the certificate
36           and PEM is the base64 encoding of the DER encoding with header and
37           footer lines added. The NET option is an obscure Netscape server
38           format that is now obsolete.
39
40       -outform DER|PEM|NET
41           This specifies the output format, the options have the same meaning
42           as the -inform option.
43
44       -in filename
45           This specifies the input filename to read a certificate from or
46           standard input if this option is not specified.
47
48       -out filename
49           This specifies the output filename to write to or standard output
50           by default.
51
52       -md2|-md5|-sha1|-mdc2
53           the digest to use. This affects any signing or display option that
54           uses a message digest, such as the -fingerprint, -signkey and -CA
55           options. If not specified then SHA1 is used. If the key being used
56           to sign with is a DSA key then this option has no effect: SHA1 is
57           always used with DSA keys.  For full list of digests see openssl
58           dgst -h output.
59
60       -engine id
61           specifying an engine (by its unique id string) will cause x509 to
62           attempt to obtain a functional reference to the specified engine,
63           thus initialising it if needed. The engine will then be set as the
64           default for all available algorithms.
65
66   DISPLAY OPTIONS
67       Note: the -alias and -purpose options are also display options but are
68       described in the TRUST SETTINGS section.
69
70       -text
71           prints out the certificate in text form. Full details are output
72           including the public key, signature algorithms, issuer and subject
73           names, serial number any extensions present and any trust settings.
74
75       -certopt option
76           customise the output format used with -text. The option argument
77           can be a single option or multiple options separated by commas. The
78           -certopt switch may be also be used more than once to set multiple
79           options. See the TEXT OPTIONS section for more information.
80
81       -noout
82           this option prevents output of the encoded version of the request.
83
84       -pubkey
85           outputs the the certificate's SubjectPublicKeyInfo block in PEM
86           format.
87
88       -modulus
89           this option prints out the value of the modulus of the public key
90           contained in the certificate.
91
92       -serial
93           outputs the certificate serial number.
94
95       -subject_hash
96           outputs the "hash" of the certificate subject name. This is used in
97           OpenSSL to form an index to allow certificates in a directory to be
98           looked up by subject name.
99
100       -issuer_hash
101           outputs the "hash" of the certificate issuer name.
102
103       -hash
104           synonym for "-subject_hash" for backward compatibility reasons.
105
106       -subject_hash_old
107           outputs the "hash" of the certificate subject name using the older
108           algorithm as used by OpenSSL versions before 1.0.0.
109
110       -issuer_hash_old
111           outputs the "hash" of the certificate issuer name using the older
112           algorithm as used by OpenSSL versions before 1.0.0.
113
114       -subject
115           outputs the subject name.
116
117       -issuer
118           outputs the issuer name.
119
120       -nameopt option
121           option which determines how the subject or issuer names are
122           displayed. The option argument can be a single option or multiple
123           options separated by commas.  Alternatively the -nameopt switch may
124           be used more than once to set multiple options. See the NAME
125           OPTIONS section for more information.
126
127       -email
128           outputs the email address(es) if any.
129
130       -ocsp_uri
131           outputs the OCSP responder address(es) if any.
132
133       -startdate
134           prints out the start date of the certificate, that is the notBefore
135           date.
136
137       -enddate
138           prints out the expiry date of the certificate, that is the notAfter
139           date.
140
141       -dates
142           prints out the start and expiry dates of a certificate.
143
144       -fingerprint
145           prints out the digest of the DER encoded version of the whole
146           certificate (see digest options).
147
148       -C  this outputs the certificate in the form of a C source file.
149
150   TRUST SETTINGS
151       Please note these options are currently experimental and may well
152       change.
153
154       A trusted certificate is an ordinary certificate which has several
155       additional pieces of information attached to it such as the permitted
156       and prohibited uses of the certificate and an "alias".
157
158       Normally when a certificate is being verified at least one certificate
159       must be "trusted". By default a trusted certificate must be stored
160       locally and must be a root CA: any certificate chain ending in this CA
161       is then usable for any purpose.
162
163       Trust settings currently are only used with a root CA. They allow a
164       finer control over the purposes the root CA can be used for. For
165       example a CA may be trusted for SSL client but not SSL server use.
166
167       See the description of the verify utility for more information on the
168       meaning of trust settings.
169
170       Future versions of OpenSSL will recognize trust settings on any
171       certificate: not just root CAs.
172
173       -trustout
174           this causes x509 to output a trusted certificate. An ordinary or
175           trusted certificate can be input but by default an ordinary
176           certificate is output and any trust settings are discarded. With
177           the -trustout option a trusted certificate is output. A trusted
178           certificate is automatically output if any trust settings are
179           modified.
180
181       -setalias arg
182           sets the alias of the certificate. This will allow the certificate
183           to be referred to using a nickname for example "Steve's
184           Certificate".
185
186       -alias
187           outputs the certificate alias, if any.
188
189       -clrtrust
190           clears all the permitted or trusted uses of the certificate.
191
192       -clrreject
193           clears all the prohibited or rejected uses of the certificate.
194
195       -addtrust arg
196           adds a trusted certificate use. Any object name can be used here
197           but currently only clientAuth (SSL client use), serverAuth (SSL
198           server use) and emailProtection (S/MIME email) are used.  Other
199           OpenSSL applications may define additional uses.
200
201       -addreject arg
202           adds a prohibited use. It accepts the same values as the -addtrust
203           option.
204
205       -purpose
206           this option performs tests on the certificate extensions and
207           outputs the results. For a more complete description see the
208           CERTIFICATE EXTENSIONS section.
209
210   SIGNING OPTIONS
211       The x509 utility can be used to sign certificates and requests: it can
212       thus behave like a "mini CA".
213
214       -signkey filename
215           this option causes the input file to be self signed using the
216           supplied private key.
217
218           If the input file is a certificate it sets the issuer name to the
219           subject name (i.e.  makes it self signed) changes the public key to
220           the supplied value and changes the start and end dates. The start
221           date is set to the current time and the end date is set to a value
222           determined by the -days option. Any certificate extensions are
223           retained unless the -clrext option is supplied.
224
225           If the input is a certificate request then a self signed
226           certificate is created using the supplied private key using the
227           subject name in the request.
228
229       -clrext
230           delete any extensions from a certificate. This option is used when
231           a certificate is being created from another certificate (for
232           example with the -signkey or the -CA options). Normally all
233           extensions are retained.
234
235       -keyform PEM|DER
236           specifies the format (DER or PEM) of the private key file used in
237           the -signkey option.
238
239       -days arg
240           specifies the number of days to make a certificate valid for. The
241           default is 30 days.
242
243       -x509toreq
244           converts a certificate into a certificate request. The -signkey
245           option is used to pass the required private key.
246
247       -req
248           by default a certificate is expected on input. With this option a
249           certificate request is expected instead.
250
251       -set_serial n
252           specifies the serial number to use. This option can be used with
253           either the -signkey or -CA options. If used in conjunction with the
254           -CA option the serial number file (as specified by the -CAserial or
255           -CAcreateserial options) is not used.
256
257           The serial number can be decimal or hex (if preceded by 0x).
258           Negative serial numbers can also be specified but their use is not
259           recommended.
260
261       -CA filename
262           specifies the CA certificate to be used for signing. When this
263           option is present x509 behaves like a "mini CA". The input file is
264           signed by this CA using this option: that is its issuer name is set
265           to the subject name of the CA and it is digitally signed using the
266           CAs private key.
267
268           This option is normally combined with the -req option. Without the
269           -req option the input is a certificate which must be self signed.
270
271       -CAkey filename
272           sets the CA private key to sign a certificate with. If this option
273           is not specified then it is assumed that the CA private key is
274           present in the CA certificate file.
275
276       -CAserial filename
277           sets the CA serial number file to use.
278
279           When the -CA option is used to sign a certificate it uses a serial
280           number specified in a file. This file consist of one line
281           containing an even number of hex digits with the serial number to
282           use. After each use the serial number is incremented and written
283           out to the file again.
284
285           The default filename consists of the CA certificate file base name
286           with ".srl" appended. For example if the CA certificate file is
287           called "mycacert.pem" it expects to find a serial number file
288           called "mycacert.srl".
289
290       -CAcreateserial
291           with this option the CA serial number file is created if it does
292           not exist: it will contain the serial number "02" and the
293           certificate being signed will have the 1 as its serial number.
294           Normally if the -CA option is specified and the serial number file
295           does not exist it is an error.
296
297       -extfile filename
298           file containing certificate extensions to use. If not specified
299           then no extensions are added to the certificate.
300
301       -extensions section
302           the section to add certificate extensions from. If this option is
303           not specified then the extensions should either be contained in the
304           unnamed (default) section or the default section should contain a
305           variable called "extensions" which contains the section to use. See
306           the x509v3_config(5) manual page for details of the extension
307           section format.
308
309   NAME OPTIONS
310       The nameopt command line switch determines how the subject and issuer
311       names are displayed. If no nameopt switch is present the default
312       "oneline" format is used which is compatible with previous versions of
313       OpenSSL.  Each option is described in detail below, all options can be
314       preceded by a - to turn the option off. Only the first four will
315       normally be used.
316
317       compat
318           use the old format. This is equivalent to specifying no name
319           options at all.
320
321       RFC2253
322           displays names compatible with RFC2253 equivalent to esc_2253,
323           esc_ctrl, esc_msb, utf8, dump_nostr, dump_unknown, dump_der,
324           sep_comma_plus, dn_rev and sname.
325
326       oneline
327           a oneline format which is more readable than RFC2253. It is
328           equivalent to specifying the  esc_2253, esc_ctrl, esc_msb, utf8,
329           dump_nostr, dump_der, use_quote, sep_comma_plus_space, space_eq and
330           sname options.
331
332       multiline
333           a multiline format. It is equivalent esc_ctrl, esc_msb,
334           sep_multiline, space_eq, lname and align.
335
336       esc_2253
337           escape the "special" characters required by RFC2253 in a field That
338           is ,+"<>;. Additionally # is escaped at the beginning of a string
339           and a space character at the beginning or end of a string.
340
341       esc_ctrl
342           escape control characters. That is those with ASCII values less
343           than 0x20 (space) and the delete (0x7f) character. They are escaped
344           using the RFC2253 \XX notation (where XX are two hex digits
345           representing the character value).
346
347       esc_msb
348           escape characters with the MSB set, that is with ASCII values
349           larger than 127.
350
351       use_quote
352           escapes some characters by surrounding the whole string with "
353           characters, without the option all escaping is done with the \
354           character.
355
356       utf8
357           convert all strings to UTF8 format first. This is required by
358           RFC2253. If you are lucky enough to have a UTF8 compatible terminal
359           then the use of this option (and not setting esc_msb) may result in
360           the correct display of multibyte (international) characters. Is
361           this option is not present then multibyte characters larger than
362           0xff will be represented using the format \UXXXX for 16 bits and
363           \WXXXXXXXX for 32 bits.  Also if this option is off any UTF8Strings
364           will be converted to their character form first.
365
366       no_type
367           this option does not attempt to interpret multibyte characters in
368           any way. That is their content octets are merely dumped as though
369           one octet represents each character. This is useful for diagnostic
370           purposes but will result in rather odd looking output.
371
372       show_type
373           show the type of the ASN1 character string. The type precedes the
374           field contents. For example "BMPSTRING: Hello World".
375
376       dump_der
377           when this option is set any fields that need to be hexdumped will
378           be dumped using the DER encoding of the field. Otherwise just the
379           content octets will be displayed. Both options use the RFC2253
380           #XXXX... format.
381
382       dump_nostr
383           dump non character string types (for example OCTET STRING) if this
384           option is not set then non character string types will be displayed
385           as though each content octet represents a single character.
386
387       dump_all
388           dump all fields. This option when used with dump_der allows the DER
389           encoding of the structure to be unambiguously determined.
390
391       dump_unknown
392           dump any field whose OID is not recognised by OpenSSL.
393
394       sep_comma_plus, sep_comma_plus_space, sep_semi_plus_space,
395       sep_multiline
396           these options determine the field separators. The first character
397           is between RDNs and the second between multiple AVAs (multiple AVAs
398           are very rare and their use is discouraged). The options ending in
399           "space" additionally place a space after the separator to make it
400           more readable. The sep_multiline uses a linefeed character for the
401           RDN separator and a spaced + for the AVA separator. It also indents
402           the fields by four characters.
403
404       dn_rev
405           reverse the fields of the DN. This is required by RFC2253. As a
406           side effect this also reverses the order of multiple AVAs but this
407           is permissible.
408
409       nofname, sname, lname, oid
410           these options alter how the field name is displayed. nofname does
411           not display the field at all. sname uses the "short name" form (CN
412           for commonName for example). lname uses the long form.  oid
413           represents the OID in numerical form and is useful for diagnostic
414           purpose.
415
416       align
417           align field values for a more readable output. Only usable with
418           sep_multiline.
419
420       space_eq
421           places spaces round the = character which follows the field name.
422
423   TEXT OPTIONS
424       As well as customising the name output format, it is also possible to
425       customise the actual fields printed using the certopt options when the
426       text option is present. The default behaviour is to print all fields.
427
428       compatible
429           use the old format. This is equivalent to specifying no output
430           options at all.
431
432       no_header
433           don't print header information: that is the lines saying
434           "Certificate" and "Data".
435
436       no_version
437           don't print out the version number.
438
439       no_serial
440           don't print out the serial number.
441
442       no_signame
443           don't print out the signature algorithm used.
444
445       no_validity
446           don't print the validity, that is the notBefore and notAfter
447           fields.
448
449       no_subject
450           don't print out the subject name.
451
452       no_issuer
453           don't print out the issuer name.
454
455       no_pubkey
456           don't print out the public key.
457
458       no_sigdump
459           don't give a hexadecimal dump of the certificate signature.
460
461       no_aux
462           don't print out certificate trust information.
463
464       no_extensions
465           don't print out any X509V3 extensions.
466
467       ext_default
468           retain default extension behaviour: attempt to print out
469           unsupported certificate extensions.
470
471       ext_error
472           print an error message for unsupported certificate extensions.
473
474       ext_parse
475           ASN1 parse unsupported extensions.
476
477       ext_dump
478           hex dump unsupported extensions.
479
480       ca_default
481           the value used by the ca utility, equivalent to no_issuer,
482           no_pubkey, no_header, no_version, no_sigdump and no_signame.
483

EXAMPLES

485       Note: in these examples the '\' means the example should be all on one
486       line.
487
488       Display the contents of a certificate:
489
490        openssl x509 -in cert.pem -noout -text
491
492       Display the certificate serial number:
493
494        openssl x509 -in cert.pem -noout -serial
495
496       Display the certificate subject name:
497
498        openssl x509 -in cert.pem -noout -subject
499
500       Display the certificate subject name in RFC2253 form:
501
502        openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
503
504       Display the certificate subject name in oneline form on a terminal
505       supporting UTF8:
506
507        openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
508
509       Display the certificate MD5 fingerprint:
510
511        openssl x509 -in cert.pem -noout -fingerprint
512
513       Display the certificate SHA1 fingerprint:
514
515        openssl x509 -sha1 -in cert.pem -noout -fingerprint
516
517       Convert a certificate from PEM to DER format:
518
519        openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
520
521       Convert a certificate to a certificate request:
522
523        openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
524
525       Convert a certificate request into a self signed certificate using
526       extensions for a CA:
527
528        openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
529               -signkey key.pem -out cacert.pem
530
531       Sign a certificate request using the CA certificate above and add user
532       certificate extensions:
533
534        openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
535               -CA cacert.pem -CAkey key.pem -CAcreateserial
536
537       Set a certificate to be trusted for SSL client use and change set its
538       alias to "Steve's Class 1 CA"
539
540        openssl x509 -in cert.pem -addtrust clientAuth \
541               -setalias "Steve's Class 1 CA" -out trust.pem
542

NOTES

544       The PEM format uses the header and footer lines:
545
546        -----BEGIN CERTIFICATE-----
547        -----END CERTIFICATE-----
548
549       it will also handle files containing:
550
551        -----BEGIN X509 CERTIFICATE-----
552        -----END X509 CERTIFICATE-----
553
554       Trusted certificates have the lines
555
556        -----BEGIN TRUSTED CERTIFICATE-----
557        -----END TRUSTED CERTIFICATE-----
558
559       The conversion to UTF8 format used with the name options assumes that
560       T61Strings use the ISO8859-1 character set. This is wrong but Netscape
561       and MSIE do this as do many certificates. So although this is incorrect
562       it is more likely to display the majority of certificates correctly.
563
564       The -fingerprint option takes the digest of the DER encoded
565       certificate.  This is commonly called a "fingerprint". Because of the
566       nature of message digests the fingerprint of a certificate is unique to
567       that certificate and two certificates with the same fingerprint can be
568       considered to be the same.
569
570       The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
571
572       The -email option searches the subject name and the subject alternative
573       name extension. Only unique email addresses will be printed out: it
574       will not print the same address more than once.
575

CERTIFICATE EXTENSIONS

577       The -purpose option checks the certificate extensions and determines
578       what the certificate can be used for. The actual checks done are rather
579       complex and include various hacks and workarounds to handle broken
580       certificates and software.
581
582       The same code is used when verifying untrusted certificates in chains
583       so this section is useful if a chain is rejected by the verify code.
584
585       The basicConstraints extension CA flag is used to determine whether the
586       certificate can be used as a CA. If the CA flag is true then it is a
587       CA, if the CA flag is false then it is not a CA. All CAs should have
588       the CA flag set to true.
589
590       If the basicConstraints extension is absent then the certificate is
591       considered to be a "possible CA" other extensions are checked according
592       to the intended use of the certificate. A warning is given in this case
593       because the certificate should really not be regarded as a CA: however
594       it is allowed to be a CA to work around some broken software.
595
596       If the certificate is a V1 certificate (and thus has no extensions) and
597       it is self signed it is also assumed to be a CA but a warning is again
598       given: this is to work around the problem of Verisign roots which are
599       V1 self signed certificates.
600
601       If the keyUsage extension is present then additional restraints are
602       made on the uses of the certificate. A CA certificate must have the
603       keyCertSign bit set if the keyUsage extension is present.
604
605       The extended key usage extension places additional restrictions on the
606       certificate uses. If this extension is present (whether critical or
607       not) the key can only be used for the purposes specified.
608
609       A complete description of each test is given below. The comments about
610       basicConstraints and keyUsage and V1 certificates above apply to all CA
611       certificates.
612
613       SSL Client
614           The extended key usage extension must be absent or include the "web
615           client authentication" OID.  keyUsage must be absent or it must
616           have the digitalSignature bit set. Netscape certificate type must
617           be absent or it must have the SSL client bit set.
618
619       SSL Client CA
620           The extended key usage extension must be absent or include the "web
621           client authentication" OID. Netscape certificate type must be
622           absent or it must have the SSL CA bit set: this is used as a work
623           around if the basicConstraints extension is absent.
624
625       SSL Server
626           The extended key usage extension must be absent or include the "web
627           server authentication" and/or one of the SGC OIDs.  keyUsage must
628           be absent or it must have the digitalSignature, the keyEncipherment
629           set or both bits set.  Netscape certificate type must be absent or
630           have the SSL server bit set.
631
632       SSL Server CA
633           The extended key usage extension must be absent or include the "web
634           server authentication" and/or one of the SGC OIDs.  Netscape
635           certificate type must be absent or the SSL CA bit must be set: this
636           is used as a work around if the basicConstraints extension is
637           absent.
638
639       Netscape SSL Server
640           For Netscape SSL clients to connect to an SSL server it must have
641           the keyEncipherment bit set if the keyUsage extension is present.
642           This isn't always valid because some cipher suites use the key for
643           digital signing.  Otherwise it is the same as a normal SSL server.
644
645       Common S/MIME Client Tests
646           The extended key usage extension must be absent or include the
647           "email protection" OID. Netscape certificate type must be absent or
648           should have the S/MIME bit set. If the S/MIME bit is not set in
649           netscape certificate type then the SSL client bit is tolerated as
650           an alternative but a warning is shown: this is because some
651           Verisign certificates don't set the S/MIME bit.
652
653       S/MIME Signing
654           In addition to the common S/MIME client tests the digitalSignature
655           bit must be set if the keyUsage extension is present.
656
657       S/MIME Encryption
658           In addition to the common S/MIME tests the keyEncipherment bit must
659           be set if the keyUsage extension is present.
660
661       S/MIME CA
662           The extended key usage extension must be absent or include the
663           "email protection" OID. Netscape certificate type must be absent or
664           must have the S/MIME CA bit set: this is used as a work around if
665           the basicConstraints extension is absent.
666
667       CRL Signing
668           The keyUsage extension must be absent or it must have the CRL
669           signing bit set.
670
671       CRL Signing CA
672           The normal CA tests apply. Except in this case the basicConstraints
673           extension must be present.
674

BUGS

676       Extensions in certificates are not transferred to certificate requests
677       and vice versa.
678
679       It is possible to produce invalid certificates or requests by
680       specifying the wrong private key or using inconsistent options in some
681       cases: these should be checked.
682
683       There should be options to explicitly set such things as start and end
684       dates rather than an offset from the current time.
685
686       The code to implement the verify behaviour described in the TRUST
687       SETTINGS is currently being developed. It thus describes the intended
688       behaviour rather than the current behaviour. It is hoped that it will
689       represent reality in OpenSSL 0.9.5 and later.
690

SEE ALSO

692       req(1), ca(1), genrsa(1), gendsa(1), verify(1), x509v3_config(5)
693

HISTORY

695       Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
696
697       The hash algorithm used in the -subject_hash and -issuer_hash options
698       before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the
699       encoding of the distinguished name. In OpenSSL 1.0.0 and later it is
700       based on a canonical version of the DN using SHA1. This means that any
701       directories using the old form must have their links rebuilt using
702       c_rehash or similar.
703
704
705
7061.0.1e                            2017-03-22                           X509(1)
Impressum