001: /*
002: * @(#)X509CRL.java 1.25 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.security.cert;
029:
030: import java.security.NoSuchAlgorithmException;
031: import java.security.NoSuchProviderException;
032: import java.security.InvalidKeyException;
033: import java.security.SignatureException;
034: import java.security.Principal;
035: import java.security.PublicKey;
036: import javax.security.auth.x500.X500Principal;
037:
038: import java.math.BigInteger;
039: import java.util.Date;
040: import java.util.Set;
041: import java.util.Arrays;
042:
043: import sun.security.x509.X509CRLImpl;
044:
045: /**
046: * <p>
047: * Abstract class for an X.509 Certificate Revocation List (CRL).
048: * A CRL is a time-stamped list identifying revoked certificates.
049: * It is signed by a Certificate Authority (CA) and made freely
050: * available in a public repository.
051: *
052: * <p>Each revoked certificate is
053: * identified in a CRL by its certificate serial number. When a
054: * certificate-using system uses a certificate (e.g., for verifying a
055: * remote user's digital signature), that system not only checks the
056: * certificate signature and validity but also acquires a suitably-
057: * recent CRL and checks that the certificate serial number is not on
058: * that CRL. The meaning of "suitably-recent" may vary with local
059: * policy, but it usually means the most recently-issued CRL. A CA
060: * issues a new CRL on a regular periodic basis (e.g., hourly, daily, or
061: * weekly). Entries are added to CRLs as revocations occur, and an
062: * entry may be removed when the certificate expiration date is reached.
063: * <p>
064: * The X.509 v2 CRL format is described below in ASN.1:
065: * <pre>
066: * CertificateList ::= SEQUENCE {
067: * tbsCertList TBSCertList,
068: * signatureAlgorithm AlgorithmIdentifier,
069: * signature BIT STRING }
070: * </pre>
071: * <p>
072: * More information can be found in RFC 2459,
073: * "Internet X.509 Public Key Infrastructure Certificate and CRL
074: * Profile" at <A HREF="http://www.ietf.org/rfc/rfc2459.txt">
075: * http://www.ietf.org/rfc/rfc2459.txt </A>.
076: * <p>
077: * The ASN.1 definition of <code>tbsCertList</code> is:
078: * <pre>
079: * TBSCertList ::= SEQUENCE {
080: * version Version OPTIONAL,
081: * -- if present, must be v2
082: * signature AlgorithmIdentifier,
083: * issuer Name,
084: * thisUpdate ChoiceOfTime,
085: * nextUpdate ChoiceOfTime OPTIONAL,
086: * revokedCertificates SEQUENCE OF SEQUENCE {
087: * userCertificate CertificateSerialNumber,
088: * revocationDate ChoiceOfTime,
089: * crlEntryExtensions Extensions OPTIONAL
090: * -- if present, must be v2
091: * } OPTIONAL,
092: * crlExtensions [0] EXPLICIT Extensions OPTIONAL
093: * -- if present, must be v2
094: * }
095: * </pre>
096: * <p>
097: * CRLs are instantiated using a certificate factory. The following is an
098: * example of how to instantiate an X.509 CRL:
099: * <pre><code>
100: * InputStream inStream = new FileInputStream("fileName-of-crl");
101: * CertificateFactory cf = CertificateFactory.getInstance("X.509");
102: * X509CRL crl = (X509CRL)cf.generateCRL(inStream);
103: * inStream.close();
104: * </code></pre>
105: *
106: * @author Hemma Prafullchandra
107: *
108: * @version 1.25, 10/10/06
109: *
110: * @see CRL
111: * @see CertificateFactory
112: * @see X509Extension
113: */
114:
115: public abstract class X509CRL extends CRL implements X509Extension {
116:
117: private transient X500Principal issuerPrincipal;
118:
119: /**
120: * Constructor for X.509 CRLs.
121: */
122: protected X509CRL() {
123: super ("X.509");
124: }
125:
126: /**
127: * Compares this CRL for equality with the given
128: * object. If the <code>other</code> object is an
129: * <code>instanceof</code> <code>X509CRL</code>, then
130: * its encoded form is retrieved and compared with the
131: * encoded form of this CRL.
132: *
133: * @param other the object to test for equality with this CRL.
134: *
135: * @return true iff the encoded forms of the two CRLs
136: * match, false otherwise.
137: */
138: public boolean equals(Object other) {
139: if (this == other) {
140: return true;
141: }
142: if (!(other instanceof X509CRL)) {
143: return false;
144: }
145: try {
146: byte[] this CRL = X509CRLImpl.getEncodedInternal(this );
147: byte[] otherCRL = X509CRLImpl
148: .getEncodedInternal((X509CRL) other);
149:
150: return Arrays.equals(this CRL, otherCRL);
151: } catch (CRLException e) {
152: return false;
153: }
154: }
155:
156: /**
157: * Returns a hashcode value for this CRL from its
158: * encoded form.
159: *
160: * @return the hashcode value.
161: */
162: public int hashCode() {
163: int retval = 0;
164: try {
165: byte[] crlData = X509CRLImpl.getEncodedInternal(this );
166: for (int i = 1; i < crlData.length; i++) {
167: retval += crlData[i] * i;
168: }
169: return retval;
170: } catch (CRLException e) {
171: return retval;
172: }
173: }
174:
175: /**
176: * Returns the ASN.1 DER-encoded form of this CRL.
177: *
178: * @return the encoded form of this certificate
179: * @exception CRLException if an encoding error occurs.
180: */
181: public abstract byte[] getEncoded() throws CRLException;
182:
183: /**
184: * Verifies that this CRL was signed using the
185: * private key that corresponds to the given public key.
186: *
187: * @param key the PublicKey used to carry out the verification.
188: *
189: * @exception NoSuchAlgorithmException on unsupported signature
190: * algorithms.
191: * @exception InvalidKeyException on incorrect key.
192: * @exception NoSuchProviderException if there's no default provider.
193: * @exception SignatureException on signature errors.
194: * @exception CRLException on encoding errors.
195: */
196: public abstract void verify(PublicKey key) throws CRLException,
197: NoSuchAlgorithmException, InvalidKeyException,
198: NoSuchProviderException, SignatureException;
199:
200: /**
201: * Verifies that this CRL was signed using the
202: * private key that corresponds to the given public key.
203: * This method uses the signature verification engine
204: * supplied by the given provider.
205: *
206: * @param key the PublicKey used to carry out the verification.
207: * @param sigProvider the name of the signature provider.
208: *
209: * @exception NoSuchAlgorithmException on unsupported signature
210: * algorithms.
211: * @exception InvalidKeyException on incorrect key.
212: * @exception NoSuchProviderException on incorrect provider.
213: * @exception SignatureException on signature errors.
214: * @exception CRLException on encoding errors.
215: */
216: public abstract void verify(PublicKey key, String sigProvider)
217: throws CRLException, NoSuchAlgorithmException,
218: InvalidKeyException, NoSuchProviderException,
219: SignatureException;
220:
221: /**
222: * Gets the <code>version</code> (version number) value from the CRL.
223: * The ASN.1 definition for this is:
224: * <pre>
225: * version Version OPTIONAL,
226: * -- if present, must be v2<p>
227: * Version ::= INTEGER { v1(0), v2(1), v3(2) }
228: * -- v3 does not apply to CRLs but appears for consistency
229: * -- with definition of Version for certs
230: * </pre>
231: *
232: * @return the version number, i.e. 1 or 2.
233: */
234: public abstract int getVersion();
235:
236: /**
237: * Gets the <code>issuer</code> (issuer distinguished name) value from
238: * the CRL. The issuer name identifies the entity that signed (and
239: * issued) the CRL.
240: *
241: * <p>The issuer name field contains an
242: * X.500 distinguished name (DN).
243: * The ASN.1 definition for this is:
244: * <pre>
245: * issuer Name
246: *
247: * Name ::= CHOICE { RDNSequence }
248: * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
249: * RelativeDistinguishedName ::=
250: * SET OF AttributeValueAssertion
251: *
252: * AttributeValueAssertion ::= SEQUENCE {
253: * AttributeType,
254: * AttributeValue }
255: * AttributeType ::= OBJECT IDENTIFIER
256: * AttributeValue ::= ANY
257: * </pre>
258: * The <code>Name</code> describes a hierarchical name composed of
259: * attributes,
260: * such as country name, and corresponding values, such as US.
261: * The type of the <code>AttributeValue</code> component is determined by
262: * the <code>AttributeType</code>; in general it will be a
263: * <code>directoryString</code>. A <code>directoryString</code> is usually
264: * one of <code>PrintableString</code>,
265: * <code>TeletexString</code> or <code>UniversalString</code>.
266: *
267: * @return a Principal whose name is the issuer distinguished name.
268: */
269: public abstract Principal getIssuerDN();
270:
271: /**
272: * Returns the issuer (issuer distinguished name) value from the
273: * CRL as an <code>X500Principal</code>.
274: * <p>
275: * It is recommended that subclasses override this method to provide
276: * an efficient implementation.
277: *
278: * @return an <code>X500Principal</code> representing the issuer
279: * distinguished name
280: * @since 1.4
281: */
282: public X500Principal getIssuerX500Principal() {
283: if (issuerPrincipal == null) {
284: issuerPrincipal = X509CRLImpl.getIssuerX500Principal(this );
285: }
286: return issuerPrincipal;
287: }
288:
289: /**
290: * Gets the <code>thisUpdate</code> date from the CRL.
291: * The ASN.1 definition for this is:
292: * <pre>
293: * thisUpdate ChoiceOfTime
294: * ChoiceOfTime ::= CHOICE {
295: * utcTime UTCTime,
296: * generalTime GeneralizedTime }
297: * </pre>
298: *
299: * @return the <code>thisUpdate</code> date from the CRL.
300: */
301: public abstract Date getThisUpdate();
302:
303: /**
304: * Gets the <code>nextUpdate</code> date from the CRL.
305: *
306: * @return the <code>nextUpdate</code> date from the CRL, or null if
307: * not present.
308: */
309: public abstract Date getNextUpdate();
310:
311: /**
312: * Gets the CRL entry, if any, with the given certificate serialNumber.
313: *
314: * @param serialNumber the serial number of the certificate for which a CRL entry
315: * is to be looked up
316: * @return the entry with the given serial number, or null if no such entry
317: * exists in this CRL.
318: * @see X509CRLEntry
319: */
320: public abstract X509CRLEntry getRevokedCertificate(
321: BigInteger serialNumber);
322:
323: /**
324: * Gets all the entries from this CRL.
325: * This returns a Set of X509CRLEntry objects.
326: *
327: * @return all the entries or null if there are none present.
328: * @see X509CRLEntry
329: */
330: public abstract Set getRevokedCertificates();
331:
332: /**
333: * Gets the DER-encoded CRL information, the
334: * <code>tbsCertList</code> from this CRL.
335: * This can be used to verify the signature independently.
336: *
337: * @return the DER-encoded CRL information.
338: * @exception CRLException if an encoding error occurs.
339: */
340: public abstract byte[] getTBSCertList() throws CRLException;
341:
342: /**
343: * Gets the <code>signature</code> value (the raw signature bits) from
344: * the CRL.
345: * The ASN.1 definition for this is:
346: * <pre>
347: * signature BIT STRING
348: * </pre>
349: *
350: * @return the signature.
351: */
352: public abstract byte[] getSignature();
353:
354: /**
355: * Gets the signature algorithm name for the CRL
356: * signature algorithm. An example is the string "SHA-1/DSA".
357: * The ASN.1 definition for this is:
358: * <pre>
359: * signatureAlgorithm AlgorithmIdentifier<p>
360: * AlgorithmIdentifier ::= SEQUENCE {
361: * algorithm OBJECT IDENTIFIER,
362: * parameters ANY DEFINED BY algorithm OPTIONAL }
363: * -- contains a value of the type
364: * -- registered for use with the
365: * -- algorithm object identifier value
366: * </pre>
367: *
368: * <p>The algorithm name is determined from the <code>algorithm</code>
369: * OID string.
370: *
371: * @return the signature algorithm name.
372: */
373: public abstract String getSigAlgName();
374:
375: /**
376: * Gets the signature algorithm OID string from the CRL.
377: * An OID is represented by a set of nonnegative whole numbers separated
378: * by periods.
379: * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
380: * with DSA signature algorithm, as per RFC 2459.
381: *
382: * <p>See {@link getSigAlgName()#getSigAlgName} for
383: * relevant ASN.1 definitions.
384: *
385: * @return the signature algorithm OID string.
386: */
387: public abstract String getSigAlgOID();
388:
389: /**
390: * Gets the DER-encoded signature algorithm parameters from this
391: * CRL's signature algorithm. In most cases, the signature
392: * algorithm parameters are null; the parameters are usually
393: * supplied with the public key.
394: * If access to individual parameter values is needed then use
395: * {@link java.security.AlgorithmParameters AlgorithmParameters}
396: * and instantiate with the name returned by
397: * {@link getSigAlgName()#getSigAlgName}.
398: *
399: * <p>See {@link getSigAlgName()#getSigAlgName} for
400: * relevant ASN.1 definitions.
401: *
402: * @return the DER-encoded signature algorithm parameters, or
403: * null if no parameters are present.
404: */
405: public abstract byte[] getSigAlgParams();
406: }
|