1 /*
2 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.security.cert;
27
28 import java.security.NoSuchAlgorithmException;
29 import java.security.NoSuchProviderException;
30 import java.security.InvalidKeyException;
31 import java.security.SignatureException;
32 import java.security.Principal;
33 import java.security.PublicKey;
34 import javax.security.auth.x500.X500Principal;
35
36 import java.math.BigInteger;
37 import java.util.Date;
38 import java.util.Set;
39 import java.util.Arrays;
40
41 import sun.security.x509.X509CRLImpl;
42
43 /**
44 * <p>
45 * Abstract class for an X.509 Certificate Revocation List (CRL).
46 * A CRL is a time-stamped list identifying revoked certificates.
47 * It is signed by a Certificate Authority (CA) and made freely
48 * available in a public repository.
49 *
50 * <p>Each revoked certificate is
51 * identified in a CRL by its certificate serial number. When a
52 * certificate-using system uses a certificate (e.g., for verifying a
53 * remote user's digital signature), that system not only checks the
54 * certificate signature and validity but also acquires a suitably-
55 * recent CRL and checks that the certificate serial number is not on
56 * that CRL. The meaning of "suitably-recent" may vary with local
57 * policy, but it usually means the most recently-issued CRL. A CA
58 * issues a new CRL on a regular periodic basis (e.g., hourly, daily, or
59 * weekly). Entries are added to CRLs as revocations occur, and an
60 * entry may be removed when the certificate expiration date is reached.
61 * <p>
62 * The X.509 v2 CRL format is described below in ASN.1:
63 * <pre>
64 * CertificateList ::= SEQUENCE {
65 * tbsCertList TBSCertList,
66 * signatureAlgorithm AlgorithmIdentifier,
67 * signature BIT STRING }
68 * </pre>
69 * <p>
70 * More information can be found in
71 * <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280: Internet X.509
72 * Public Key Infrastructure Certificate and CRL Profile</a>.
73 * <p>
74 * The ASN.1 definition of <code>tbsCertList</code> is:
75 * <pre>
76 * TBSCertList ::= SEQUENCE {
77 * version Version OPTIONAL,
78 * -- if present, must be v2
79 * signature AlgorithmIdentifier,
80 * issuer Name,
81 * thisUpdate ChoiceOfTime,
82 * nextUpdate ChoiceOfTime OPTIONAL,
83 * revokedCertificates SEQUENCE OF SEQUENCE {
84 * userCertificate CertificateSerialNumber,
85 * revocationDate ChoiceOfTime,
86 * crlEntryExtensions Extensions OPTIONAL
87 * -- if present, must be v2
88 * } OPTIONAL,
89 * crlExtensions [0] EXPLICIT Extensions OPTIONAL
90 * -- if present, must be v2
91 * }
92 * </pre>
93 * <p>
94 * CRLs are instantiated using a certificate factory. The following is an
95 * example of how to instantiate an X.509 CRL:
96 * <pre><code>
97 * InputStream inStream = null;
98 * try {
99 * 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 *
112 * @see CRL
113 * @see CertificateFactory
114 * @see X509Extension
115 */
116
117 public abstract class X509CRL extends CRL implements X509Extension {
118
119 private transient X500Principal issuerPrincipal;
120
121 /**
122 * Constructor for X.509 CRLs.
123 */
124 protected X509CRL() {
125 super("X.509");
126 }
127
128 /**
129 * Compares this CRL for equality with the given
130 * object. If the <code>other</code> object is an
131 * <code>instanceof</code> <code>X509CRL</code>, then
132 * its encoded form is retrieved and compared with the
133 * encoded form of this CRL.
134 *
135 * @param other the object to test for equality with this CRL.
136 *
137 * @return true iff the encoded forms of the two CRLs
138 * match, false otherwise.
139 */
140 public boolean equals(Object other) {
141 if (this == other) {
142 return true;
143 }
144 if (!(other instanceof X509CRL)) {
145 return false;
146 }
147 try {
148 byte[] thisCRL = X509CRLImpl.getEncodedInternal(this);
149 byte[] otherCRL = X509CRLImpl.getEncodedInternal((X509CRL)other);
150
151 return Arrays.equals(thisCRL, otherCRL);
152 } catch (CRLException e) {
153 return false;
154 }
155 }
156
157 /**
158 * Returns a hashcode value for this CRL from its
159 * encoded form.
160 *
161 * @return the hashcode value.
162 */
163 public int hashCode() {
164 int retval = 0;
165 try {
166 byte[] crlData = X509CRLImpl.getEncodedInternal(this);
167 for (int i = 1; i < crlData.length; i++) {
168 retval += crlData[i] * i;
169 }
170 return retval;
171 } catch (CRLException e) {
172 return retval;
173 }
174 }
175
176 /**
177 * Returns the ASN.1 DER-encoded form of this CRL.
178 *
179 * @return the encoded form of this certificate
180 * @exception CRLException if an encoding error occurs.
181 */
182 public abstract byte[] getEncoded()
183 throws CRLException;
184
185 /**
186 * Verifies that this CRL was signed using the
187 * private key that corresponds to the given public key.
188 *
189 * @param key the PublicKey used to carry out the verification.
190 *
191 * @exception NoSuchAlgorithmException on unsupported signature
192 * algorithms.
193 * @exception InvalidKeyException on incorrect key.
194 * @exception NoSuchProviderException if there's no default provider.
195 * @exception SignatureException on signature errors.
196 * @exception CRLException on encoding errors.
197 */
198 public abstract void verify(PublicKey key)
199 throws CRLException, NoSuchAlgorithmException,
200 InvalidKeyException, NoSuchProviderException,
201 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
329 getRevokedCertificate(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(X509Certificate certificate) {
349 X500Principal certIssuer = certificate.getIssuerX500Principal();
350 X500Principal crlIssuer = getIssuerX500Principal();
351 if (certIssuer.equals(crlIssuer) == false) {
352 return null;
353 }
354 return getRevokedCertificate(certificate.getSerialNumber());
355 }
356
357 /**
358 * Gets all the entries from this CRL.
359 * This returns a Set of X509CRLEntry objects.
360 *
361 * @return all the entries or null if there are none present.
362 * @see X509CRLEntry
363 */
364 public abstract Set<? extends X509CRLEntry> getRevokedCertificates();
365
366 /**
367 * Gets the DER-encoded CRL information, the
368 * <code>tbsCertList</code> from this CRL.
369 * This can be used to verify the signature independently.
370 *
371 * @return the DER-encoded CRL information.
372 * @exception CRLException if an encoding error occurs.
373 */
374 public abstract byte[] getTBSCertList() throws CRLException;
375
376 /**
377 * Gets the <code>signature</code> value (the raw signature bits) from
378 * the CRL.
379 * The ASN.1 definition for this is:
380 * <pre>
381 * signature BIT STRING
382 * </pre>
383 *
384 * @return the signature.
385 */
386 public abstract byte[] getSignature();
387
388 /**
389 * Gets the signature algorithm name for the CRL
390 * signature algorithm. An example is the string "SHA-1/DSA".
391 * The ASN.1 definition for this is:
392 * <pre>
393 * signatureAlgorithm AlgorithmIdentifier<p>
394 * AlgorithmIdentifier ::= SEQUENCE {
395 * algorithm OBJECT IDENTIFIER,
396 * parameters ANY DEFINED BY algorithm OPTIONAL }
397 * -- contains a value of the type
398 * -- registered for use with the
399 * -- algorithm object identifier value
400 * </pre>
401 *
402 * <p>The algorithm name is determined from the <code>algorithm</code>
403 * OID string.
404 *
405 * @return the signature algorithm name.
406 */
407 public abstract String getSigAlgName();
408
409 /**
410 * Gets the signature algorithm OID string from the CRL.
411 * An OID is represented by a set of nonnegative whole numbers separated
412 * by periods.
413 * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
414 * with DSA signature algorithm defined in
415 * <a href="http://www.ietf.org/rfc/rfc3279.txt">RFC 3279: Algorithms and
416 * Identifiers for the Internet X.509 Public Key Infrastructure Certificate
417 * and CRL Profile</a>.
418 *
419 * <p>See {@link #getSigAlgName() getSigAlgName} for
420 * relevant ASN.1 definitions.
421 *
422 * @return the signature algorithm OID string.
423 */
424 public abstract String getSigAlgOID();
425
426 /**
427 * Gets the DER-encoded signature algorithm parameters from this
428 * CRL's signature algorithm. In most cases, the signature
429 * algorithm parameters are null; the parameters are usually
430 * supplied with the public key.
431 * If access to individual parameter values is needed then use
432 * {@link java.security.AlgorithmParameters AlgorithmParameters}
433 * and instantiate with the name returned by
434 * {@link #getSigAlgName() getSigAlgName}.
435 *
436 * <p>See {@link #getSigAlgName() getSigAlgName} for
437 * relevant ASN.1 definitions.
438 *
439 * @return the DER-encoded signature algorithm parameters, or
440 * null if no parameters are present.
441 */
442 public abstract byte[] getSigAlgParams();
443 }
Save This Page