doc/apps/x509.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 x509 - Certificate display and signing utility
   7
   8 =head1 SYNOPSIS
   9
  10 B<openssl> B<x509>
  11 [B<-inform DER|PEM|NET>]
  12 [B<-outform DER|PEM|NET>]
  13 [B<-keyform DER|PEM>]
  14 [B<-CAform DER|PEM>]
  15 [B<-CAkeyform DER|PEM>]
  16 [B<-in filename>]
  17 [B<-out filename>]
  18 [B<-serial>]
  19 [B<-hash>]
  20 [B<-subject>]
  21 [B<-issuer>]
  22 [B<-nameopt option>]
  23 [B<-email>]
  24 [B<-startdate>]
  25 [B<-enddate>]
  26 [B<-purpose>]
  27 [B<-dates>]
  28 [B<-modulus>]
  29 [B<-fingerprint>]
  30 [B<-alias>]
  31 [B<-noout>]
  32 [B<-trustout>]
  33 [B<-clrtrust>]
  34 [B<-clrreject>]
  35 [B<-addtrust arg>]
  36 [B<-addreject arg>]
  37 [B<-setalias arg>]
  38 [B<-days arg>]
  39 [B<-signkey filename>]
  40 [B<-x509toreq>]
  41 [B<-req>]
  42 [B<-CA filename>]
  43 [B<-CAkey filename>]
  44 [B<-CAcreateserial>]
  45 [B<-CAserial filename>]
  46 [B<-text>]
  47 [B<-C>]
  48 [B<-md2|-md5|-sha1|-mdc2>]
  49 [B<-clrext>]
  50 [B<-extfile filename>]
  51 [B<-extensions section>]
  52
  53 =head1 DESCRIPTION
  54
  55 The B<x509> command is a multi purpose certificate utility. It can be
  56 used to display certificate information, convert certificates to
  57 various forms, sign certificate requests like a "mini CA" or edit
  58 certificate trust settings.
  59
  60 Since there are a large number of options they will split up into
  61 various sections.
  62
  63
  64 =head1 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
  65
  66 =over 4
  67
  68 =item B<-inform DER|PEM|NET>
  69
  70 This specifies the input format normally the command will expect an X509
  71 certificate but this can change if other options such as B<-req> are
  72 present. The DER format is the DER encoding of the certificate and PEM
  73 is the base64 encoding of the DER encoding with header and footer lines
  74 added. The NET option is an obscure Netscape server format that is now
  75 obsolete.
  76
  77 =item B<-outform DER|PEM|NET>
  78
  79 This specifies the output format, the options have the same meaning as the
  80 B<-inform> option.
  81
  82 =item B<-in filename>
  83
  84 This specifies the input filename to read a certificate from or standard input
  85 if this option is not specified.
  86
  87 =item B<-out filename>
  88
  89 This specifies the output filename to write to or standard output by
  90 default.
  91
  92 =item B<-md2|-md5|-sha1|-mdc2>
  93
  94 the digest to use. This affects any signing or display option that uses a message
  95 digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not
  96 specified then MD5 is used. If the key being used to sign with is a DSA key then
  97 this option has no effect: SHA1 is always used with DSA keys.
  98
  99
 100 =back
 101
 102 =head1 DISPLAY OPTIONS
 103
 104 Note: the B<-alias> and B<-purpose> options are also display options
 105 but are described in the B<TRUST OPTIONS> section.
 106
 107 =over 4
 108
 109 =item B<-text>
 110
 111 prints out the certificate in text form. Full details are output including the
 112 public key, signature algorithms, issuer and subject names, serial number
 113 any extensions present and any trust settings.
 114
 115 =item B<-noout>
 116
 117 this option prevents output of the encoded version of the request.
 118
 119 =item B<-modulus>
 120
 121 this option prints out the value of the modulus of the public key
 122 contained in the certificate.
 123
 124 =item B<-serial>
 125
 126 outputs the certificate serial number.
 127
 128 =item B<-hash>
 129
 130 outputs the "hash" of the certificate subject name. This is used in OpenSSL to
 131 form an index to allow certificates in a directory to be looked up by subject
 132 name.
 133
 134 =item B<-subject>
 135
 136 outputs the subject name.
 137
 138 =item B<-issuer>
 139
 140 outputs the issuer name.
 141
 142 =item B<-nameopt option>
 143
 144 option which determine how the subject or issuer names are displayed. This
 145 option may be used more than once to set multiple options. See the B<NAME
 146 OPTIONS> section for more information.
 147
 148 =item B<-email>
 149
 150 outputs the email address(es) if any.
 151
 152 =item B<-startdate>
 153
 154 prints out the start date of the certificate, that is the notBefore date.
 155
 156 =item B<-enddate>
 157
 158 prints out the expiry date of the certificate, that is the notAfter date.
 159
 160 =item B<-dates>
 161
 162 prints out the start and expiry dates of a certificate.
 163
 164 =item B<-fingerprint>
 165
 166 prints out the digest of the DER encoded version of the whole certificate.
 167
 168 =item B<-C>
 169
 170 this outputs the certificate in the form of a C source file.
 171
 172 =back
 173
 174 =head1 TRUST SETTINGS
 175
 176 Please note these options are currently experimental and may well change.
 177
 178 A B<trusted certificate> is an ordinary certificate which has several
 179 additional pieces of information attached to it such as the permitted
 180 and prohibited uses of the certificate and an "alias".
 181
 182 Normally when a certificate is being verified at least one certificate
 183 must be "trusted". By default a trusted certificate must be stored
 184 locally and must be a root CA: any certificate chain ending in this CA
 185 is then usable for any purpose.
 186
 187 Trust settings currently are only used with a root CA. They allow a finer
 188 control over the purposes the root CA can be used for. For example a CA
 189 may be trusted for SSL client but not SSL server use.
 190
 191 See the description of the B<verify> utility for more information on the
 192 meaning of trust settings.
 193
 194 Future versions of OpenSSL will recognize trust settings on any
 195 certificate: not just root CAs.
 196
 197
 198 =over 4
 199
 200 =item B<-trustout>
 201
 202 this causes B<x509> to output a B<trusted> certificate. An ordinary
 203 or trusted certificate can be input but by default an ordinary
 204 certificate is output and any trust settings are discarded. With the
 205 B<-trustout> option a trusted certificate is output. A trusted
 206 certificate is automatically output if any trust settings are modified.
 207
 208 =item B<-setalias arg>
 209
 210 sets the alias of the certificate. This will allow the certificate
 211 to be referred to using a nickname for example "Steve's Certificate".
 212
 213 =item B<-alias>
 214
 215 outputs the certificate alias, if any.
 216
 217 =item B<-clrtrust>
 218
 219 clears all the permitted or trusted uses of the certificate.
 220
 221 =item B<-clrreject>
 222
 223 clears all the prohibited or rejected uses of the certificate.
 224
 225 =item B<-addtrust arg>
 226
 227 adds a trusted certificate use. Any object name can be used here
 228 but currently only B<clientAuth> (SSL client use), B<serverAuth>
 229 (SSL server use) and B<emailProtection> (S/MIME email) are used.
 230 Other OpenSSL applications may define additional uses.
 231
 232 =item B<-addreject arg>
 233
 234 adds a prohibited use. It accepts the same values as the B<-addtrust>
 235 option.
 236
 237 =item B<-purpose>
 238
 239 this option performs tests on the certificate extensions and outputs
 240 the results. For a more complete description see the B<CERTIFICATE
 241 EXTENSIONS> section.
 242
 243 =back
 244
 245 =head1 SIGNING OPTIONS
 246
 247 The B<x509> utility can be used to sign certificates and requests: it
 248 can thus behave like a "mini CA".
 249
 250 =over 4
 251
 252 =item B<-signkey filename>
 253
 254 this option causes the input file to be self signed using the supplied
 255 private key.
 256
 257 If the input file is a certificate it sets the issuer name to the
 258 subject name (i.e.  makes it self signed) changes the public key to the
 259 supplied value and changes the start and end dates. The start date is
 260 set to the current time and the end date is set to a value determined
 261 by the B<-days> option. Any certificate extensions are retained unless
 262 the B<-clrext> option is supplied.
 263
 264 If the input is a certificate request then a self signed certificate
 265 is created using the supplied private key using the subject name in
 266 the request.
 267
 268 =item B<-clrext>
 269
 270 delete any extensions from a certificate. This option is used when a
 271 certificate is being created from another certificate (for example with
 272 the B<-signkey> or the B<-CA> options). Normally all extensions are
 273 retained.
 274
 275 =item B<-keyform PEM|DER>
 276
 277 specifies the format (DER or PEM) of the private key file used in the
 278 B<-signkey> option.
 279
 280 =item B<-days arg>
 281
 282 specifies the number of days to make a certificate valid for. The default
 283 is 30 days.
 284
 285 =item B<-x509toreq>
 286
 287 converts a certificate into a certificate request. The B<-signkey> option
 288 is used to pass the required private key.
 289
 290 =item B<-req>
 291
 292 by default a certificate is expected on input. With this option a
 293 certificate request is expected instead.
 294
 295 =item B<-CA filename>
 296
 297 specifies the CA certificate to be used for signing. When this option is
 298 present B<x509> behaves like a "mini CA". The input file is signed by this
 299 CA using this option: that is its issuer name is set to the subject name
 300 of the CA and it is digitally signed using the CAs private key.
 301
 302 This option is normally combined with the B<-req> option. Without the
 303 B<-req> option the input is a certificate which must be self signed.
 304
 305 =item B<-CAkey filename>
 306
 307 sets the CA private key to sign a certificate with. If this option is
 308 not specified then it is assumed that the CA private key is present in
 309 the CA certificate file.
 310
 311 =item B<-CAserial filename>
 312
 313 sets the CA serial number file to use.
 314
 315 When the B<-CA> option is used to sign a certificate it uses a serial
 316 number specified in a file. This file consist of one line containing
 317 an even number of hex digits with the serial number to use. After each
 318 use the serial number is incremented and written out to the file again.
 319
 320 The default filename consists of the CA certificate file base name with
 321 ".srl" appended. For example if the CA certificate file is called
 322 "mycacert.pem" it expects to find a serial number file called "mycacert.srl".
 323
 324 =item B<-CAcreateserial filename>
 325
 326 with this option the CA serial number file is created if it does not exist:
 327 it will contain the serial number "02" and the certificate being signed will
 328 have the 1 as its serial number. Normally if the B<-CA> option is specified
 329 and the serial number file does not exist it is an error.
 330
 331 =item B<-extfile filename>
 332
 333 file containing certificate extensions to use. If not specified then
 334 no extensions are added to the certificate.
 335
 336 =item B<-extensions section>
 337
 338 the section to add certificate extensions from. If this option is not
 339 specified then the extensions should either be contained in the unnamed
 340 (default) section or the default section should contain a variable called
 341 "extensions" which contains the section to use.
 342
 343 =back
 344
 345 =head1 NAME OPTIONS
 346
 347 The B<nameopt> command line switch determines how the subject and issuer
 348 names are displayed. If no B<nameopt> switch is present the default "oneline"
 349 format is used which is compatible with previous versions of OpenSSL.
 350 Each option is described in detail below, all options can be preceded by
 351 a B<-> to turn the option off. Only the first four will normally be used.
 352
 353 =over 4
 354
 355 =item B<compat>
 356
 357 use the old format. This is equivalent to specifying no name options at all.
 358
 359 =item B<RFC2253>
 360
 361 displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
 362 B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
 363 B<sep_comma_plus>, B<dn_rev> and B<sname>.
 364
 365 =item B<oneline>
 366
 367 a oneline format which is more readable than RFC2253. It is equivalent to
 368 specifying the  B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
 369 B<dump_der>, B<use_quote>, B<sep_comma_plus_spc>, B<spc_eq> and B<sname>
 370 options.
 371
 372 =item B<multiline>
 373
 374 a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
 375 B<spc_eq> and B<lname>.
 376
 377 =item B<esc_2253>
 378
 379 escape the "special" characters required by RFC2253 in a field That is
 380 B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginnging of a string
 381 and a space character at the beginning or end of a string.
 382
 383 =item B<esc_ctrl>
 384
 385 escape control characters. That is those with ASCII values less than
 386 0x20 (space) and the delete (0x7f) character. They are escaped using the
 387 RFC2253 \XX notation (where XX are two hex digits representing the
 388 character value).
 389
 390 =item B<esc_msb>
 391
 392 escape characters with the MSB set, that is with ASCII values larger than
 393 127.
 394
 395 =item B<use_quote>
 396
 397 escapes some characters by surrounding the whole string with B<"> characters,
 398 without the option all escaping is done with the B<\> character.
 399
 400 =item B<utf8>
 401
 402 convert all strings to UTF8 format first. This is required by RFC2253. If
 403 you are lucky enough to have a UTF8 compatible terminal then the use
 404 of this option (and B<not> setting B<esc_msb>) may result in the correct
 405 display of multibyte (international) characters. Is this option is not
 406 present then multibyte characters larger than 0xff will be represented
 407 using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
 408 Also if this option is off any UTF8Strings will be converted to their
 409 character form first.
 410
 411 =item B<no_type>
 412
 413 this option does not attempt to interpret multibyte characters in any
 414 way. That is their content octets are merely dumped as though one octet
 415 represents each character. This is useful for diagnostic purposes but
 416 will result in rather odd looking output.
 417
 418 =item B<show_type>
 419
 420 show the type of the ASN1 character string. The type precedes the
 421 field contents. For example "BMPSTRING: Hello World".
 422
 423 =item B<dump_der>
 424
 425 when this option is set any fields that need to be hexdumped will
 426 be dumped using the DER encoding of the field. Otherwise just the
 427 content octets will be displayed. Both options use the RFC2253
 428 B<#XXXX...> format.
 429
 430 =item B<dump_nostr>
 431
 432 dump non character string types (for example OCTET STRING) if this
 433 option is not set then non character string types will be displayed
 434 as though each content octet repesents a single character.
 435
 436 =item B<dump_all>
 437
 438 dump all fields. This option when used with B<dump_der> allows the
 439 DER encoding of the structure to be unambiguously determined.
 440
 441 =item B<dump_unknown>
 442
 443 dump any field whose OID is not recognised by OpenSSL.
 444
 445 =item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
 446 B<sep_multiline>
 447
 448 these options determine the field separators. The first character is
 449 between RDNs and the second between multiple AVAs (multiple AVAs are
 450 very rare and their use is discouraged). The options ending in
 451 "space" additionally place a space after the separator to make it
 452 more readable. The B<sep_multiline> uses a linefeed character for
 453 the RDN separator and a spaced B<+> for the AVA separator. It also
 454 indents the fields by four characters.
 455
 456 =item B<dn_rev>
 457
 458 reverse the fields of the DN. This is required by RFC2253. As a side
 459 effect this also reverses the order of multiple AVAs but this is
 460 permissible.
 461
 462 =item B<nofname>, B<sname>, B<lname>, B<oid>
 463
 464 these options alter how the field name is displayed. B<nofname> does
 465 not display the field at all. B<sname> uses the "short name" form
 466 (CN for commonName for example). B<lname> uses the long form.
 467 B<oid> represents the OID in numerical form and is useful for
 468 diagnostic purpose.
 469
 470 =item B<spc_eq>
 471
 472 places spaces round the B<=> character which follows the field
 473 name.
 474
 475 =back
 476
 477 =head1 EXAMPLES
 478
 479 Note: in these examples the '\' means the example should be all on one
 480 line.
 481
 482 Display the contents of a certificate:
 483
 484  openssl x509 -in cert.pem -noout -text
 485
 486 Display the certificate serial number:
 487
 488  openssl x509 -in cert.pem -noout -serial
 489
 490 Display the certificate subject name:
 491
 492  openssl x509 -in cert.pem -noout -subject
 493
 494 Display the certificate subject name in RFC2253 form:
 495
 496  openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
 497
 498 Display the certificate subject name in oneline form on a terminal
 499 supporting UTF8:
 500
 501  openssl x509 -in cert.pem -noout -subject -nameopt oneline -nameopt -escmsb
 502
 503 Display the certificate MD5 fingerprint:
 504
 505  openssl x509 -in cert.pem -noout -fingerprint
 506
 507 Display the certificate SHA1 fingerprint:
 508
 509  openssl x509 -sha1 -in cert.pem -noout -fingerprint
 510
 511 Convert a certificate from PEM to DER format:
 512
 513  openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
 514
 515 Convert a certificate to a certificate request:
 516
 517  openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
 518
 519 Convert a certificate request into a self signed certificate using
 520 extensions for a CA:
 521
 522  openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
 523         -signkey key.pem -out cacert.pem
 524
 525 Sign a certificate request using the CA certificate above and add user
 526 certificate extensions:
 527
 528  openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
 529         -CA cacert.pem -CAkey key.pem -CAcreateserial
 530
 531
 532 Set a certificate to be trusted for SSL client use and change set its alias to
 533 "Steve's Class 1 CA"
 534
 535  openssl x509 -in cert.pem -addtrust sslclient \
 536         -alias "Steve's Class 1 CA" -out trust.pem
 537
 538 =head1 NOTES
 539
 540 The PEM format uses the header and footer lines:
 541
 542  -----BEGIN CERTIFICATE----
 543  -----END CERTIFICATE----
 544
 545 it will also handle files containing:
 546
 547  -----BEGIN X509 CERTIFICATE----
 548  -----END X509 CERTIFICATE----
 549
 550 Trusted certificates have the lines
 551
 552  -----BEGIN TRUSTED CERTIFICATE----
 553  -----END TRUSTED CERTIFICATE----
 554
 555 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
 560 The B<-fingerprint> option takes the digest of the DER encoded certificate.
 561 This is commonly called a "fingerprint". Because of the nature of message
 562 digests the fingerprint of a certificate is unique to that certificate and
 563 two certificates with the same fingerprint can be considered to be the same.
 564
 565 The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
 566
 567 The B<-email> option searches the subject name and the subject alternative
 568 name extension. Only unique email addresses will be printed out: it will
 569 not print the same address more than once.
 570
 571 =head1 CERTIFICATE EXTENSIONS
 572
 573 The B<-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
 578 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
 581 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 CA,
 583 if the CA flag is false then it is not a CA. B<All> CAs should have the
 584 CA flag set to true.
 585
 586 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
 592 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 V1
 595 self signed certificates.
 596
 597 If the keyUsage extension is present then additional restraints are
 598 made on the uses of the certificate. A CA certificate B<must> have the
 599 keyCertSign bit set if the keyUsage extension is present.
 600
 601 The extended key usage extension places additional restrictions on the
 602 certificate uses. If this extension is present (whether critical or not)
 603 the key can only be used for the purposes specified.
 604
 605 A complete description of each test is given below. The comments about
 606 basicConstraints and keyUsage and V1 certificates above apply to B<all>
 607 CA certificates.
 608
 609
 610 =over 4
 611
 612 =item B<SSL Client>
 613
 614 The extended key usage extension must be absent or include the "web client
 615 authentication" OID.  keyUsage must be absent or it must have the
 616 digitalSignature bit set. Netscape certificate type must be absent or it must
 617 have the SSL client bit set.
 618
 619 =item B<SSL Client CA>
 620
 621 The extended key usage extension must be absent or include the "web client
 622 authentication" OID. Netscape certificate type must be absent or it must have
 623 the SSL CA bit set: this is used as a work around if the basicConstraints
 624 extension is absent.
 625
 626 =item B<SSL Server>
 627
 628 The extended key usage extension must be absent or include the "web server
 629 authentication" and/or one of the SGC OIDs.  keyUsage must be absent or it
 630 must have the digitalSignature, the keyEncipherment set or both bits set.
 631 Netscape certificate type must be absent or have the SSL server bit set.
 632
 633 =item B<SSL Server CA>
 634
 635 The extended key usage extension must be absent or include the "web server
 636 authentication" and/or one of the SGC OIDs.  Netscape certificate type must
 637 be absent or the SSL CA bit must be set: this is used as a work around if the
 638 basicConstraints extension is absent.
 639
 640 =item B<Netscape SSL Server>
 641
 642 For Netscape SSL clients to connect to an SSL server it must have the
 643 keyEncipherment bit set if the keyUsage extension is present. This isn't
 644 always valid because some cipher suites use the key for digital signing.
 645 Otherwise it is the same as a normal SSL server.
 646
 647 =item B<Common S/MIME Client Tests>
 648
 649 The extended key usage extension must be absent or include the "email
 650 protection" OID. Netscape certificate type must be absent or should have the
 651 S/MIME bit set. If the S/MIME bit is not set in netscape certificate type
 652 then the SSL client bit is tolerated as an alternative but a warning is shown:
 653 this is because some Verisign certificates don't set the S/MIME bit.
 654
 655 =item B<S/MIME Signing>
 656
 657 In addition to the common S/MIME client tests the digitalSignature bit must
 658 be set if the keyUsage extension is present.
 659
 660 =item B<S/MIME Encryption>
 661
 662 In addition to the common S/MIME tests the keyEncipherment bit must be set
 663 if the keyUsage extension is present.
 664
 665 =item B<S/MIME CA>
 666
 667 The extended key usage extension must be absent or include the "email
 668 protection" OID. Netscape certificate type must be absent or must have the
 669 S/MIME CA bit set: this is used as a work around if the basicConstraints
 670 extension is absent.
 671
 672 =item B<CRL Signing>
 673
 674 The keyUsage extension must be absent or it must have the CRL signing bit
 675 set.
 676
 677 =item B<CRL Signing CA>
 678
 679 The normal CA tests apply. Except in this case the basicConstraints extension
 680 must be present.
 681
 682 =back
 683
 684 =head1 BUGS
 685
 686 Extensions in certificates are not transferred to certificate requests and
 687 vice versa.
 688
 689 It is possible to produce invalid certificates or requests by specifying the
 690 wrong private key or using inconsistent options in some cases: these should
 691 be checked.
 692
 693 There should be options to explicitly set such things as start and end
 694 dates rather than an offset from the current time.
 695
 696 The code to implement the verify behaviour described in the B<TRUST SETTINGS>
 697 is currently being developed. It thus describes the intended behavior rather
 698 than the current behaviour. It is hoped that it will represent reality in
 699 OpenSSL 0.9.5 and later.
 700
 701 =head1 SEE ALSO
 702
 703 L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
 704 L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>
 705
 706 =cut