/*
 * @(#)X509Certificate.java	1.11 97/10/24
 *
 * Copyright 1993-1997 Sun Microsystems, Inc. 901 San Antonio Road,
 * Palo Alto, California, 94303, U.S.A.  All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * CopyrightVersion 1.2
 *
 */

package com.novell.java.security.cert;

import java.io.InputStream;
import java.lang.Class;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.security.Security;

import java.math.BigInteger;
import com.novell.java.security.Principal;
import com.novell.java.security.PublicKey;
import java.util.BitSet;
import java.util.Date;
import com.novell.java.util.Set;

/**
 * <p>
 * Abstract class for X.509 certificates. This provides a standard
 * way to access all the attributes of an X.509 certificate.
 * <p>
 * In June of 1996, the basic X.509 v3 format was completed by
 * ISO/IEC and ANSI X9, which is described below in ASN.1:
 * <pre>
 * Certificate  ::=  SEQUENCE  {
 *     tbsCertificate       TBSCertificate,
 *     signatureAlgorithm   AlgorithmIdentifier,
 *     signature            BIT STRING  }
 * </pre>
 * <p>
 * These certificates are widely used to support authentication and
 * other functionality in Internet security systems. Common applications
 * include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL),
 * code signing for trusted software distribution, and Secure Electronic
 * Transactions (SET).
 * <p>
 * These certificates are managed and vouched for by <em>Certificate
 * Authorities</em> (CAs). CAs are services which create certificates by
 * placing data in the X.509 standard format and then digitally signing
 * that data. CAs act as trusted third parties, making introductions
 * between principals who have no direct knowledge of each other.
 * CA certificates are either signed by themselves, or by some other
 * CA such as a "root" CA.
 * <p>
 * A good decription and profiling is provided in the IETF PKIX WG
 * draft, Part I:  X.509 Certificate and CRL Profile,
 * &lt;draft-ietf-pkix-ipki-part1-06.txt&gt;.
 * <p>
 * The ASN.1 definition of <code>tbsCertificate</code> is:
 * <pre>
 * TBSCertificate  ::=  SEQUENCE  {
 *     version         [0]  EXPLICIT Version DEFAULT v1,
 *     serialNumber         CertificateSerialNumber,
 *     signature            AlgorithmIdentifier,
 *     issuer               Name,
 *     validity             Validity,
 *     subject              Name,
 *     subjectPublicKeyInfo SubjectPublicKeyInfo,
 *     issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
 *                          -- If present, version must be v2 or v3
 *     subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
 *                          -- If present, version must be v2 or v3
 *     extensions      [3]  EXPLICIT Extensions OPTIONAL
 *                          -- If present, version must be v3
 *     }
 * </pre>
 * <p>
 * Here is sample code to instantiate an X.509 certificate:
 * <pre>
 * InputStream inStream = new FileInputStream("fileName-of-cert");
 * X509Certificate cert = X509Certificate.getInstance(inStream);
 * inStream.close();
 * </pre>
 * OR
 * <pre>
 * byte[] certData = &lt;certificate read from a file, say&gt;
 * X509Certificate cert = X509Certificate.getInstance(certData);
 * </pre>
 * <p>
 * In either case, the code that instantiates an X.509 certificate
 * consults the Java security properties file to locate the actual
 * implementation.  The default implementation for the
 * <code>java.security.cert</code> package is the Sun X.509 v3
 * implementation, from what is known to the <code>java.security</code>
 * APIs as the "SUN" provider.
 *
 * <p>
 * The Java security properties file is located in the file named
 * &lt;JAVA_HOME&gt;/lib/security/java.security, where &lt;JAVA_HOME&gt;
 * refers to the directory where the JDK was installed.
 * In the Security properties file, the default implementation
 * for X.509 v3 is given as:
 * <pre>
 * cert.provider.x509=sun.security.x509.X509CertImpl
 * </pre>
 * <p>
 * The value of this <code>cert.provider.x509</code> property has to be
 * changed to instatiate another implementation.
 *
 * @author Hemma Prafullchandra
 * @version 1.11
 * @see Certificate
 * @see X509Extension
 */
