libjava/classpath/java/security/cert/X509Certificate.java

   1 /* X509Certificate.java --- X.509 Certificate class
   2    Copyright (C) 1999,2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.security.cert;
  40
  41 import java.math.BigInteger;
  42 import java.security.Principal;
  43 import java.util.Date;
  44 import java.util.List;
  45
  46 /**
  47  * X509Certificate is the abstract class for X.509 certificates.
  48  * This provides a stanard class interface for accessing all
  49  * the attributes of X.509 certificates.
  50  *
  51  * <p>In June 1996, the basic X.509 v3 format was finished by
  52  * ISO/IEC and ANSI X.9. The ASN.1 DER format is below:
  53  *
  54  * <blockquote><pre>
  55  * Certificate  ::=  SEQUENCE  {
  56  *   tbsCertificate       TBSCertificate,
  57  *   signatureAlgorithm   AlgorithmIdentifier,
  58  *   signatureValue       BIT STRING  }
  59  * </pre></blockquote>
  60  *
  61  * <p>These certificates are widely used in various Internet
  62  * protocols to support authentication. It is used in
  63  * Privacy Enhanced Mail (PEM), Transport Layer Security (TLS),
  64  * Secure Sockets Layer (SSL), code signing for trusted software
  65  * distribution, and Secure Electronic Transactions (SET).
  66  *
  67  * <p>The certificates are managed and vouched for by
  68  * <I>Certificate Authorities</I> (CAs). CAs are companies or
  69  * groups that create certificates by placing the data in the
  70  * X.509 certificate format and signing it with their private
  71  * key. CAs serve as trusted third parties by certifying that
  72  * the person or group specified in the certificate is who
  73  * they say they are.
  74  *
  75  * <p>The ASN.1 defintion for <I>tbsCertificate</I> is
  76  *
  77  * <blockquote><pre>
  78  * TBSCertificate  ::=  SEQUENCE  {
  79  *   version         [0]  EXPLICIT Version DEFAULT v1,
  80  *   serialNumber         CertificateSerialNumber,
  81  *   signature            AlgorithmIdentifier,
  82  *   issuer               Name,
  83  *   validity             Validity,
  84  *   subject              Name,
  85  *   subjectPublicKeyInfo SubjectPublicKeyInfo,
  86  *   issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
  87  *                        -- If present, version shall be v2 or v3
  88  *   subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
  89  *                        -- If present, version shall be v2 or v3
  90  *   extensions      [3]  EXPLICIT Extensions OPTIONAL
  91  *                        -- If present, version shall be v3
  92  * }
  93  *
  94  * Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
  95  *
  96  * CertificateSerialNumber  ::=  INTEGER
  97  *
  98  * Validity ::= SEQUENCE {
  99  *   notBefore      Time,
 100  *   notAfter       Time }
 101  *
 102  * Time ::= CHOICE {
 103  *   utcTime        UTCTime,
 104  *   generalTime    GeneralizedTime }
 105  *
 106  * UniqueIdentifier  ::=  BIT STRING
 107  *
 108  * SubjectPublicKeyInfo  ::=  SEQUENCE  {
 109  *   algorithm            AlgorithmIdentifier,
 110  *   subjectPublicKey     BIT STRING  }
 111  *
 112  * Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
 113  *
 114  * Extension  ::=  SEQUENCE  {
 115  *   extnID      OBJECT IDENTIFIER,
 116  *   critical    BOOLEAN DEFAULT FALSE,
 117  *   extnValue   OCTET STRING  }
 118  * </pre></blockquote>
 119  *
 120  * Certificates are created with the CertificateFactory.
 121  *
 122  * <p>References:
 123  *
 124  * <ol>
 125  * <li>Olivier Dubuisson, Philippe Fouquart (Translator) <i>ASN.1 -
 126  * Communication between heterogeneous systems</i>, (C) September 2000,
 127  * Morgan Kaufmann Publishers, ISBN 0-12-6333361-0. Available on-line at
 128  * <a
 129  * href="http://www.oss.com/asn1/dubuisson.html">http://www.oss.com/asn1/dubuisson.html</a></li>
 130  * <li>R. Housley et al, <i><a href="http://www.ietf.org/rfc/rfc3280.txt">RFC
 131  * 3280: Internet X.509 Public Key Infrastructure Certificate and CRL
 132  * Profile</a></i>.</li>
 133  * </ol>
 134  *
 135  * @since 1.2
 136  * @author Mark Benvenuto
 137  * @author Casey Marshall (rsdio@metastatic.org)
 138  */
 139 public abstract class X509Certificate
 140   extends java.security.cert.Certificate  // XXX workaround for gcj bug #17845
 141   implements X509Extension
 142 {
 143   private static final long serialVersionUID = -2491127588187038216L;
 144
 145   /**
 146    * Constructs a new certificate of the specified type.
 147    */
 148   protected X509Certificate()
 149   {
 150     super( "X.509" );
 151   }
 152
 153   /**
 154      Checks the validity of the X.509 certificate. It is valid
 155      if the current date and time are within the period specified
 156      by the certificate.
 157
 158      The ASN.1 DER encoding is:
 159
 160      validity             Validity,
 161
 162      Validity ::= SEQUENCE {
 163      notBefore      Time,
 164      notAfter       Time }
 165
 166      Time ::= CHOICE {
 167      utcTime        UTCTime,
 168      generalTime    GeneralizedTime }
 169
 170      Consult rfc2459 for more information.
 171
 172      @throws CertificateExpiredException if the certificate expired
 173      @throws CertificateNotYetValidException if the certificate is
 174      not yet valid
 175   */
 176   public abstract void checkValidity()
 177     throws CertificateExpiredException,
 178     CertificateNotYetValidException;
 179
 180   /**
 181      Checks the validity of the X.509 certificate for the
 182      specified time and date. It is valid if the specified
 183      date and time are within the period specified by
 184      the certificate.
 185
 186      @throws CertificateExpiredException if the certificate expired
 187      based on the date
 188      @throws CertificateNotYetValidException if the certificate is
 189      not yet valid based on the date
 190   */
 191   public abstract void checkValidity(Date date)
 192     throws CertificateExpiredException,
 193     CertificateNotYetValidException;
 194
 195   /**
 196      Returns the version of this certificate.
 197
 198      The ASN.1 DER encoding is:
 199
 200      version         [0]  EXPLICIT Version DEFAULT v1,
 201
 202      Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
 203
 204      Consult rfc2459 for more information.
 205
 206      @return version number of certificate
 207   */
 208   public abstract int getVersion();
 209
 210   /**
 211      Gets the serial number for serial Number in
 212      this Certifcate. It must be a unique number
 213      unique other serial numbers from the granting CA.
 214
 215      The ASN.1 DER encoding is:
 216
 217      serialNumber         CertificateSerialNumber,
 218
 219      CertificateSerialNumber  ::=  INTEGER
 220
 221      Consult rfc2459 for more information.
 222
 223      @return the serial number for this X509CRLEntry.
 224   */
 225   public abstract BigInteger getSerialNumber();
 226
 227   /**
 228      Returns the issuer (issuer distinguished name) of the
 229      Certificate. The issuer is the entity who signed
 230      and issued the Certificate.
 231
 232      The ASN.1 DER encoding is:
 233
 234      issuer                  Name,
 235
 236      Name ::= CHOICE {
 237      RDNSequence }
 238
 239      RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
 240
 241      RelativeDistinguishedName ::=
 242      SET OF AttributeTypeAndValue
 243
 244      AttributeTypeAndValue ::= SEQUENCE {
 245      type     AttributeType,
 246      value    AttributeValue }
 247
 248      AttributeType ::= OBJECT IDENTIFIER
 249
 250      AttributeValue ::= ANY DEFINED BY AttributeType
 251
 252      DirectoryString ::= CHOICE {
 253      teletexString           TeletexString (SIZE (1..MAX)),
 254      printableString         PrintableString (SIZE (1..MAX)),
 255      universalString         UniversalString (SIZE (1..MAX)),
 256      utf8String              UTF8String (SIZE (1.. MAX)),
 257      bmpString               BMPString (SIZE (1..MAX)) }
 258
 259      Consult rfc2459 for more information.
 260
 261      @return the issuer in the Principal class
 262   */
 263   public abstract Principal getIssuerDN();
 264
 265   /**
 266      Returns the subject (subject distinguished name) of the
 267      Certificate. The subject is the entity who the Certificate
 268      identifies.
 269
 270      The ASN.1 DER encoding is:
 271
 272      subject              Name,
 273
 274      Consult rfc2459 for more information.
 275
 276      @return the issuer in the Principal class
 277   */
 278   public abstract Principal getSubjectDN();
 279
 280   /**
 281      Returns the date that this certificate is not to be used
 282      before, <I>notBefore</I>.
 283
 284      The ASN.1 DER encoding is:
 285
 286      validity             Validity,
 287
 288      Validity ::= SEQUENCE {
 289      notBefore      Time,
 290      notAfter       Time }
 291
 292      Time ::= CHOICE {
 293      utcTime        UTCTime,
 294      generalTime    GeneralizedTime }
 295
 296      Consult rfc2459 for more information.
 297
 298      @return the date <I>notBefore</I>
 299   */
 300   public abstract Date getNotBefore();
 301
 302   /**
 303      Returns the date that this certificate is not to be used
 304      after, <I>notAfter</I>.
 305
 306      @return the date <I>notAfter</I>
 307   */
 308   public abstract Date getNotAfter();
 309
 310
 311   /**
 312      Returns the <I>tbsCertificate</I> from the certificate.
 313
 314      @return the DER encoded tbsCertificate
 315
 316      @throws CertificateEncodingException if encoding error occurred
 317   */
 318   public abstract byte[] getTBSCertificate() throws CertificateEncodingException;
 319
 320   /**
 321      Returns the signature in its raw DER encoded format.
 322
 323      The ASN.1 DER encoding is:
 324
 325      signatureValue       BIT STRING
 326
 327      Consult rfc2459 for more information.
 328
 329      @return byte array representing signature
 330   */
 331   public abstract byte[] getSignature();
 332
 333   /**
 334      Returns the signature algorithm used to sign the CRL.
 335      An examples is "SHA-1/DSA".
 336
 337      The ASN.1 DER encoding is:
 338
 339      signatureAlgorithm   AlgorithmIdentifier,
 340
 341      AlgorithmIdentifier  ::=  SEQUENCE  {
 342      algorithm               OBJECT IDENTIFIER,
 343      parameters              ANY DEFINED BY algorithm OPTIONAL  }
 344
 345      Consult rfc2459 for more information.
 346
 347      The algorithm name is determined from the OID.
 348
 349      @return a string with the signature algorithm name
 350   */
 351   public abstract String getSigAlgName();
 352
 353
 354   /**
 355      Returns the OID for the signature algorithm used.
 356      Example "1.2.840.10040.4.3" is return for SHA-1 with DSA.\
 357
 358      The ASN.1 DER encoding for the example is:
 359
 360      id-dsa-with-sha1 ID  ::=  {
 361      iso(1) member-body(2) us(840) x9-57 (10040)
 362      x9cm(4) 3 }
 363
 364      Consult rfc2459 for more information.
 365
 366      @return a string containing the OID.
 367   */
 368   public abstract String getSigAlgOID();
 369
 370
 371   /**
 372      Returns the AlgorithmParameters in the encoded form
 373      for the signature algorithm used.
 374
 375      If access to the parameters is need, create an
 376      instance of AlgorithmParameters.
 377
 378      @return byte array containing algorithm parameters, null
 379      if no parameters are present in certificate
 380   */
 381   public abstract byte[] getSigAlgParams();
 382
 383
 384   /**
 385      Returns the issuer unique ID for this certificate.
 386
 387      The ASN.1 DER encoding is:
 388
 389      issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
 390      -- If present, version shall be v2 or v3
 391
 392      UniqueIdentifier  ::=  BIT STRING
 393
 394      Consult rfc2459 for more information.
 395
 396      @return bit representation of <I>issuerUniqueID</I>
 397   */
 398   public abstract boolean[] getIssuerUniqueID();
 399
 400   /**
 401      Returns the subject unique ID for this certificate.
 402
 403      The ASN.1 DER encoding is:
 404
 405      subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
 406      -- If present, version shall be v2 or v3
 407
 408      UniqueIdentifier  ::=  BIT STRING
 409
 410      Consult rfc2459 for more information.
 411
 412      @return bit representation of <I>subjectUniqueID</I>
 413   */
 414   public abstract boolean[] getSubjectUniqueID();
 415
 416   /**
 417      Returns a boolean array representing the <I>KeyUsage</I>
 418      extension for the certificate. The KeyUsage (OID = 2.5.29.15)
 419      defines the purpose of the key in the certificate.
 420
 421      The ASN.1 DER encoding is:
 422
 423      id-ce-keyUsage OBJECT IDENTIFIER ::=  { id-ce 15 }
 424
 425      KeyUsage ::= BIT STRING {
 426      digitalSignature        (0),
 427      nonRepudiation          (1),
 428      keyEncipherment         (2),
 429      dataEncipherment        (3),
 430      keyAgreement            (4),
 431      keyCertSign             (5),
 432      cRLSign                 (6),
 433      encipherOnly            (7),
 434      decipherOnly            (8) }
 435
 436      Consult rfc2459 for more information.
 437
 438      @return bit representation of <I>KeyUsage</I>
 439   */
 440   public abstract boolean[] getKeyUsage();
 441
 442   /**
 443      Returns the certificate constraints path length from the
 444      critical BasicConstraints extension, (OID = 2.5.29.19).
 445
 446      The basic constraints extensions is used to determine if
 447      the subject of the certificate is a Certificate Authority (CA)
 448      and how deep the certification path may exist. The
 449      <I>pathLenConstraint</I> only takes affect if <I>cA</I>
 450      is set to true. "A value of zero indicates that only an
 451      end-entity certificate may follow in the path." (rfc2459)
 452
 453      The ASN.1 DER encoding is:
 454
 455      id-ce-basicConstraints OBJECT IDENTIFIER ::=  { id-ce 19 }
 456
 457      BasicConstraints ::= SEQUENCE {
 458      cA                      BOOLEAN DEFAULT FALSE,
 459      pathLenConstraint       INTEGER (0..MAX) OPTIONAL }
 460
 461      Consult rfc2459 for more information.
 462
 463      @return the length of the path constraint if BasicConstraints
 464      is present and cA is TRUE. Otherwise returns -1.
 465   */
 466   public abstract int getBasicConstraints();
 467
 468   // 1.4 instance methods.
 469   // ------------------------------------------------------------------------
 470
 471   /**
 472    * Returns the <code>ExtendedKeyUsage</code> extension of this
 473    * certificate, or null if there is no extension present. The returned
 474    * value is a {@link java.util.List} strings representing the object
 475    * identifiers of the extended key usages. This extension has the OID
 476    * 2.5.29.37.
 477    *
 478    * <p>The ASN.1 definition for this extension is:
 479    *
 480    * <blockquote><pre>
 481    * ExtendedKeyUsage ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId
 482    *
 483    * KeyPurposeId ::= OBJECT IDENTIFIER
 484    * </pre></blockquote>
 485    *
 486    * @return The list of extension OIDs, or null if there are none
 487    * present in this certificate.
 488    * @throws CertificateParsingException If this extension cannot be
 489    * parsed from its encoded form.
 490    */
 491   public java.util.List<String> getExtendedKeyUsage()
 492     throws CertificateParsingException
 493   {
 494     throw new UnsupportedOperationException();
 495   }
 496
 497   /**
 498    * Returns the alternative names for this certificate's subject (the
 499    * owner), or null if there are none.
 500    *
 501    * <p>This is an X.509 extension with OID 2.5.29.17 and is defined by
 502    * the ASN.1 construction:
 503    *
 504    * <blockquote><pre>
 505    * SubjectAltNames ::= GeneralNames
 506    *
 507    * GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName
 508    *
 509    * GeneralName ::= CHOICE {
 510    *   otherName                 [0]   OtherName,
 511    *   rfc822Name                [1]   IA5String,
 512    *   dNSName                   [2]   IA5String,
 513    *   x400Address               [3]   ORAddress,
 514    *   directoryName             [4]   Name,
 515    *   ediPartyName              [5]   EDIPartyName,
 516    *   uniformResourceIdentifier [6]   IA5String,
 517    *   iPAddress                 [7]   OCTET STRING,
 518    *   registeredID              [8]   OBJECT IDENTIFIER
 519    * }
 520    * </pre></blockquote>
 521    *
 522    * <p>The returned collection contains one or more two-element Lists,
 523    * with the first object being an Integer representing the choice
 524    * above (with value 0 through 8) and the second being an (a) String
 525    * if the <code>GeneralName</code> is a rfc822Name, dNSName,
 526    * uniformResourceIdentifier, iPAddress, or registeredID, or (b) a
 527    * byte array of the DER encoded form for any others.
 528    *
 529    * @return The collection of alternative names, or null if there are
 530    * none.
 531    * @throws CertificateParsingException If the encoded extension cannot
 532    * be parsed.
 533    * @since JDK 1.4
 534    */
 535   public java.util.Collection<List<?>> getSubjectAlternativeNames()
 536     throws CertificateParsingException
 537   {
 538     throw new UnsupportedOperationException();
 539   }
 540
 541   /**
 542    * Returns the alternative names for this certificate's issuer, or
 543    * null if there are none.
 544    *
 545    * <p>This is an X.509 extension with OID 2.5.29.18, and is defined by
 546    * the ASN.1 construction:
 547    *
 548    * <blockquote><pre>
 549    * IssuerAltNames ::= GeneralNames
 550    * </pre></blockquote>
 551    *
 552    * <p>The <code>GeneralNames</code> construct and the form of the
 553    * returned collection are the same as with {@link
 554    * #getSubjectAlternativeNames()}.
 555    *
 556    * @return The collection of alternative names, or null if there are
 557    * none.
 558    * @throws CertificateParsingException If the encoded extension cannot
 559    * be parsed.
 560    * @since JDK 1.4
 561    */
 562   public java.util.Collection<List<?>> getIssuerAlternativeNames()
 563     throws CertificateParsingException
 564   {
 565     throw new UnsupportedOperationException();
 566   }
 567
 568   /**
 569    * Returns the X.500 distinguished name of this certificate's subject.
 570    *
 571    * @return The subject's X.500 distinguished name.
 572    * @since JDK 1.4
 573    */
 574   public javax.security.auth.x500.X500Principal getSubjectX500Principal()
 575   {
 576     throw new UnsupportedOperationException();
 577   }
 578
 579   /**
 580    * Returns the X.500 distinguished name of this certificate's issuer.
 581    *
 582    * @return The issuer's X.500 distinguished name.
 583    * @since JDK 1.4
 584    */
 585   public javax.security.auth.x500.X500Principal getIssuerX500Principal()
 586   {
 587     throw new UnsupportedOperationException();
 588   }
 589 }