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