public abstract class X509Certificate extends Certificate
implements X509Extension {

    /*
     * Constant to lookup in the Security properties file.
     * In the Security properties file the default implementation
     * for X.509 v3 is given as:
     * <pre>
     * cert.provider.x509=sun.security.x509.X509CertImpl
     * </pre>
     */
    private static final String X509_PROVIDER = "cert.provider.x509";

    /**
     * Instantiates an X509Certificate object, and initializes it with
     * the data read from the input stream <code>inStream</code>.
     * The implementation (X509Certificate is an abstract class) is
     * provided by the class specified as the value of the
     * <code>cert.provider.x509</code>
     * property in the security properties file.
     *
     * <p>Note: Only one DER-encoded
     * certificate is expected to be in the input stream.
     * Also, all X509Certificate
     * subclasses must provide a constructor of the form:
     * <code><pre>
     * public &lt;subClass&gt;(InputStream inStream) ...
     * </code></pre>
     *
     * @param inStream an input stream with the data to be read to
     *        initialize the certificate.
     * @return an X509Certificate object initialized with the data
     * from the input stream.
     * @exception CertificateException if a class initialization
     *            or certificate parsing error occurs.
     */
    public static final X509Certificate getInstance(InputStream inStream)
    throws CertificateException {
        return getInst((Object)inStream);
    }

    /**
     * Instantiates an X509Certificate object, and initializes it with
     * the specified byte array.
     * The implementation (X509Certificate is an abstract class) is
     * provided by the class specified as the value of the
     * <code>cert.provider.x509</code>
     * property in the security properties file.
     *
     * <p>Note: All X509Certificate
     * subclasses must provide a constructor of the form:
     * <code><pre>
     * public &lt;subClass&gt;(InputStream inStream) ...
     * </code></pre>
     *
     * @param certData a byte array containing the DER-encoded
     * certificate.
     * @return an X509Certificate object initialized with the data
     * from <code>certData</code>.
     * @exception CertificateException if a class initialization
     *            or certificate parsing error occurs.
     */
    public static final X509Certificate getInstance(byte[] certData)
    throws CertificateException {
        return getInst((Object)certData);
    }

    private static final X509Certificate getInst(Object value)
    throws CertificateException {
        String className = Security.getProperty(X509_PROVIDER);
        if (className == null) {
            // shouldn't happen, but assume corrupted properties file
            // provide access to sun implementation
            className = "sun.security.x509.X509CertImpl";
        }
        try {
            Class[] params = null;
            if (value instanceof InputStream) {
                params = new Class[] { InputStream.class };
            } else if (value instanceof byte[]) {
                params = new Class[] { value.getClass() };
            } else
                throw new CertificateException("Unsupported argument type");
            Class certClass = Class.forName(className);

            // get the appropriate constructor and instantiate it
            Constructor cons = certClass.getConstructor(params);

            // get a new instance
            Object obj = cons.newInstance(new Object[] {value});
            return (X509Certificate)obj;

        } catch (ClassNotFoundException e) {
          throw new CertificateException("Could not find class: " + e);
        } catch (IllegalAccessException e) {
          throw new CertificateException("Could not access class: " + e);
        } catch (InstantiationException e) {
          throw new CertificateException("Problems instantiating: " + e);
        } catch (InvocationTargetException e) {
          throw new CertificateException("InvocationTargetException: "
                                         + e.getTargetException());
       } catch (NoSuchMethodException e) {
          throw new CertificateException("Could not find class method: "
                                          + e.getMessage());
        }
    }

    /**
     * Checks that the certificate is currently valid. It is if
     * the current date and time are within the validity period given in the
     * certificate.
     * <p>
     * The validity period consists of two date/time values:
     * the first and last dates (and times) on which the certificate
     * is valid. It is defined in
     * ASN.1 as:
     * <pre>
     * validity             Validity<p>
     * Validity ::= SEQUENCE {
     *     notBefore      CertificateValidityDate,
     *     notAfter       CertificateValidityDate }<p>
     * CertificateValidityDate ::= CHOICE {
     *     utcTime        UTCTime,
     *     generalTime    GeneralizedTime }
     * </pre>
     *
     * @exception CertificateParsingException if a parsing error occurs.
     * @exception CertificateExpiredException if the certificate has expired.
     * @exception CertificateNotYetValidException if the certificate is not
     * yet valid.
     */
    public abstract void checkValidity()
        throws CertificateParsingException, CertificateExpiredException,
        CertificateNotYetValidException;

    /**
     * Checks that the specified date is within the certificate's
     * validity period. In other words, this determines whether the
     * certificate would be valid at the specified date/time.
     *
     * @param date the Date to check against to see if this certificate
     *        is valid at that date/time.
     *
     * @exception CertificateParsingException if a parsing error occurs.
     * @exception CertificateExpiredException if the certificate has expired
     * with respect to the <code>date</code> supplied.
     * @exception CertificateNotYetValidException if the certificate is not
     * yet valid with respect to the <code>date</code> supplied.
     *
     * @see #checkValidity()
     */
    public abstract void checkValidity(Date date)
        throws CertificateParsingException, CertificateExpiredException,
        CertificateNotYetValidException;

    /**
     * Gets the <code>version</code> (version number) value from the certificate.
     * The ASN.1 definition for this is:
     * <pre>
     * version         [0]  EXPLICIT Version DEFAULT v1<p>
     * Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
     * </pre>
     * @return the version number.
     */
    public abstract int getVersion();

    /**
     * Gets the <code>serialNumber</code> value from the certificate.
     * The serial number is an integer assigned by the certification
     * authority to each certificate. It must be unique for each
     * certificate issued by a given CA (i.e., the issuer name and
     * serial number identify a unique certificate).
     * The ASN.1 definition for this is:
     * <pre>
     * serialNumber     CertificateSerialNumber<p>
     *
     * CertificateSerialNumber  ::=  INTEGER
     * </pre>
     *
     * @return the serial number.
     */
    public abstract BigInteger getSerialNumber();

    /**
     * Gets the <code>issuer</code> (issuer distinguished name) value from
     * the certificate. The issuer name identifies the entity that signed (and
     * issued) the certificate.
     *
     * <p>The issuer name field contains an
     * X.500 distinguished name (DN).
     * The ASN.1 definition for this is:
     * <pre>
     * issuer    Name<p>
     *
     * Name ::= CHOICE { RDNSequence }
     * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
     * RelativeDistinguishedName ::=
     *     SET OF AttributeValueAssertion
     *
     * AttributeValueAssertion ::= SEQUENCE {
     *                               AttributeType,
     *                               AttributeValue }
     * AttributeType ::= OBJECT IDENTIFIER
     * AttributeValue ::= ANY
     * </pre>
     * The <code>Name</code> describes a hierarchical name composed of attributes,
     * such as country name, and corresponding values, such as US.
     * The type of the <code>AttributeValue</code> component is determined by the
     * <code>AttributeType</code>; in general it will be a
     * <code>directoryString</code>. A <code>directoryString</code> is usually
     * one of <code>PrintableString</code>,
     * <code>TeletexString</code> or <code>UniversalString</code>.
     *
     * @return a Principal whose name is the issuer distinguished name.
     */
    public abstract Principal getIssuerDN();

    /**
     * Gets the <code>subject</code> (subject distinguished name) value
     * from the certificate.
     * The ASN.1 definition for this is:
     * <pre>
     * subject    Name
     * </pre>
     *
     * <p>See <a href = "#getIssuerDN">getIssuerDN</a> for <code>Name</code>
     * and other relevant definitions.
     *
     * @return a Principal whose name is the subject name.
     */
    public abstract Principal getSubjectDN();

    /**
     * Gets the <code>notBefore</code> date from the validity period of
     * the certificate.
     * The relevant ASN.1 definitions are:
     * <pre>
     * validity             Validity<p>
     *
     * Validity ::= SEQUENCE {
     *     notBefore      CertificateValidityDate,
     *     notAfter       CertificateValidityDate }<p>
     * CertificateValidityDate ::= CHOICE {
     *     utcTime        UTCTime,
     *     generalTime    GeneralizedTime }
     * </pre>
     *
     * @return the start date of the validity period.
     * @see #checkValidity
     */
    public abstract Date getNotBefore();

    /**
     * Gets the <code>notAfter</code> date from the validity period of
     * the certificate. See <a href = "#getNotBefore">getNotBefore</a>
     * for relevant ASN.1 definitions.
     *
     * @return the end date of the validity period.
     * @see #checkValidity
     */
    public abstract Date getNotAfter();

    /**
     * Gets the DER-encoded certificate information, the
     * <code>tbsCertificate</code> from this certificate.
     * This can be used to verify the signature independently.
     *
     * @return the DER-encoded certificate information.
     * @exception CertificateEncodingException if an encoding error occurs.
     */
    public abstract byte[] getTBSCertificate()
        throws CertificateEncodingException;

    /**
     * Gets the <code>signature</code> value (the raw signature bits) from
     * the certificate.
     * 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 certificate
     * signature algorithm. An example is the string "SHA-1/DSA".
     * The ASN.1 definition for this is:
     * <pre>
     * signatureAlgorithm   AlgorithmIdentifier<p>
     * 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</code>
     * OID string.
     *
     * @return the signature algorithm name.
     */
    public abstract String getSigAlgName();

    /**
     * Gets the signature algorithm OID string from the certificate.
     * An OID is represented by a set of positive whole numbers separated
     * by periods.
     * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
     * with DSA signature algorithm, as per the PKIX part I.
     *
     * <p>See <a href = "#getSigAlgName">getSigAlgName</a> for
     * relevant ASN.1 definitions.
     *
     * @return the signature algorithm OID string.
     */
    public abstract String getSigAlgOID();

    /**
     * Gets the DER-encoded signature algorithm parameters from this
     * certificate's signature algorithm. In most cases, the signature
     * algorithm parameters are null; the parameters are usually
     * supplied with the certificate's public key.
     * If access to individual parameter values is needed then use
     * <a href="java.security.AlgorithmParameters.html">
     * AlgorithmParameters</a>
     * and instantiate with the name returned by
     * <a href = "#getSigAlgName">getSigAlgName</a>.
     *
     * <p>See <a href = "#getSigAlgName">getSigAlgName</a> for
     * relevant ASN.1 definitions.
     *
     * @return the DER-encoded signature algorithm parameters, or
     *         null if no parameters are present.
     */
    public abstract byte[] getSigAlgParams();

    /**
     * Gets the <code>issuerUniqueID</code> value from the certificate.
     * The issuer unique identifier is present in the certificate
     * to handle the possibility of reuse of issuer names over time.
     * The PKIX Part I recommends that names not be reused and that
     * conforming certificates not make use of unique identifiers.
     * Applications conforming to that profile should be capable of
     * parsing unique identifiers and making comparisons.
     *
     * <p>The ASN.1 definition for this is:
     * <pre>
     * issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL<p>
     * UniqueIdentifier  ::=  BIT STRING
     * </pre>
     *
     * @return the issuer unique identifier or null if it is not
     * present in the certificate.
     */
    public abstract boolean[] getIssuerUniqueID();

    /**
     * Gets the <code>subjectUniqueID</code> value from the certificate.
     *
     * <p>The ASN.1 definition for this is:
     * <pre>
     * subjectUniqueID  [2]  IMPLICIT UniqueIdentifier OPTIONAL<p>
     * UniqueIdentifier  ::=  BIT STRING
     * </pre>
     *
     * @return the subject unique identifier or null if it is not
     * present in the certificate.
     */
    public abstract boolean[] getSubjectUniqueID();

    /**
     * Gets a boolean array representing bits of
     * the <code>KeyUsage</code> extension, (OID = 2.5.29.15).
     * The key usage extension defines the purpose (e.g., encipherment,
     * signature, certificate signing) of the key contained in the
     * certificate.
     * The ASN.1 definition for this is:
     * <pre>
     * KeyUsage ::= BIT STRING {
     *     digitalSignature        (0),
     *     nonRepudiation          (1),
     *     keyEncipherment         (2),
     *     dataEncipherment        (3),
     *     keyAgreement            (4),
     *     keyCertSign             (5),
     *     cRLSign                 (6),
     *     encipherOnly            (7),
     *     decipherOnly            (8) }
     * </pre>
     * The PKIX part I draft recommends that when used, this be marked
     * as a critical extension.
     *
     * @return the bit values of the KeyUsage extension as an array of booleans,
     * or null if the KeyUsage extension is not present in the certificate.
     */
    public abstract boolean[] getKeyUsage();

    /**
     * Gets the certificate constraints path length from the
     * critical <code>BasicConstraints</code> extension, (OID = 2.5.29.19).
     * <p>
     * The basic constraints extension identifies whether the subject
     * of the certificate is a Certificate Authority (CA) and
     * how deep a certification path may exist through that CA. The
     * <code>pathLenConstraint</code> field (see below) is meaningful
     * only if <code>cA</code> is set to TRUE. In this case, it gives the maximum
     * number of CA certificates that may follow this certificate in a
     * certification path. A value of zero indicates that only an end-entity
     * certificate may follow in the path.
     * <p>
     * Note that for the PKIX profile this extension is always marked
     * critical if <code>cA</code> is TRUE, meaning this certificate belongs
     * to a Certificate Authority.
     * <p>
     * The ASN.1 definition for this is:
     * <pre>
     * BasicConstraints ::= SEQUENCE {
     *     cA                  BOOLEAN DEFAULT FALSE,
     *     pathLenConstraint   INTEGER (0..MAX) OPTIONAL }
     * </pre>
     *
     * @return the length of the constraint if the BasicConstraints extension is
     * present in the certificate and the <code>cA</code> value is TRUE.
     * Otherwise returns -1.
     */
    public abstract int getBasicConstraints();
}
