libcore/luni/src/main/java/java/security/cert/X509Certificate.java

   1 /*
   2  *  Licensed to the Apache Software Foundation (ASF) under one or more
   3  *  contributor license agreements.  See the NOTICE file distributed with
   4  *  this work for additional information regarding copyright ownership.
   5  *  The ASF licenses this file to You under the Apache License, Version 2.0
   6  *  (the "License"); you may not use this file except in compliance with
   7  *  the License.  You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *  Unless required by applicable law or agreed to in writing, software
  12  *  distributed under the License is distributed on an "AS IS" BASIS,
  13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *  See the License for the specific language governing permissions and
  15  *  limitations under the License.
  16  */
  17
  18 package java.security.cert;
  19
  20 import java.io.ByteArrayInputStream;
  21 import java.math.BigInteger;
  22 import java.security.Principal;
  23 import java.util.Collection;
  24 import java.util.Date;
  25 import java.util.List;
  26 import javax.security.auth.x500.X500Principal;
  27
  28 /**
  29  * Abstract base class for X.509 certificates.
  30  * <p>
  31  * This represents a standard way for accessing the attributes of X.509
  32  * certificates.
  33  * <p>
  34  * The basic X.509 v3 format described in ASN.1:
  35  *
  36  * <pre>
  37  * Certificate  ::=  SEQUENCE  {
  38  *     tbsCertificate       TBSCertificate,
  39  *     signatureAlgorithm   AlgorithmIdentifier,
  40  *     signature            BIT STRING  }
  41  *
  42  * TBSCertificate  ::=  SEQUENCE  {
  43  *      version         [0]  EXPLICIT Version DEFAULT v1,
  44  *      serialNumber         CertificateSerialNumber,
  45  *      signature            AlgorithmIdentifier,
  46  *      issuer               Name,
  47  *      validity             Validity,
  48  *      subject              Name,
  49  *      subjectPublicKeyInfo SubjectPublicKeyInfo,
  50  *      issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
  51  *                           -- If present, version must be v2 or v3
  52  *      subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
  53  *                           -- If present, version must be v2 or v3
  54  *      extensions      [3]  EXPLICIT Extensions OPTIONAL
  55  *                           -- If present, version must be v3
  56  *      }
  57  * </pre>
  58  * <p>
  59  * For more information consult RFC 2459
  60  * "Internet X.509 Public Key Infrastructure Certificate and CRL Profile" at <a
  61  * href
  62  * ="http://www.ietf.org/rfc/rfc2459.txt">http://www.ietf.org/rfc/rfc2459.txt
  63  * </a> .
  64  */
  65 public abstract class X509Certificate
  66         extends Certificate implements X509Extension {
  67
  68     private static final long serialVersionUID = -2491127588187038216L;
  69
  70     /**
  71      * Creates a new {@code X509Certificate}.
  72      */
  73     protected X509Certificate() {
  74         super("X.509");
  75     }
  76
  77     /**
  78      * Checks whether the certificate is currently valid.
  79      * <p>
  80      * The validity defined in ASN.1:
  81      *
  82      * <pre>
  83      * validity             Validity
  84      *
  85      * Validity ::= SEQUENCE {
  86      *      notBefore       CertificateValidityDate,
  87      *      notAfter        CertificateValidityDate }
  88      *
  89      * CertificateValidityDate ::= CHOICE {
  90      *      utcTime         UTCTime,
  91      *      generalTime     GeneralizedTime }
  92      * </pre>
  93      *
  94      * @throws CertificateExpiredException
  95      *             if the certificate has expired.
  96      * @throws CertificateNotYetValidException
  97      *             if the certificate is not yet valid.
  98      */
  99     public abstract void checkValidity()
 100             throws CertificateExpiredException, CertificateNotYetValidException;
 101
 102     /**
 103      * Checks whether the certificate is valid at the specified date.
 104      *
 105      * @param date
 106      *            the date to check the validity against.
 107      * @throws CertificateExpiredException
 108      *             if the certificate has expired.
 109      * @throws CertificateNotYetValidException
 110      *             if the certificate is not yet valid.
 111      * @see #checkValidity()
 112      */
 113     public abstract void checkValidity(Date date)
 114             throws CertificateExpiredException, CertificateNotYetValidException;
 115
 116     /**
 117      * Returns the certificates {@code version} (version number).
 118      * <p>
 119      * The version defined is ASN.1:
 120      *
 121      * <pre>
 122      * Version ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
 123      * </pre>
 124      *
 125      * @return the version number.
 126      */
 127     public abstract int getVersion();
 128
 129     /**
 130      * Returns the {@code serialNumber} of the certificate.
 131      * <p>
 132      * The ASN.1 definition of {@code serialNumber}:
 133      *
 134      * <pre>
 135      * CertificateSerialNumber  ::=  INTEGER
 136      * </pre>
 137      *
 138      * @return the serial number.
 139      */
 140     public abstract BigInteger getSerialNumber();
 141
 142     /**
 143      * Returns the {@code issuer} (issuer distinguished name) as an
 144      * implementation specific {@code Principal} object.
 145      * <p>
 146      * The ASN.1 definition of {@code issuer}:
 147      *
 148      * <pre>
 149      *  issuer      Name
 150      *
 151      *  Name ::= CHOICE {
 152      *      RDNSequence }
 153      *
 154      *    RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
 155      *
 156      *    RelativeDistinguishedName ::= SET OF AttributeTypeAndValue
 157      *
 158      *    AttributeTypeAndValue ::= SEQUENCE {
 159      *      type     AttributeType,
 160      *      value    AttributeValue }
 161      *
 162      *    AttributeType ::= OBJECT IDENTIFIER
 163      *
 164      *    AttributeValue ::= ANY DEFINED BY AttributeType
 165      * </pre>
 166      *
 167      * <b>replaced by:</b> {@link #getIssuerX500Principal()}.
 168      *
 169      * @return the {@code issuer} as an implementation specific {@code
 170      *         Principal}.
 171      */
 172     public abstract Principal getIssuerDN() ;
 173
 174     /**
 175      * Returns the {@code issuer} (issuer distinguished name) as an {@code
 176      * X500Principal}.
 177      *
 178      * @return the {@code issuer} (issuer distinguished name).
 179      */
 180     public X500Principal getIssuerX500Principal() {
 181
 182         try {
 183             // TODO if there is no X.509 certificate provider installed
 184             // should we try to access Harmony X509CertImpl via classForName?
 185             CertificateFactory factory = CertificateFactory
 186                     .getInstance("X.509");
 187
 188             X509Certificate cert = (X509Certificate) factory
 189                     .generateCertificate(new ByteArrayInputStream(getEncoded()));
 190
 191             return cert.getIssuerX500Principal();
 192
 193         } catch (Exception e) {
 194             throw new RuntimeException("Failed to get X500Principal issuer", e);
 195         }
 196     }
 197
 198     /**
 199      * Returns the {@code subject} (subject distinguished name) as an
 200      * implementation specific {@code Principal} object.
 201      * <p>
 202      * The ASN.1 definition of {@code subject}:
 203      *
 204      * <pre>
 205      * subject      Name
 206      *
 207      *  Name ::= CHOICE {
 208      *      RDNSequence }
 209      *
 210      *    RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
 211      *
 212      *    RelativeDistinguishedName ::= SET OF AttributeTypeAndValue
 213      *
 214      *    AttributeTypeAndValue ::= SEQUENCE {
 215      *      type     AttributeType,
 216      *      value    AttributeValue }
 217      *
 218      *    AttributeType ::= OBJECT IDENTIFIER
 219      *
 220      *    AttributeValue ::= ANY DEFINED BY AttributeType
 221      * </pre>
 222      *
 223      * <p>
 224      * <b>replaced by:</b> {@link #getSubjectX500Principal()}.
 225      *
 226      * @return the {@code subject} (subject distinguished name).
 227      */
 228     public abstract Principal getSubjectDN();
 229
 230     /**
 231      * Returns the {@code subject} (subject distinguished name) as an {@code
 232      * X500Principal}.
 233      *
 234      * @return the {@code subject} (subject distinguished name)
 235      */
 236     public X500Principal getSubjectX500Principal() {
 237
 238         try {
 239             // TODO if there is no X.509 certificate provider installed
 240             // should we try to access Harmony X509CertImpl via classForName?
 241             CertificateFactory factory = CertificateFactory
 242                     .getInstance("X.509");
 243
 244             X509Certificate cert = (X509Certificate) factory
 245                     .generateCertificate(new ByteArrayInputStream(getEncoded()));
 246
 247             return cert.getSubjectX500Principal();
 248         } catch (Exception e) {
 249             throw new RuntimeException("Failed to get X500Principal subject", e);
 250         }
 251     }
 252
 253     /**
 254      * Returns the {@code notBefore} date from the validity period of the
 255      * certificate.
 256      *
 257      * @return the start of the validity period.
 258      */
 259     public abstract Date getNotBefore();
 260
 261     /**
 262      * Returns the {@code notAfter} date of the validity period of the
 263      * certificate.
 264      *
 265      * @return the end of the validity period.
 266      */
 267     public abstract Date getNotAfter();
 268
 269     /**
 270      * Returns the {@code tbsCertificate} information from this certificate in
 271      * DER-encoded format.
 272      *
 273      * @return the DER-encoded certificate information.
 274      * @throws CertificateEncodingException
 275      *             if an error occurs in encoding
 276      */
 277     public abstract byte[] getTBSCertificate()
 278                                     throws CertificateEncodingException;
 279
 280     /**
 281      * Returns the raw signature bits from the certificate.
 282      *
 283      * @return the raw signature bits from the certificate.
 284      */
 285     public abstract byte[] getSignature();
 286
 287     /**
 288      * Returns the name of the algorithm for the certificate signature.
 289      *
 290      * @return the signature algorithm name.
 291      */
 292     public abstract String getSigAlgName();
 293
 294     /**
 295      * Returns the OID of the signature algorithm from the certificate.
 296      *
 297      * @return the OID of the signature algorithm.
 298      */
 299     public abstract String getSigAlgOID();
 300
 301     /**
 302      * Returns the parameters of the signature algorithm in DER-encoded format.
 303      *
 304      * @return the parameters of the signature algorithm, or {@code null} if
 305      *         none are used.
 306      */
 307     public abstract byte[] getSigAlgParams();
 308
 309     /**
 310      * Returns the {@code issuerUniqueID} from the certificate.
 311      *
 312      * @return the {@code issuerUniqueID} or {@code null} if there's none in the
 313      *         certificate.
 314      */
 315     public abstract boolean[] getIssuerUniqueID();
 316
 317     /**
 318      * Returns the {@code subjectUniqueID} from the certificate.
 319      *
 320      * @return the {@code subjectUniqueID} or null if there's none in the
 321      *         certificate.
 322      */
 323     public abstract boolean[] getSubjectUniqueID();
 324
 325     /**
 326      * Returns the {@code KeyUsage} extension as a {@code boolean} array.
 327      * <p>
 328      * The ASN.1 definition of {@code KeyUsage}:
 329      *
 330      * <pre>
 331      * KeyUsage ::= BIT STRING {
 332      *      digitalSignature        (0),
 333      *      nonRepudiation          (1),
 334      *      keyEncipherment         (2),
 335      *      dataEncipherment        (3),
 336      *      keyAgreement            (4),
 337      *      keyCertSign             (5),
 338      *      cRLSign                 (6),
 339      *      encipherOnly            (7),
 340      *      decipherOnly            (8) }
 341      *
 342      * </pre>
 343      *
 344      * @return the {@code KeyUsage} extension or {@code null} if there's none in
 345      *         the certificate.
 346      */
 347     public abstract boolean[] getKeyUsage();
 348
 349     /**
 350      * Returns a read-only list of OID strings representing the {@code
 351      * ExtKeyUsageSyntax} field of the extended key usage extension.
 352      *
 353      * @return the extended key usage extension, or {@code null} if there's none
 354      *         in the certificate.
 355      * @throws CertificateParsingException
 356      *             if the extension decoding fails.
 357      */
 358     public List<String> getExtendedKeyUsage()
 359                         throws CertificateParsingException {
 360         return null;
 361     }
 362
 363     /**
 364      * Returns the path length of the certificate constraints from the {@code
 365      * BasicContraints} extension.
 366      *
 367      * @return the path length of the certificate constraints if the extension
 368      *         is present or {@code -1} if the extension is not present. {@code
 369      *         Integer.MAX_VALUE} if there's not limit.
 370      */
 371     public abstract int getBasicConstraints();
 372
 373     /**
 374      * Returns a read-only list of the subject alternative names from the
 375      * {@code SubjectAltName} extension.
 376      * <p>
 377      * The ASN.1 definition of {@code SubjectAltName}:
 378      *
 379      * <pre>
 380      * SubjectAltName ::= GeneralNames
 381      *
 382      * GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName
 383      *
 384      * GeneralName ::= CHOICE {
 385      *      otherName                       [0]     AnotherName,
 386      *      rfc822Name                      [1]     IA5String,
 387      *      dNSName                         [2]     IA5String,
 388      *      x400Address                     [3]     ORAddress,
 389      *      directoryName                   [4]     Name,
 390      *      ediPartyName                    [5]     EDIPartyName,
 391      *      uniformResourceIdentifier       [6]     IA5String,
 392      *      iPAddress                       [7]     OCTET STRING,
 393      *      registeredID                    [8]     OBJECT IDENTIFIER }
 394      *
 395      * </pre>
 396      *
 397      * @return the subject alternative names or {@code null} if there are none
 398      *         in the certificate.
 399      * @throws CertificateParsingException
 400      *             if decoding of the extension fails.
 401      */
 402     public Collection<List<?>> getSubjectAlternativeNames()
 403                                     throws CertificateParsingException {
 404         return null;
 405     }
 406
 407     /**
 408      * Returns a read-only list of the issuer alternative names from the {@code
 409      * IssuerAltName} extension.
 410      * <p>
 411      * The ASN.1 definition of {@code IssuerAltName}:
 412      *
 413      * <pre>
 414      * IssuerAltName ::= GeneralNames
 415      *
 416      * GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName
 417      *
 418      * GeneralName ::= CHOICE {
 419      *      otherName                       [0]     AnotherName,
 420      *      rfc822Name                      [1]     IA5String,
 421      *      dNSName                         [2]     IA5String,
 422      *      x400Address                     [3]     ORAddress,
 423      *      directoryName                   [4]     Name,
 424      *      ediPartyName                    [5]     EDIPartyName,
 425      *      uniformResourceIdentifier       [6]     IA5String,
 426      *      iPAddress                       [7]     OCTET STRING,
 427      *      registeredID                    [8]     OBJECT IDENTIFIER }
 428      *
 429      * </pre>
 430      *
 431      * @return the issuer alternative names of {@code null} if there are none in
 432      *         the certificate.
 433      * @throws CertificateParsingException
 434      *             if decoding of the extension fails.
 435      */
 436     public Collection<List<?>> getIssuerAlternativeNames()
 437                                     throws CertificateParsingException {
 438         return null;
 439     }
 440 }