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] [-subject]
12 [-issuer] [-nameopt option] [-email] [-ocsp_uri] [-startdate]
13 [-enddate] [-purpose] [-dates] [-modulus] [-fingerprint] [-alias]
14 [-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
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 Since there are a large number of options they will split up into
28 various sections.
29
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 -outform DER|PEM|NET
41 This specifies the output format, the options have the same meaning
42 as the -inform option.
43 -in filename
45 This specifies the input filename to read a certificate from or
46 standard input if this option is not specified.
47 -out filename
49 This specifies the output filename to write to or standard output
50 by default.
51 -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 -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 DISPLAY OPTIONS
67 Note: the -alias and -purpose options are also display options but are
68 described in the TRUST SETTINGS section.
69 -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 -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 -noout
82 this option prevents output of the encoded version of the request.
83 -modulus
85 this option prints out the value of the modulus of the public key
86 contained in the certificate.
87 -serial
89 outputs the certificate serial number.
90 -subject_hash
92 outputs the "hash" of the certificate subject name. This is used in
93 OpenSSL to form an index to allow certificates in a directory to be
94 looked up by subject name.
95 -issuer_hash
97 outputs the "hash" of the certificate issuer name.
98 -hash
100 synonym for "-subject_hash" for backward compatibility reasons.
101 -subject_hash_old
103 outputs the "hash" of the certificate subject name using the older
104 algorithm as used by OpenSSL versions before 1.0.0.
105 -issuer_hash_old
107 outputs the "hash" of the certificate issuer name using the older
108 algorithm as used by OpenSSL versions before 1.0.0.
109 -subject
111 outputs the subject name.
112 -issuer
114 outputs the issuer name.
115 -nameopt option
117 option which determines how the subject or issuer names are
118 displayed. The option argument can be a single option or multiple
119 options separated by commas. Alternatively the -nameopt switch may
120 be used more than once to set multiple options. See the NAME
121 OPTIONS section for more information.
122 -email
124 outputs the email address(es) if any.
125 -ocsp_uri
127 outputs the OCSP responder address(es) if any.
128 -startdate
130 prints out the start date of the certificate, that is the notBefore
131 date.
132 -enddate
134 prints out the expiry date of the certificate, that is the notAfter
135 date.
136 -dates
138 prints out the start and expiry dates of a certificate.
139 -fingerprint
141 prints out the digest of the DER encoded version of the whole
142 certificate (see digest options).
143 -C this outputs the certificate in the form of a C source file.
145 TRUST SETTINGS
147 Please note these options are currently experimental and may well
148 change.
149 A trusted certificate is an ordinary certificate which has several
151 additional pieces of information attached to it such as the permitted
152 and prohibited uses of the certificate and an "alias".
153 Normally when a certificate is being verified at least one certificate
155 must be "trusted". By default a trusted certificate must be stored
156 locally and must be a root CA: any certificate chain ending in this CA
157 is then usable for any purpose.
158 Trust settings currently are only used with a root CA. They allow a
160 finer control over the purposes the root CA can be used for. For
161 example a CA may be trusted for SSL client but not SSL server use.
162 See the description of the verify utility for more information on the
164 meaning of trust settings.
165 Future versions of OpenSSL will recognize trust settings on any
167 certificate: not just root CAs.
168 -trustout
170 this causes x509 to output a trusted certificate. An ordinary or
171 trusted certificate can be input but by default an ordinary
172 certificate is output and any trust settings are discarded. With
173 the -trustout option a trusted certificate is output. A trusted
174 certificate is automatically output if any trust settings are
175 modified.
176 -setalias arg
178 sets the alias of the certificate. This will allow the certificate
179 to be referred to using a nickname for example "Steve's
180 Certificate".
181 -alias
183 outputs the certificate alias, if any.
184 -clrtrust
186 clears all the permitted or trusted uses of the certificate.
187 -clrreject
189 clears all the prohibited or rejected uses of the certificate.
190 -addtrust arg
192 adds a trusted certificate use. Any object name can be used here
193 but currently only clientAuth (SSL client use), serverAuth (SSL
194 server use) and emailProtection (S/MIME email) are used. Other
195 OpenSSL applications may define additional uses.
196 -addreject arg
198 adds a prohibited use. It accepts the same values as the -addtrust
199 option.
200 -purpose
202 this option performs tests on the certificate extensions and
203 outputs the results. For a more complete description see the
204 CERTIFICATE EXTENSIONS section.
205 SIGNING OPTIONS
207 The x509 utility can be used to sign certificates and requests: it can
208 thus behave like a "mini CA".
209 -signkey filename
211 this option causes the input file to be self signed using the
212 supplied private key.
213 If the input file is a certificate it sets the issuer name to the
215 subject name (i.e. makes it self signed) changes the public key to
216 the supplied value and changes the start and end dates. The start
217 date is set to the current time and the end date is set to a value
218 determined by the -days option. Any certificate extensions are
219 retained unless the -clrext option is supplied.
220 If the input is a certificate request then a self signed
222 certificate is created using the supplied private key using the
223 subject name in the request.
224 -clrext
226 delete any extensions from a certificate. This option is used when
227 a certificate is being created from another certificate (for
228 example with the -signkey or the -CA options). Normally all
229 extensions are retained.
230 -keyform PEM|DER
232 specifies the format (DER or PEM) of the private key file used in
233 the -signkey option.
234 -days arg
236 specifies the number of days to make a certificate valid for. The
237 default is 30 days.
238 -x509toreq
240 converts a certificate into a certificate request. The -signkey
241 option is used to pass the required private key.
242 -req
244 by default a certificate is expected on input. With this option a
245 certificate request is expected instead.
246 -set_serial n
248 specifies the serial number to use. This option can be used with
249 either the -signkey or -CA options. If used in conjunction with the
250 -CA option the serial number file (as specified by the -CAserial or
251 -CAcreateserial options) is not used.
252 The serial number can be decimal or hex (if preceded by 0x).
254 Negative serial numbers can also be specified but their use is not
255 recommended.
256 -CA filename
258 specifies the CA certificate to be used for signing. When this
259 option is present x509 behaves like a "mini CA". The input file is
260 signed by this CA using this option: that is its issuer name is set
261 to the subject name of the CA and it is digitally signed using the
262 CAs private key.
263 This option is normally combined with the -req option. Without the
265 -req option the input is a certificate which must be self signed.
266 -CAkey filename
268 sets the CA private key to sign a certificate with. If this option
269 is not specified then it is assumed that the CA private key is
270 present in the CA certificate file.
271 -CAserial filename
273 sets the CA serial number file to use.
274 When the -CA option is used to sign a certificate it uses a serial
276 number specified in a file. This file consist of one line
277 containing an even number of hex digits with the serial number to
278 use. After each use the serial number is incremented and written
279 out to the file again.
280 The default filename consists of the CA certificate file base name
282 with ".srl" appended. For example if the CA certificate file is
283 called "mycacert.pem" it expects to find a serial number file
284 called "mycacert.srl".
285 -CAcreateserial
287 with this option the CA serial number file is created if it does
288 not exist: it will contain the serial number "02" and the
289 certificate being signed will have the 1 as its serial number.
290 Normally if the -CA option is specified and the serial number file
291 does not exist it is an error.
292 -extfile filename
294 file containing certificate extensions to use. If not specified
295 then no extensions are added to the certificate.
296 -extensions section
298 the section to add certificate extensions from. If this option is
299 not specified then the extensions should either be contained in the
300 unnamed (default) section or the default section should contain a
301 variable called "extensions" which contains the section to use. See
302 the x509v3_config(5) manual page for details of the extension
303 section format.
304 NAME OPTIONS
306 The nameopt command line switch determines how the subject and issuer
307 names are displayed. If no nameopt switch is present the default
308 "oneline" format is used which is compatible with previous versions of
309 OpenSSL. Each option is described in detail below, all options can be
310 preceded by a - to turn the option off. Only the first four will
311 normally be used.
312 compat
314 use the old format. This is equivalent to specifying no name
315 options at all.
316 RFC2253
318 displays names compatible with RFC2253 equivalent to esc_2253,
319 esc_ctrl, esc_msb, utf8, dump_nostr, dump_unknown, dump_der,
320 sep_comma_plus, dn_rev and sname.
321 oneline
323 a oneline format which is more readable than RFC2253. It is
324 equivalent to specifying the esc_2253, esc_ctrl, esc_msb, utf8,
325 dump_nostr, dump_der, use_quote, sep_comma_plus_space, space_eq and
326 sname options.
327 multiline
329 a multiline format. It is equivalent esc_ctrl, esc_msb,
330 sep_multiline, space_eq, lname and align.
331 esc_2253
333 escape the "special" characters required by RFC2253 in a field That
334 is ,+"<>;. Additionally # is escaped at the beginning of a string
335 and a space character at the beginning or end of a string.
336 esc_ctrl
338 escape control characters. That is those with ASCII values less
339 than 0x20 (space) and the delete (0x7f) character. They are escaped
340 using the RFC2253 \XX notation (where XX are two hex digits
341 representing the character value).
342 esc_msb
344 escape characters with the MSB set, that is with ASCII values
345 larger than 127.
346 use_quote
348 escapes some characters by surrounding the whole string with "
349 characters, without the option all escaping is done with the \
350 character.
351 utf8
353 convert all strings to UTF8 format first. This is required by
354 RFC2253. If you are lucky enough to have a UTF8 compatible terminal
355 then the use of this option (and not setting esc_msb) may result in
356 the correct display of multibyte (international) characters. Is
357 this option is not present then multibyte characters larger than
358 0xff will be represented using the format \UXXXX for 16 bits and
359 \WXXXXXXXX for 32 bits. Also if this option is off any UTF8Strings
360 will be converted to their character form first.
361 no_type
363 this option does not attempt to interpret multibyte characters in
364 any way. That is their content octets are merely dumped as though
365 one octet represents each character. This is useful for diagnostic
366 purposes but will result in rather odd looking output.
367 show_type
369 show the type of the ASN1 character string. The type precedes the
370 field contents. For example "BMPSTRING: Hello World".
371 dump_der
373 when this option is set any fields that need to be hexdumped will
374 be dumped using the DER encoding of the field. Otherwise just the
375 content octets will be displayed. Both options use the RFC2253
376 #XXXX... format.
377 dump_nostr
379 dump non character string types (for example OCTET STRING) if this
380 option is not set then non character string types will be displayed
381 as though each content octet represents a single character.
382 dump_all
384 dump all fields. This option when used with dump_der allows the DER
385 encoding of the structure to be unambiguously determined.
386 dump_unknown
388 dump any field whose OID is not recognised by OpenSSL.
389 sep_comma_plus, sep_comma_plus_space, sep_semi_plus_space,
391 sep_multiline
392 these options determine the field separators. The first character
393 is between RDNs and the second between multiple AVAs (multiple AVAs
394 are very rare and their use is discouraged). The options ending in
395 "space" additionally place a space after the separator to make it
396 more readable. The sep_multiline uses a linefeed character for the
397 RDN separator and a spaced + for the AVA separator. It also indents
398 the fields by four characters.
399 dn_rev
401 reverse the fields of the DN. This is required by RFC2253. As a
402 side effect this also reverses the order of multiple AVAs but this
403 is permissible.
404 nofname, sname, lname, oid
406 these options alter how the field name is displayed. nofname does
407 not display the field at all. sname uses the "short name" form (CN
408 for commonName for example). lname uses the long form. oid
409 represents the OID in numerical form and is useful for diagnostic
410 purpose.
411 align
413 align field values for a more readable output. Only usable with
414 sep_multiline.
415 space_eq
417 places spaces round the = character which follows the field name.
418 TEXT OPTIONS
420 As well as customising the name output format, it is also possible to
421 customise the actual fields printed using the certopt options when the
422 text option is present. The default behaviour is to print all fields.
423 compatible
425 use the old format. This is equivalent to specifying no output
426 options at all.
427 no_header
429 don't print header information: that is the lines saying
430 "Certificate" and "Data".
431 no_version
433 don't print out the version number.
434 no_serial
436 don't print out the serial number.
437 no_signame
439 don't print out the signature algorithm used.
440 no_validity
442 don't print the validity, that is the notBefore and notAfter
443 fields.
444 no_subject
446 don't print out the subject name.
447 no_issuer
449 don't print out the issuer name.
450 no_pubkey
452 don't print out the public key.
453 no_sigdump
455 don't give a hexadecimal dump of the certificate signature.
456 no_aux
458 don't print out certificate trust information.
459 no_extensions
461 don't print out any X509V3 extensions.
462 ext_default
464 retain default extension behaviour: attempt to print out
465 unsupported certificate extensions.
466 ext_error
468 print an error message for unsupported certificate extensions.
469 ext_parse
471 ASN1 parse unsupported extensions.
472 ext_dump
474 hex dump unsupported extensions.
475 ca_default
477 the value used by the ca utility, equivalent to no_issuer,
478 no_pubkey, no_header, no_version, no_sigdump and no_signame.
479
481 Note: in these examples the '\' means the example should be all on one
482 line.
483 Display the contents of a certificate:
485 openssl x509 -in cert.pem -noout -text
487 Display the certificate serial number:
489 openssl x509 -in cert.pem -noout -serial
491 Display the certificate subject name:
493 openssl x509 -in cert.pem -noout -subject
495 Display the certificate subject name in RFC2253 form:
497 openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
499 Display the certificate subject name in oneline form on a terminal
501 supporting UTF8:
502 openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
504 Display the certificate MD5 fingerprint:
506 openssl x509 -in cert.pem -noout -fingerprint
508 Display the certificate SHA1 fingerprint:
510 openssl x509 -sha1 -in cert.pem -noout -fingerprint
512 Convert a certificate from PEM to DER format:
514 openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
516 Convert a certificate to a certificate request:
518 openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
520 Convert a certificate request into a self signed certificate using
522 extensions for a CA:
523 openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
525 -signkey key.pem -out cacert.pem
526 Sign a certificate request using the CA certificate above and add user
528 certificate extensions:
529 openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
531 -CA cacert.pem -CAkey key.pem -CAcreateserial
532 Set a certificate to be trusted for SSL client use and change set its
534 alias to "Steve's Class 1 CA"
535 openssl x509 -in cert.pem -addtrust clientAuth \
537 -setalias "Steve's Class 1 CA" -out trust.pem
538
540 The PEM format uses the header and footer lines:
541 -----BEGIN CERTIFICATE-----
543 -----END CERTIFICATE-----
544 it will also handle files containing:
546 -----BEGIN X509 CERTIFICATE-----
548 -----END X509 CERTIFICATE-----
549 Trusted certificates have the lines
551 -----BEGIN TRUSTED CERTIFICATE-----
553 -----END TRUSTED CERTIFICATE-----
554 The conversion to UTF8 format used with the name options assumes that
556 T61Strings use the ISO8859-1 character set. This is wrong but Netscape
557 and MSIE do this as do many certificates. So although this is incorrect
558 it is more likely to display the majority of certificates correctly.
559 The -fingerprint option takes the digest of the DER encoded
561 certificate. This is commonly called a "fingerprint". Because of the
562 nature of message digests the fingerprint of a certificate is unique to
563 that certificate and two certificates with the same fingerprint can be
564 considered to be the same.
565 The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
567 The -email option searches the subject name and the subject alternative
569 name extension. Only unique email addresses will be printed out: it
570 will not print the same address more than once.
571
573 The -purpose option checks the certificate extensions and determines
574 what the certificate can be used for. The actual checks done are rather
575 complex and include various hacks and workarounds to handle broken
576 certificates and software.
577 The same code is used when verifying untrusted certificates in chains
579 so this section is useful if a chain is rejected by the verify code.
580 The basicConstraints extension CA flag is used to determine whether the
582 certificate can be used as a CA. If the CA flag is true then it is a
583 CA, if the CA flag is false then it is not a CA. All CAs should have
584 the CA flag set to true.
585 If the basicConstraints extension is absent then the certificate is
587 considered to be a "possible CA" other extensions are checked according
588 to the intended use of the certificate. A warning is given in this case
589 because the certificate should really not be regarded as a CA: however
590 it is allowed to be a CA to work around some broken software.
591 If the certificate is a V1 certificate (and thus has no extensions) and
593 it is self signed it is also assumed to be a CA but a warning is again
594 given: this is to work around the problem of Verisign roots which are
595 V1 self signed certificates.
596 If the keyUsage extension is present then additional restraints are
598 made on the uses of the certificate. A CA certificate must have the
599 keyCertSign bit set if the keyUsage extension is present.
600 The extended key usage extension places additional restrictions on the
602 certificate uses. If this extension is present (whether critical or
603 not) the key can only be used for the purposes specified.
604 A complete description of each test is given below. The comments about
606 basicConstraints and keyUsage and V1 certificates above apply to all CA
607 certificates.
608 SSL Client
610 The extended key usage extension must be absent or include the "web
611 client authentication" OID. keyUsage must be absent or it must
612 have the digitalSignature bit set. Netscape certificate type must
613 be absent or it must have the SSL client bit set.
614 SSL Client CA
616 The extended key usage extension must be absent or include the "web
617 client authentication" OID. Netscape certificate type must be
618 absent or it must have the SSL CA bit set: this is used as a work
619 around if the basicConstraints extension is absent.
620 SSL Server
622 The extended key usage extension must be absent or include the "web
623 server authentication" and/or one of the SGC OIDs. keyUsage must
624 be absent or it must have the digitalSignature, the keyEncipherment
625 set or both bits set. Netscape certificate type must be absent or
626 have the SSL server bit set.
627 SSL Server CA
629 The extended key usage extension must be absent or include the "web
630 server authentication" and/or one of the SGC OIDs. Netscape
631 certificate type must be absent or the SSL CA bit must be set: this
632 is used as a work around if the basicConstraints extension is
633 absent.
634 Netscape SSL Server
636 For Netscape SSL clients to connect to an SSL server it must have
637 the keyEncipherment bit set if the keyUsage extension is present.
638 This isn't always valid because some cipher suites use the key for
639 digital signing. Otherwise it is the same as a normal SSL server.
640 Common S/MIME Client Tests
642 The extended key usage extension must be absent or include the
643 "email protection" OID. Netscape certificate type must be absent or
644 should have the S/MIME bit set. If the S/MIME bit is not set in
645 netscape certificate type then the SSL client bit is tolerated as
646 an alternative but a warning is shown: this is because some
647 Verisign certificates don't set the S/MIME bit.
648 S/MIME Signing
650 In addition to the common S/MIME client tests the digitalSignature
651 bit must be set if the keyUsage extension is present.
652 S/MIME Encryption
654 In addition to the common S/MIME tests the keyEncipherment bit must
655 be set if the keyUsage extension is present.
656 S/MIME CA
658 The extended key usage extension must be absent or include the
659 "email protection" OID. Netscape certificate type must be absent or
660 must have the S/MIME CA bit set: this is used as a work around if
661 the basicConstraints extension is absent.
662 CRL Signing
664 The keyUsage extension must be absent or it must have the CRL
665 signing bit set.
666 CRL Signing CA
668 The normal CA tests apply. Except in this case the basicConstraints
669 extension must be present.
670
672 Extensions in certificates are not transferred to certificate requests
673 and vice versa.
674 It is possible to produce invalid certificates or requests by
676 specifying the wrong private key or using inconsistent options in some
677 cases: these should be checked.
678 There should be options to explicitly set such things as start and end
680 dates rather than an offset from the current time.
681 The code to implement the verify behaviour described in the TRUST
683 SETTINGS is currently being developed. It thus describes the intended
684 behaviour rather than the current behaviour. It is hoped that it will
685 represent reality in OpenSSL 0.9.5 and later.
686
688 req(1), ca(1), genrsa(1), gendsa(1), verify(1), x509v3_config(5)
689
691 Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
692 The hash algorithm used in the -subject_hash and -issuer_hash options
694 before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the
695 encoding of the distinguished name. In OpenSSL 1.0.0 and later it is
696 based on a canonical version of the DN using SHA1. This means that any
697 directories using the old form must have their links rebuilt using
698 c_rehash or similar.
6991.0.0e 2011-09-07 X509(1)