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] [-startdate] [-enddate] [-purpose]
13 [-dates] [-modulus] [-fingerprint] [-alias] [-noout] [-trustout]
14 [-clrtrust] [-clrreject] [-addtrust arg] [-addreject arg] [-setalias
15 arg] [-days arg] [-set_serial n] [-signkey filename] [-x509toreq]
16 [-req] [-CA filename] [-CAkey filename] [-CAcreateserial] [-CAserial
17 filename] [-text] [-C] [-md2⎪-md5⎪-sha1⎪-mdc2] [-clrext] [-extfile
18 filename] [-extensions section] [-engine id]
19
21 The x509 command is a multi purpose certificate utility. It can be used
22 to display certificate information, convert certificates to various
23 forms, sign certificate requests like a "mini CA" or edit certificate
24 trust settings.
25 Since there are a large number of options they will split up into vari‐
27 ous sections.
28
30 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
31 -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.
58 -engine id
60 specifying an engine (by it's unique id string) will cause req to
61 attempt to obtain a functional reference to the specified engine,
62 thus initialising it if needed. The engine will then be set as the
63 default for all available algorithms.
64 DISPLAY OPTIONS
66 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 "-hash" for backward compatibility reasons.
101 -subject
103 outputs the subject name.
104 -issuer
106 outputs the issuer name.
107 -nameopt option
109 option which determines how the subject or issuer names are dis‐
110 played. The option argument can be a single option or multiple
111 options separated by commas. Alternatively the -nameopt switch may
112 be used more than once to set multiple options. See the NAME
113 OPTIONS section for more information.
114 -email
116 outputs the email address(es) if any.
117 -startdate
119 prints out the start date of the certificate, that is the notBefore
120 date.
121 -enddate
123 prints out the expiry date of the certificate, that is the notAfter
124 date.
125 -dates
127 prints out the start and expiry dates of a certificate.
128 -fingerprint
130 prints out the digest of the DER encoded version of the whole cer‐
131 tificate (see digest options).
132 -C this outputs the certificate in the form of a C source file.
134 TRUST SETTINGS
136 Please note these options are currently experimental and may well
138 change.
139 A trusted certificate is an ordinary certificate which has several
141 additional pieces of information attached to it such as the permitted
142 and prohibited uses of the certificate and an "alias".
143 Normally when a certificate is being verified at least one certificate
145 must be "trusted". By default a trusted certificate must be stored
146 locally and must be a root CA: any certificate chain ending in this CA
147 is then usable for any purpose.
148 Trust settings currently are only used with a root CA. They allow a
150 finer control over the purposes the root CA can be used for. For exam‐
151 ple a CA may be trusted for SSL client but not SSL server use.
152 See the description of the verify utility for more information on the
154 meaning of trust settings.
155 Future versions of OpenSSL will recognize trust settings on any cer‐
157 tificate: not just root CAs.
158 -trustout
160 this causes x509 to output a trusted certificate. An ordinary or
161 trusted certificate can be input but by default an ordinary cer‐
162 tificate is output and any trust settings are discarded. With the
163 -trustout option a trusted certificate is output. A trusted cer‐
164 tificate is automatically output if any trust settings are modi‐
165 fied.
166 -setalias arg
168 sets the alias of the certificate. This will allow the certificate
169 to be referred to using a nickname for example "Steve's Certifi‐
170 cate".
171 -alias
173 outputs the certificate alias, if any.
174 -clrtrust
176 clears all the permitted or trusted uses of the certificate.
177 -clrreject
179 clears all the prohibited or rejected uses of the certificate.
180 -addtrust arg
182 adds a trusted certificate use. Any object name can be used here
183 but currently only clientAuth (SSL client use), serverAuth (SSL
184 server use) and emailProtection (S/MIME email) are used. Other
185 OpenSSL applications may define additional uses.
186 -addreject arg
188 adds a prohibited use. It accepts the same values as the -addtrust
189 option.
190 -purpose
192 this option performs tests on the certificate extensions and out‐
193 puts the results. For a more complete description see the CERTIFI‐
194 CATE EXTENSIONS section.
195 SIGNING OPTIONS
197 The x509 utility can be used to sign certificates and requests: it can
199 thus behave like a "mini CA".
200 -signkey filename
202 this option causes the input file to be self signed using the sup‐
203 plied private key.
204 If the input file is a certificate it sets the issuer name to the
206 subject name (i.e. makes it self signed) changes the public key to
207 the supplied value and changes the start and end dates. The start
208 date is set to the current time and the end date is set to a value
209 determined by the -days option. Any certificate extensions are
210 retained unless the -clrext option is supplied.
211 If the input is a certificate request then a self signed certifi‐
213 cate is created using the supplied private key using the subject
214 name in the request.
215 -clrext
217 delete any extensions from a certificate. This option is used when
218 a certificate is being created from another certificate (for exam‐
219 ple with the -signkey or the -CA options). Normally all extensions
220 are retained.
221 -keyform PEM⎪DER
223 specifies the format (DER or PEM) of the private key file used in
224 the -signkey option.
225 -days arg
227 specifies the number of days to make a certificate valid for. The
228 default is 30 days.
229 -x509toreq
231 converts a certificate into a certificate request. The -signkey
232 option is used to pass the required private key.
233 -req
235 by default a certificate is expected on input. With this option a
236 certificate request is expected instead.
237 -set_serial n
239 specifies the serial number to use. This option can be used with
240 either the -signkey or -CA options. If used in conjunction with the
241 -CA option the serial number file (as specified by the -CAserial or
242 -CAcreateserial options) is not used.
243 The serial number can be decimal or hex (if preceded by 0x). Nega‐
245 tive serial numbers can also be specified but their use is not rec‐
246 ommended.
247 -CA filename
249 specifies the CA certificate to be used for signing. When this
250 option is present x509 behaves like a "mini CA". The input file is
251 signed by this CA using this option: that is its issuer name is set
252 to the subject name of the CA and it is digitally signed using the
253 CAs private key.
254 This option is normally combined with the -req option. Without the
256 -req option the input is a certificate which must be self signed.
257 -CAkey filename
259 sets the CA private key to sign a certificate with. If this option
260 is not specified then it is assumed that the CA private key is
261 present in the CA certificate file.
262 -CAserial filename
264 sets the CA serial number file to use.
265 When the -CA option is used to sign a certificate it uses a serial
267 number specified in a file. This file consist of one line contain‐
268 ing an even number of hex digits with the serial number to use.
269 After each use the serial number is incremented and written out to
270 the file again.
271 The default filename consists of the CA certificate file base name
273 with ".srl" appended. For example if the CA certificate file is
274 called "mycacert.pem" it expects to find a serial number file
275 called "mycacert.srl".
276 -CAcreateserial
278 with this option the CA serial number file is created if it does
279 not exist: it will contain the serial number "02" and the certifi‐
280 cate being signed will have the 1 as its serial number. Normally if
281 the -CA option is specified and the serial number file does not
282 exist it is an error.
283 -extfile filename
285 file containing certificate extensions to use. If not specified
286 then no extensions are added to the certificate.
287 -extensions section
289 the section to add certificate extensions from. If this option is
290 not specified then the extensions should either be contained in the
291 unnamed (default) section or the default section should contain a
292 variable called "extensions" which contains the section to use.
293 NAME OPTIONS
295 The nameopt command line switch determines how the subject and issuer
297 names are displayed. If no nameopt switch is present the default "one‐
298 line" format is used which is compatible with previous versions of
299 OpenSSL. Each option is described in detail below, all options can be
300 preceded by a - to turn the option off. Only the first four will nor‐
301 mally be used.
302 compat
304 use the old format. This is equivalent to specifying no name
305 options at all.
306 RFC2253
308 displays names compatible with RFC2253 equivalent to esc_2253,
309 esc_ctrl, esc_msb, utf8, dump_nostr, dump_unknown, dump_der,
310 sep_comma_plus, dn_rev and sname.
311 oneline
313 a oneline format which is more readable than RFC2253. It is equiva‐
314 lent to specifying the esc_2253, esc_ctrl, esc_msb, utf8,
315 dump_nostr, dump_der, use_quote, sep_comma_plus_spc, spc_eq and
316 sname options.
317 multiline
319 a multiline format. It is equivalent esc_ctrl, esc_msb, sep_multi‐
320 line, spc_eq, lname and align.
321 esc_2253
323 escape the "special" characters required by RFC2253 in a field That
324 is ,+"<>;. Additionally # is escaped at the beginning of a string
325 and a space character at the beginning or end of a string.
326 esc_ctrl
328 escape control characters. That is those with ASCII values less
329 than 0x20 (space) and the delete (0x7f) character. They are escaped
330 using the RFC2253 \XX notation (where XX are two hex digits repre‐
331 senting the character value).
332 esc_msb
334 escape characters with the MSB set, that is with ASCII values
335 larger than 127.
336 use_quote
338 escapes some characters by surrounding the whole string with "
339 characters, without the option all escaping is done with the \
340 character.
341 utf8
343 convert all strings to UTF8 format first. This is required by
344 RFC2253. If you are lucky enough to have a UTF8 compatible terminal
345 then the use of this option (and not setting esc_msb) may result in
346 the correct display of multibyte (international) characters. Is
347 this option is not present then multibyte characters larger than
348 0xff will be represented using the format \UXXXX for 16 bits and
349 \WXXXXXXXX for 32 bits. Also if this option is off any UTF8Strings
350 will be converted to their character form first.
351 no_type
353 this option does not attempt to interpret multibyte characters in
354 any way. That is their content octets are merely dumped as though
355 one octet represents each character. This is useful for diagnostic
356 purposes but will result in rather odd looking output.
357 show_type
359 show the type of the ASN1 character string. The type precedes the
360 field contents. For example "BMPSTRING: Hello World".
361 dump_der
363 when this option is set any fields that need to be hexdumped will
364 be dumped using the DER encoding of the field. Otherwise just the
365 content octets will be displayed. Both options use the RFC2253
366 #XXXX... format.
367 dump_nostr
369 dump non character string types (for example OCTET STRING) if this
370 option is not set then non character string types will be displayed
371 as though each content octet represents a single character.
372 dump_all
374 dump all fields. This option when used with dump_der allows the DER
375 encoding of the structure to be unambiguously determined.
376 dump_unknown
378 dump any field whose OID is not recognised by OpenSSL.
379 sep_comma_plus, sep_comma_plus_space, sep_semi_plus_space, sep_multi‐
381 line
382 these options determine the field separators. The first character
383 is between RDNs and the second between multiple AVAs (multiple AVAs
384 are very rare and their use is discouraged). The options ending in
385 "space" additionally place a space after the separator to make it
386 more readable. The sep_multiline uses a linefeed character for the
387 RDN separator and a spaced + for the AVA separator. It also indents
388 the fields by four characters.
389 dn_rev
391 reverse the fields of the DN. This is required by RFC2253. As a
392 side effect this also reverses the order of multiple AVAs but this
393 is permissible.
394 nofname, sname, lname, oid
396 these options alter how the field name is displayed. nofname does
397 not display the field at all. sname uses the "short name" form (CN
398 for commonName for example). lname uses the long form. oid repre‐
399 sents the OID in numerical form and is useful for diagnostic pur‐
400 pose.
401 align
403 align field values for a more readable output. Only usable with
404 sep_multiline.
405 spc_eq
407 places spaces round the = character which follows the field name.
408 TEXT OPTIONS
410 As well as customising the name output format, it is also possible to
412 customise the actual fields printed using the certopt options when the
413 text option is present. The default behaviour is to print all fields.
414 compatible
416 use the old format. This is equivalent to specifying no output
417 options at all.
418 no_header
420 don't print header information: that is the lines saying "Certifi‐
421 cate" and "Data".
422 no_version
424 don't print out the version number.
425 no_serial
427 don't print out the serial number.
428 no_signame
430 don't print out the signature algorithm used.
431 no_validity
433 don't print the validity, that is the notBefore and notAfter
434 fields.
435 no_subject
437 don't print out the subject name.
438 no_issuer
440 don't print out the issuer name.
441 no_pubkey
443 don't print out the public key.
444 no_sigdump
446 don't give a hexadecimal dump of the certificate signature.
447 no_aux
449 don't print out certificate trust information.
450 no_extensions
452 don't print out any X509V3 extensions.
453 ext_default
455 retain default extension behaviour: attempt to print out unsup‐
456 ported certificate extensions.
457 ext_error
459 print an error message for unsupported certificate extensions.
460 ext_parse
462 ASN1 parse unsupported extensions.
463 ext_dump
465 hex dump unsupported extensions.
466 ca_default
468 the value used by the ca utility, equivalent to no_issuer, no_pub‐
469 key, no_header, no_version, no_sigdump and no_signame.
470
472 Note: in these examples the '\' means the example should be all on one
473 line.
474 Display the contents of a certificate:
476 openssl x509 -in cert.pem -noout -text
478 Display the certificate serial number:
480 openssl x509 -in cert.pem -noout -serial
482 Display the certificate subject name:
484 openssl x509 -in cert.pem -noout -subject
486 Display the certificate subject name in RFC2253 form:
488 openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
490 Display the certificate subject name in oneline form on a terminal sup‐
492 porting UTF8:
493 openssl x509 -in cert.pem -noout -subject -nameopt oneline,-escmsb
495 Display the certificate MD5 fingerprint:
497 openssl x509 -in cert.pem -noout -fingerprint
499 Display the certificate SHA1 fingerprint:
501 openssl x509 -sha1 -in cert.pem -noout -fingerprint
503 Convert a certificate from PEM to DER format:
505 openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
507 Convert a certificate to a certificate request:
509 openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
511 Convert a certificate request into a self signed certificate using
513 extensions for a CA:
514 openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
516 -signkey key.pem -out cacert.pem
517 Sign a certificate request using the CA certificate above and add user
519 certificate extensions:
520 openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
522 -CA cacert.pem -CAkey key.pem -CAcreateserial
523 Set a certificate to be trusted for SSL client use and change set its
525 alias to "Steve's Class 1 CA"
526 openssl x509 -in cert.pem -addtrust clientAuth \
528 -setalias "Steve's Class 1 CA" -out trust.pem
529
531 The PEM format uses the header and footer lines:
532 -----BEGIN CERTIFICATE-----
534 -----END CERTIFICATE-----
535 it will also handle files containing:
537 -----BEGIN X509 CERTIFICATE-----
539 -----END X509 CERTIFICATE-----
540 Trusted certificates have the lines
542 -----BEGIN TRUSTED CERTIFICATE-----
544 -----END TRUSTED CERTIFICATE-----
545 The conversion to UTF8 format used with the name options assumes that
547 T61Strings use the ISO8859-1 character set. This is wrong but Netscape
548 and MSIE do this as do many certificates. So although this is incorrect
549 it is more likely to display the majority of certificates correctly.
550 The -fingerprint option takes the digest of the DER encoded certifi‐
552 cate. This is commonly called a "fingerprint". Because of the nature
553 of message digests the fingerprint of a certificate is unique to that
554 certificate and two certificates with the same fingerprint can be con‐
555 sidered to be the same.
556 The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
558 The -email option searches the subject name and the subject alternative
560 name extension. Only unique email addresses will be printed out: it
561 will not print the same address more than once.
562
564 The -purpose option checks the certificate extensions and determines
565 what the certificate can be used for. The actual checks done are rather
566 complex and include various hacks and workarounds to handle broken cer‐
567 tificates and software.
568 The same code is used when verifying untrusted certificates in chains
570 so this section is useful if a chain is rejected by the verify code.
571 The basicConstraints extension CA flag is used to determine whether the
573 certificate can be used as a CA. If the CA flag is true then it is a
574 CA, if the CA flag is false then it is not a CA. All CAs should have
575 the CA flag set to true.
576 If the basicConstraints extension is absent then the certificate is
578 considered to be a "possible CA" other extensions are checked according
579 to the intended use of the certificate. A warning is given in this case
580 because the certificate should really not be regarded as a CA: however
581 it is allowed to be a CA to work around some broken software.
582 If the certificate is a V1 certificate (and thus has no extensions) and
584 it is self signed it is also assumed to be a CA but a warning is again
585 given: this is to work around the problem of Verisign roots which are
586 V1 self signed certificates.
587 If the keyUsage extension is present then additional restraints are
589 made on the uses of the certificate. A CA certificate must have the
590 keyCertSign bit set if the keyUsage extension is present.
591 The extended key usage extension places additional restrictions on the
593 certificate uses. If this extension is present (whether critical or
594 not) the key can only be used for the purposes specified.
595 A complete description of each test is given below. The comments about
597 basicConstraints and keyUsage and V1 certificates above apply to all CA
598 certificates.
599 SSL Client
601 The extended key usage extension must be absent or include the "web
602 client authentication" OID. keyUsage must be absent or it must
603 have the digitalSignature bit set. Netscape certificate type must
604 be absent or it must have the SSL client bit set.
605 SSL Client CA
607 The extended key usage extension must be absent or include the "web
608 client authentication" OID. Netscape certificate type must be
609 absent or it must have the SSL CA bit set: this is used as a work
610 around if the basicConstraints extension is absent.
611 SSL Server
613 The extended key usage extension must be absent or include the "web
614 server authentication" and/or one of the SGC OIDs. keyUsage must
615 be absent or it must have the digitalSignature, the keyEncipherment
616 set or both bits set. Netscape certificate type must be absent or
617 have the SSL server bit set.
618 SSL Server CA
620 The extended key usage extension must be absent or include the "web
621 server authentication" and/or one of the SGC OIDs. Netscape cer‐
622 tificate type must be absent or the SSL CA bit must be set: this is
623 used as a work around if the basicConstraints extension is absent.
624 Netscape SSL Server
626 For Netscape SSL clients to connect to an SSL server it must have
627 the keyEncipherment bit set if the keyUsage extension is present.
628 This isn't always valid because some cipher suites use the key for
629 digital signing. Otherwise it is the same as a normal SSL server.
630 Common S/MIME Client Tests
632 The extended key usage extension must be absent or include the
633 "email protection" OID. Netscape certificate type must be absent or
634 should have the S/MIME bit set. If the S/MIME bit is not set in
635 netscape certificate type then the SSL client bit is tolerated as
636 an alternative but a warning is shown: this is because some
637 Verisign certificates don't set the S/MIME bit.
638 S/MIME Signing
640 In addition to the common S/MIME client tests the digitalSignature
641 bit must be set if the keyUsage extension is present.
642 S/MIME Encryption
644 In addition to the common S/MIME tests the keyEncipherment bit must
645 be set if the keyUsage extension is present.
646 S/MIME CA
648 The extended key usage extension must be absent or include the
649 "email protection" OID. Netscape certificate type must be absent or
650 must have the S/MIME CA bit set: this is used as a work around if
651 the basicConstraints extension is absent.
652 CRL Signing
654 The keyUsage extension must be absent or it must have the CRL sign‐
655 ing bit set.
656 CRL Signing CA
658 The normal CA tests apply. Except in this case the basicConstraints
659 extension must be present.
660
662 Extensions in certificates are not transferred to certificate requests
663 and vice versa.
664 It is possible to produce invalid certificates or requests by specify‐
666 ing the wrong private key or using inconsistent options in some cases:
667 these should be checked.
668 There should be options to explicitly set such things as start and end
670 dates rather than an offset from the current time.
671 The code to implement the verify behaviour described in the TRUST SET‐
673 TINGS is currently being developed. It thus describes the intended be‐
674 haviour rather than the current behaviour. It is hoped that it will
675 represent reality in OpenSSL 0.9.5 and later.
676
678 req(1), ca(1), genrsa(1), gendsa(1), verify(1)
679
681 Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
6820.9.8b 2005-04-03 X509(1)