/*
* Copyright (c) 1997, 2006, 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.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</code> 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>
* InputStream inStream = null;
* try {
* inStream = new FileInputStream("fileName-of-crl");
* CertificateFactory cf = CertificateFactory.getInstance("X.509");
* X509CRL crl = (X509CRL)cf.generateCRL(inStream);
* } finally {
* if (inStream != null) {
* inStream.close();
* }
* }
* </code></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</code> object is an
* <code>instanceof</code> <code>X509CRL</code>, 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;
/**
* Gets the <code>version</code> (version number) value from the CRL.
* The ASN.1 definition for this is:
* <pre>
* version Version OPTIONAL,
* -- if present, must be v2<p>
* 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</code>
* as an implementation specific Principal object, which should not be
* relied upon by portable code.
*
* <p>
* Gets the <code>issuer</code> (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</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();
/**
* Returns the issuer (issuer distinguished name) value from the
* CRL as an <code>X500Principal</code>.
* <p>
* It is recommended that subclasses override this method.
*
* @return an <code>X500Principal</code> representing the issuer
* distinguished name
* @since 1.4
*/
public X500Principal getIssuerX500Principal() {
if (issuerPrincipal == null) {
issuerPrincipal = X509CRLImpl.getIssuerX500Principal(this);
}
return issuerPrincipal;
}
/**
* Gets the <code>thisUpdate</code> 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</code> date from the CRL.
*/
public abstract Date getThisUpdate();
/**
* Gets the <code>nextUpdate</code> date from the CRL.
*
* @return the <code>nextUpdate</code> 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</code> 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</code> 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 "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 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();
}