content: /*
   * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package java.security.cert;
  
  import java.security.NoSuchAlgorithmException;
  import java.security.NoSuchProviderException;
  import java.security.InvalidKeyException;
  import java.security.SignatureException;
  import java.security.Principal;
  import java.security.Provider;
  import java.security.PublicKey;
  import javax.security.auth.x500.X500Principal;
  
  import java.math.BigInteger;
  import java.util.Date;
  import java.util.Set;
  import java.util.Arrays;
  
  import sun.security.x509.X509CRLImpl;
  
  /**
   * <p>
   * Abstract class for an X.509 Certificate Revocation List (CRL).
   * A CRL is a time-stamped list identifying revoked certificates.
   * It is signed by a Certificate Authority (CA) and made freely
   * available in a public repository.
   *
   * <p>Each revoked certificate is
   * identified in a CRL by its certificate serial number. When a
   * certificate-using system uses a certificate (e.g., for verifying a
   * remote user's digital signature), that system not only checks the
   * certificate signature and validity but also acquires a suitably-
   * recent CRL and checks that the certificate serial number is not on
   * that CRL.  The meaning of "suitably-recent" may vary with local
   * policy, but it usually means the most recently-issued CRL.  A CA
   * issues a new CRL on a regular periodic basis (e.g., hourly, daily, or
   * weekly).  Entries are added to CRLs as revocations occur, and an
   * entry may be removed when the certificate expiration date is reached.
   * <p>
   * The X.509 v2 CRL format is described below in ASN.1:
   * <pre>
   * CertificateList  ::=  SEQUENCE  {
   *     tbsCertList          TBSCertList,
   *     signatureAlgorithm   AlgorithmIdentifier,
   *     signature            BIT STRING  }
   * </pre>
   * <p>
   * More information can be found in
   * <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280: Internet X.509
   * Public Key Infrastructure Certificate and CRL Profile</a>.
   * <p>
   * The ASN.1 definition of {@code tbsCertList} is:
   * <pre>
   * TBSCertList  ::=  SEQUENCE  {
   *     version                 Version OPTIONAL,
   *                             -- if present, must be v2
   *     signature               AlgorithmIdentifier,
   *     issuer                  Name,
   *     thisUpdate              ChoiceOfTime,
   *     nextUpdate              ChoiceOfTime OPTIONAL,
   *     revokedCertificates     SEQUENCE OF SEQUENCE  {
   *         userCertificate         CertificateSerialNumber,
   *         revocationDate          ChoiceOfTime,
   *         crlEntryExtensions      Extensions OPTIONAL
   *                                 -- if present, must be v2
   *         }  OPTIONAL,
   *     crlExtensions           [0]  EXPLICIT Extensions OPTIONAL
   *                                  -- if present, must be v2
   *     }
   * </pre>
   * <p>
   * CRLs are instantiated using a certificate factory. The following is an
   * example of how to instantiate an X.509 CRL:
   * <pre>{@code
   * try (InputStream inStream = new FileInputStream("fileName-of-crl")) {
   *     CertificateFactory cf = CertificateFactory.getInstance("X.509");
   *     X509CRL crl = (X509CRL)cf.generateCRL(inStream);
   * }
   * }</pre>
   *
   * @author Hemma Prafullchandra
   *
   *
   * @see CRL
   * @see CertificateFactory
   * @see X509Extension
   */
  
  public abstract class X509CRL extends CRL implements X509Extension {
  
      private transient X500Principal issuerPrincipal;
  
      /**
       * Constructor for X.509 CRLs.
       */
      protected X509CRL() {
          super("X.509");
      }
  
      /**
       * Compares this CRL for equality with the given
       * object. If the {@code other} object is an
       * {@code instanceof} {@code X509CRL}, then
       * its encoded form is retrieved and compared with the
       * encoded form of this CRL.
       *
       * @param other the object to test for equality with this CRL.
       *
       * @return true iff the encoded forms of the two CRLs
       * match, false otherwise.
       */
      public boolean equals(Object other) {
          if (this == other) {
              return true;
          }
          if (!(other instanceof X509CRL)) {
              return false;
          }
          try {
              byte[] thisCRL = X509CRLImpl.getEncodedInternal(this);
              byte[] otherCRL = X509CRLImpl.getEncodedInternal((X509CRL)other);
  
              return Arrays.equals(thisCRL, otherCRL);
          } catch (CRLException e) {
              return false;
          }
      }
  
      /**
       * Returns a hashcode value for this CRL from its
       * encoded form.
       *
       * @return the hashcode value.
       */
      public int hashCode() {
          int retval = 0;
          try {
              byte[] crlData = X509CRLImpl.getEncodedInternal(this);
              for (int i = 1; i < crlData.length; i++) {
                   retval += crlData[i] * i;
              }
              return retval;
          } catch (CRLException e) {
              return retval;
          }
      }
  
      /**
       * Returns the ASN.1 DER-encoded form of this CRL.
       *
       * @return the encoded form of this certificate
       * @exception CRLException if an encoding error occurs.
       */
      public abstract byte[] getEncoded()
          throws CRLException;
  
      /**
       * Verifies that this CRL was signed using the
       * private key that corresponds to the given public key.
       *
       * @param key the PublicKey used to carry out the verification.
       *
       * @exception NoSuchAlgorithmException on unsupported signature
       * algorithms.
       * @exception InvalidKeyException on incorrect key.
       * @exception NoSuchProviderException if there's no default provider.
       * @exception SignatureException on signature errors.
       * @exception CRLException on encoding errors.
       */
      public abstract void verify(PublicKey key)
          throws CRLException,  NoSuchAlgorithmException,
          InvalidKeyException, NoSuchProviderException,
          SignatureException;
  
      /**
       * Verifies that this CRL was signed using the
       * private key that corresponds to the given public key.
       * This method uses the signature verification engine
       * supplied by the given provider.
       *
       * @param key the PublicKey used to carry out the verification.
       * @param sigProvider the name of the signature provider.
       *
       * @exception NoSuchAlgorithmException on unsupported signature
       * algorithms.
       * @exception InvalidKeyException on incorrect key.
       * @exception NoSuchProviderException on incorrect provider.
       * @exception SignatureException on signature errors.
       * @exception CRLException on encoding errors.
       */
      public abstract void verify(PublicKey key, String sigProvider)
          throws CRLException, NoSuchAlgorithmException,
          InvalidKeyException, NoSuchProviderException,
          SignatureException;
  
      /**
       * Verifies that this CRL was signed using the
       * private key that corresponds to the given public key.
       * This method uses the signature verification engine
       * supplied by the given provider. Note that the specified Provider object
       * does not have to be registered in the provider list.
       *
       * This method was added to version 1.8 of the Java Platform Standard
       * Edition. In order to maintain backwards compatibility with existing
       * service providers, this method is not {@code abstract}
       * and it provides a default implementation.
       *
       * @param key the PublicKey used to carry out the verification.
       * @param sigProvider the signature provider.
       *
       * @exception NoSuchAlgorithmException on unsupported signature
       * algorithms.
       * @exception InvalidKeyException on incorrect key.
       * @exception SignatureException on signature errors.
       * @exception CRLException on encoding errors.
       * @since 1.8
       */
      public void verify(PublicKey key, Provider sigProvider)
          throws CRLException, NoSuchAlgorithmException,
          InvalidKeyException, SignatureException {
          // Android-changed: Eliminate infinite recursion in default implementation.
          // As the javadoc says, this "default implementation" was introduced as to avoid breaking
          // providers that generate concrete subclasses of this class.
          // The method X509Impl in the original definition calls this method, thus entering an
          // infinite recursive loop. This strange behaviour was checked to be not specific to
          // libcore by running a test with vogar --mode=jvm .  See b/31294527.
          // This is fixed upstream in OpenJDK 10.
          //
          // X509CRLImpl.verify(this, key, sigProvider);
          throw new UnsupportedOperationException(
                  "X509CRL instance doesn't not support X509CRL#verify(PublicKey, Provider)");
      }
  
      /**
       * Gets the {@code version} (version number) value from the CRL.
       * The ASN.1 definition for this is:
       * <pre>
       * version    Version OPTIONAL,
       *             -- if present, must be v2
       *
       * Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
       *             -- v3 does not apply to CRLs but appears for consistency
       *             -- with definition of Version for certs
       * </pre>
       *
       * @return the version number, i.e. 1 or 2.
       */
      public abstract int getVersion();
  
      /**
       * <strong>Denigrated</strong>, replaced by {@linkplain
       * #getIssuerX500Principal()}. This method returns the {@code issuer}
       * as an implementation specific Principal object, which should not be
       * relied upon by portable code.
       *
       * <p>
       * Gets the {@code issuer} (issuer distinguished name) value from
       * the CRL. The issuer name identifies the entity that signed (and
       * issued) the CRL.
       *
       * <p>The issuer name field contains an
       * X.500 distinguished name (DN).
       * The ASN.1 definition for this is:
       * <pre>
       * issuer    Name
       *
       * Name ::= CHOICE { RDNSequence }
       * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
       * RelativeDistinguishedName ::=
       *     SET OF AttributeValueAssertion
       *
       * AttributeValueAssertion ::= SEQUENCE {
       *                               AttributeType,
       *                               AttributeValue }
       * AttributeType ::= OBJECT IDENTIFIER
       * AttributeValue ::= ANY
       * </pre>
       * The {@code Name} describes a hierarchical name composed of
       * attributes,
       * such as country name, and corresponding values, such as US.
       * The type of the {@code AttributeValue} component is determined by
       * the {@code AttributeType}; in general it will be a
       * {@code directoryString}. A {@code directoryString} is usually
       * one of {@code PrintableString},
       * {@code TeletexString} or {@code UniversalString}.
       *
       * @return a Principal whose name is the issuer distinguished name.
       */
      public abstract Principal getIssuerDN();
  
      /**
       * Returns the issuer (issuer distinguished name) value from the
       * CRL as an {@code X500Principal}.
       * <p>
       * It is recommended that subclasses override this method.
       *
       * @return an {@code X500Principal} representing the issuer
       *          distinguished name
       * @since 1.4
       */
      public X500Principal getIssuerX500Principal() {
          if (issuerPrincipal == null) {
              issuerPrincipal = X509CRLImpl.getIssuerX500Principal(this);
          }
          return issuerPrincipal;
      }
  
      /**
       * Gets the {@code thisUpdate} date from the CRL.
       * The ASN.1 definition for this is:
       * <pre>
       * thisUpdate   ChoiceOfTime
       * ChoiceOfTime ::= CHOICE {
       *     utcTime        UTCTime,
       *     generalTime    GeneralizedTime }
       * </pre>
       *
       * @return the {@code thisUpdate} date from the CRL.
       */
      public abstract Date getThisUpdate();
  
      /**
       * Gets the {@code nextUpdate} date from the CRL.
       *
       * @return the {@code nextUpdate} date from the CRL, or null if
       * not present.
       */
      public abstract Date getNextUpdate();
  
      /**
       * Gets the CRL entry, if any, with the given certificate serialNumber.
       *
       * @param serialNumber the serial number of the certificate for which a CRL entry
       * is to be looked up
       * @return the entry with the given serial number, or null if no such entry
       * exists in this CRL.
       * @see X509CRLEntry
       */
      public abstract X509CRLEntry
          getRevokedCertificate(BigInteger serialNumber);
  
      /**
       * Get the CRL entry, if any, for the given certificate.
       *
       * <p>This method can be used to lookup CRL entries in indirect CRLs,
       * that means CRLs that contain entries from issuers other than the CRL
       * issuer. The default implementation will only return entries for
       * certificates issued by the CRL issuer. Subclasses that wish to
       * support indirect CRLs should override this method.
       *
       * @param certificate the certificate for which a CRL entry is to be looked
       *   up
       * @return the entry for the given certificate, or null if no such entry
       *   exists in this CRL.
       * @exception NullPointerException if certificate is null
       *
       * @since 1.5
       */
      public X509CRLEntry getRevokedCertificate(X509Certificate certificate) {
          X500Principal certIssuer = certificate.getIssuerX500Principal();
          X500Principal crlIssuer = getIssuerX500Principal();
          if (certIssuer.equals(crlIssuer) == false) {
              return null;
          }
          return getRevokedCertificate(certificate.getSerialNumber());
      }
  
      /**
       * Gets all the entries from this CRL.
       * This returns a Set of X509CRLEntry objects.
       *
       * @return all the entries or null if there are none present.
       * @see X509CRLEntry
       */
      public abstract Set<? extends X509CRLEntry> getRevokedCertificates();
  
      /**
       * Gets the DER-encoded CRL information, the
       * {@code tbsCertList} from this CRL.
       * This can be used to verify the signature independently.
       *
       * @return the DER-encoded CRL information.
       * @exception CRLException if an encoding error occurs.
       */
      public abstract byte[] getTBSCertList() throws CRLException;
  
      /**
       * Gets the {@code signature} value (the raw signature bits) from
       * the CRL.
       * The ASN.1 definition for this is:
       * <pre>
       * signature     BIT STRING
       * </pre>
       *
       * @return the signature.
       */
      public abstract byte[] getSignature();
  
      /**
       * Gets the signature algorithm name for the CRL
       * signature algorithm. An example is the string "SHA256withRSA".
       * The ASN.1 definition for this is:
       * <pre>
       * signatureAlgorithm   AlgorithmIdentifier
       *
       * AlgorithmIdentifier  ::=  SEQUENCE  {
       *     algorithm               OBJECT IDENTIFIER,
       *     parameters              ANY DEFINED BY algorithm OPTIONAL  }
       *                             -- contains a value of the type
       *                             -- registered for use with the
       *                             -- algorithm object identifier value
       * </pre>
       *
       * <p>The algorithm name is determined from the {@code algorithm}
       * OID string.
       *
       * @return the signature algorithm name.
       */
      public abstract String getSigAlgName();
  
      /**
       * Gets the signature algorithm OID string from the CRL.
       * An OID is represented by a set of nonnegative whole numbers separated
       * by periods.
       * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
       * with DSA signature algorithm defined in
       * <a href="http://www.ietf.org/rfc/rfc3279.txt">RFC 3279: Algorithms and
       * Identifiers for the Internet X.509 Public Key Infrastructure Certificate
       * and CRL Profile</a>.
       *
       * <p>See {@link #getSigAlgName() getSigAlgName} for
       * relevant ASN.1 definitions.
       *
       * @return the signature algorithm OID string.
       */
      public abstract String getSigAlgOID();
  
      /**
       * Gets the DER-encoded signature algorithm parameters from this
       * CRL's signature algorithm. In most cases, the signature
       * algorithm parameters are null; the parameters are usually
       * supplied with the public key.
       * If access to individual parameter values is needed then use
       * {@link java.security.AlgorithmParameters AlgorithmParameters}
       * and instantiate with the name returned by
       * {@link #getSigAlgName() getSigAlgName}.
       *
       * <p>See {@link #getSigAlgName() getSigAlgName} for
       * relevant ASN.1 definitions.
       *
       * @return the DER-encoded signature algorithm parameters, or
       *         null if no parameters are present.
       */
      public abstract byte[] getSigAlgParams();
  }
  