1 /*
2 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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.Provider;
34 import java.security.PublicKey;
35 import javax.security.auth.x500.X500Principal;
36
37 import java.math.BigInteger;
38 import java.util.Date;
39 import java.util.Set;
40 import java.util.Arrays;
41
42 import sun.security.x509.X509CRLImpl;
43
44 /**
45 * <p>
46 * Abstract class for an X.509 Certificate Revocation List (CRL).
47 * A CRL is a time-stamped list identifying revoked certificates.
48 * It is signed by a Certificate Authority (CA) and made freely
49 * available in a public repository.
50 *
51 * <p>Each revoked certificate is
52 * identified in a CRL by its certificate serial number. When a
53 * certificate-using system uses a certificate (e.g., for verifying a
54 * remote user's digital signature), that system not only checks the
55 * certificate signature and validity but also acquires a suitably-
56 * recent CRL and checks that the certificate serial number is not on
57 * that CRL. The meaning of "suitably-recent" may vary with local
58 * policy, but it usually means the most recently-issued CRL. A CA
59 * issues a new CRL on a regular periodic basis (e.g., hourly, daily, or
60 * weekly). Entries are added to CRLs as revocations occur, and an
61 * entry may be removed when the certificate expiration date is reached.
62 * <p>
63 * The X.509 v2 CRL format is described below in ASN.1:
64 * <pre>
65 * CertificateList ::= SEQUENCE {
66 * tbsCertList TBSCertList,
67 * signatureAlgorithm AlgorithmIdentifier,
68 * signature BIT STRING }
69 * </pre>
70 * <p>
71 * More information can be found in
72 * <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280: Internet X.509
73 * Public Key Infrastructure Certificate and CRL Profile</a>.
74 * <p>
75 * The ASN.1 definition of <code>tbsCertList</code> is:
76 * <pre>
77 * TBSCertList ::= SEQUENCE {
78 * version Version OPTIONAL,
79 * -- if present, must be v2
80 * signature AlgorithmIdentifier,
81 * issuer Name,
82 * thisUpdate ChoiceOfTime,
83 * nextUpdate ChoiceOfTime OPTIONAL,
84 * revokedCertificates SEQUENCE OF SEQUENCE {
85 * userCertificate CertificateSerialNumber,
86 * revocationDate ChoiceOfTime,
87 * crlEntryExtensions Extensions OPTIONAL
88 * -- if present, must be v2
89 * } OPTIONAL,
90 * crlExtensions [0] EXPLICIT Extensions OPTIONAL
91 * -- if present, must be v2
92 * }
93 * </pre>
94 * <p>
95 * CRLs are instantiated using a certificate factory. The following is an
96 * example of how to instantiate an X.509 CRL:
97 * <pre><code>
98 * try (InputStream inStream = new FileInputStream("fileName-of-crl")) {
99 * CertificateFactory cf = CertificateFactory.getInstance("X.509");
100 * X509CRL crl = (X509CRL)cf.generateCRL(inStream);
101 * }
102 * </code></pre>
103 *
104 * @author Hemma Prafullchandra
105 *
106 *
107 * @see CRL
108 * @see CertificateFactory
109 * @see X509Extension
110 */
111
112 public abstract class X509CRL extends CRL implements X509Extension {
113
114 private transient X500Principal issuerPrincipal;
115
116 /**
117 * Constructor for X.509 CRLs.
118 */
119 protected X509CRL() {
120 super("X.509");
121 }
122
123 /**
124 * Compares this CRL for equality with the given
125 * object. If the <code>other</code> object is an
126 * <code>instanceof</code> <code>X509CRL</code>, then
127 * its encoded form is retrieved and compared with the
128 * encoded form of this CRL.
129 *
130 * @param other the object to test for equality with this CRL.
131 *
132 * @return true iff the encoded forms of the two CRLs
133 * match, false otherwise.
134 */
135 public boolean equals(Object other) {
136 if (this == other) {
137 return true;
138 }
139 if (!(other instanceof X509CRL)) {
140 return false;
141 }
142 try {
143 byte[] thisCRL = X509CRLImpl.getEncodedInternal(this);
144 byte[] otherCRL = X509CRLImpl.getEncodedInternal((X509CRL)other);
145
146 return Arrays.equals(thisCRL, otherCRL);
147 } catch (CRLException e) {
148 return false;
149 }
150 }
151
152 /**
153 * Returns a hashcode value for this CRL from its
154 * encoded form.
155 *
156 * @return the hashcode value.
157 */
158 public int hashCode() {
159 int retval = 0;
160 try {
161 byte[] crlData = X509CRLImpl.getEncodedInternal(this);
162 for (int i = 1; i < crlData.length; i++) {
163 retval += crlData[i] * i;
164 }
165 return retval;
166 } catch (CRLException e) {
167 return retval;
168 }
169 }
170
171 /**
172 * Returns the ASN.1 DER-encoded form of this CRL.
173 *
174 * @return the encoded form of this certificate
175 * @exception CRLException if an encoding error occurs.
176 */
177 public abstract byte[] getEncoded()
178 throws CRLException;
179
180 /**
181 * Verifies that this CRL was signed using the
182 * private key that corresponds to the given public key.
183 *
184 * @param key the PublicKey used to carry out the verification.
185 *
186 * @exception NoSuchAlgorithmException on unsupported signature
187 * algorithms.
188 * @exception InvalidKeyException on incorrect key.
189 * @exception NoSuchProviderException if there's no default provider.
190 * @exception SignatureException on signature errors.
191 * @exception CRLException on encoding errors.
192 */
193 public abstract void verify(PublicKey key)
194 throws CRLException, NoSuchAlgorithmException,
195 InvalidKeyException, NoSuchProviderException,
196 SignatureException;
197
198 /**
199 * Verifies that this CRL was signed using the
200 * private key that corresponds to the given public key.
201 * This method uses the signature verification engine
202 * supplied by the given provider.
203 *
204 * @param key the PublicKey used to carry out the verification.
205 * @param sigProvider the name of the signature provider.
206 *
207 * @exception NoSuchAlgorithmException on unsupported signature
208 * algorithms.
209 * @exception InvalidKeyException on incorrect key.
210 * @exception NoSuchProviderException on incorrect provider.
211 * @exception SignatureException on signature errors.
212 * @exception CRLException on encoding errors.
213 */
214 public abstract void verify(PublicKey key, String sigProvider)
215 throws CRLException, NoSuchAlgorithmException,
216 InvalidKeyException, NoSuchProviderException,
217 SignatureException;
218
219 /**
220 * Verifies that this CRL was signed using the
221 * private key that corresponds to the given public key.
222 * This method uses the signature verification engine
223 * supplied by the given provider. Note that the specified Provider object
224 * does not have to be registered in the provider list.
225 *
226 * This method was added to version 1.8 of the Java Platform Standard
227 * Edition. In order to maintain backwards compatibility with existing
228 * service providers, this method is not <code>abstract</code>
229 * and it provides a default implementation.
230 *
231 * @param key the PublicKey used to carry out the verification.
232 * @param sigProvider the signature provider.
233 *
234 * @exception NoSuchAlgorithmException on unsupported signature
235 * algorithms.
236 * @exception InvalidKeyException on incorrect key.
237 * @exception SignatureException on signature errors.
238 * @exception CRLException on encoding errors.
239 * @since 1.8
240 */
241 public void verify(PublicKey key, Provider sigProvider)
242 throws CRLException, NoSuchAlgorithmException,
243 InvalidKeyException, SignatureException {
244 X509CRLImpl.verify(this, key, sigProvider);
245 }
246
247 /**
248 * Gets the <code>version</code> (version number) value from the CRL.
249 * The ASN.1 definition for this is:
250 * <pre>
251 * version Version OPTIONAL,
252 * -- if present, must be v2<p>
253 * Version ::= INTEGER { v1(0), v2(1), v3(2) }
254 * -- v3 does not apply to CRLs but appears for consistency
255 * -- with definition of Version for certs
256 * </pre>
257 *
258 * @return the version number, i.e. 1 or 2.
259 */
260 public abstract int getVersion();
261
262 /**
263 * <strong>Denigrated</strong>, replaced by {@linkplain
264 * #getIssuerX500Principal()}. This method returns the <code>issuer</code>
265 * as an implementation specific Principal object, which should not be
266 * relied upon by portable code.
267 *
268 * <p>
269 * Gets the <code>issuer</code> (issuer distinguished name) value from
270 * the CRL. The issuer name identifies the entity that signed (and
271 * issued) the CRL.
272 *
273 * <p>The issuer name field contains an
274 * X.500 distinguished name (DN).
275 * The ASN.1 definition for this is:
276 * <pre>
277 * issuer Name
278 *
279 * Name ::= CHOICE { RDNSequence }
280 * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
281 * RelativeDistinguishedName ::=
282 * SET OF AttributeValueAssertion
283 *
284 * AttributeValueAssertion ::= SEQUENCE {
285 * AttributeType,
286 * AttributeValue }
287 * AttributeType ::= OBJECT IDENTIFIER
288 * AttributeValue ::= ANY
289 * </pre>
290 * The <code>Name</code> describes a hierarchical name composed of
291 * attributes,
292 * such as country name, and corresponding values, such as US.
293 * The type of the <code>AttributeValue</code> component is determined by
294 * the <code>AttributeType</code>; in general it will be a
295 * <code>directoryString</code>. A <code>directoryString</code> is usually
296 * one of <code>PrintableString</code>,
297 * <code>TeletexString</code> or <code>UniversalString</code>.
298 *
299 * @return a Principal whose name is the issuer distinguished name.
300 */
301 public abstract Principal getIssuerDN();
302
303 /**
304 * Returns the issuer (issuer distinguished name) value from the
305 * CRL as an <code>X500Principal</code>.
306 * <p>
307 * It is recommended that subclasses override this method.
308 *
309 * @return an <code>X500Principal</code> representing the issuer
310 * distinguished name
311 * @since 1.4
312 */
313 public X500Principal getIssuerX500Principal() {
314 if (issuerPrincipal == null) {
315 issuerPrincipal = X509CRLImpl.getIssuerX500Principal(this);
316 }
317 return issuerPrincipal;
318 }
319
320 /**
321 * Gets the <code>thisUpdate</code> date from the CRL.
322 * The ASN.1 definition for this is:
323 * <pre>
324 * thisUpdate ChoiceOfTime
325 * ChoiceOfTime ::= CHOICE {
326 * utcTime UTCTime,
327 * generalTime GeneralizedTime }
328 * </pre>
329 *
330 * @return the <code>thisUpdate</code> date from the CRL.
331 */
332 public abstract Date getThisUpdate();
333
334 /**
335 * Gets the <code>nextUpdate</code> date from the CRL.
336 *
337 * @return the <code>nextUpdate</code> date from the CRL, or null if
338 * not present.
339 */
340 public abstract Date getNextUpdate();
341
342 /**
343 * Gets the CRL entry, if any, with the given certificate serialNumber.
344 *
345 * @param serialNumber the serial number of the certificate for which a CRL entry
346 * is to be looked up
347 * @return the entry with the given serial number, or null if no such entry
348 * exists in this CRL.
349 * @see X509CRLEntry
350 */
351 public abstract X509CRLEntry
352 getRevokedCertificate(BigInteger serialNumber);
353
354 /**
355 * Get the CRL entry, if any, for the given certificate.
356 *
357 * <p>This method can be used to lookup CRL entries in indirect CRLs,
358 * that means CRLs that contain entries from issuers other than the CRL
359 * issuer. The default implementation will only return entries for
360 * certificates issued by the CRL issuer. Subclasses that wish to
361 * support indirect CRLs should override this method.
362 *
363 * @param certificate the certificate for which a CRL entry is to be looked
364 * up
365 * @return the entry for the given certificate, or null if no such entry
366 * exists in this CRL.
367 * @exception NullPointerException if certificate is null
368 *
369 * @since 1.5
370 */
371 public X509CRLEntry getRevokedCertificate(X509Certificate certificate) {
372 X500Principal certIssuer = certificate.getIssuerX500Principal();
373 X500Principal crlIssuer = getIssuerX500Principal();
374 if (certIssuer.equals(crlIssuer) == false) {
375 return null;
376 }
377 return getRevokedCertificate(certificate.getSerialNumber());
378 }
379
380 /**
381 * Gets all the entries from this CRL.
382 * This returns a Set of X509CRLEntry objects.
383 *
384 * @return all the entries or null if there are none present.
385 * @see X509CRLEntry
386 */
387 public abstract Set<? extends X509CRLEntry> getRevokedCertificates();
388
389 /**
390 * Gets the DER-encoded CRL information, the
391 * <code>tbsCertList</code> from this CRL.
392 * This can be used to verify the signature independently.
393 *
394 * @return the DER-encoded CRL information.
395 * @exception CRLException if an encoding error occurs.
396 */
397 public abstract byte[] getTBSCertList() throws CRLException;
398
399 /**
400 * Gets the <code>signature</code> value (the raw signature bits) from
401 * the CRL.
402 * The ASN.1 definition for this is:
403 * <pre>
404 * signature BIT STRING
405 * </pre>
406 *
407 * @return the signature.
408 */
409 public abstract byte[] getSignature();
410
411 /**
412 * Gets the signature algorithm name for the CRL
413 * signature algorithm. An example is the string "SHA256withRSA".
414 * The ASN.1 definition for this is:
415 * <pre>
416 * signatureAlgorithm AlgorithmIdentifier<p>
417 * AlgorithmIdentifier ::= SEQUENCE {
418 * algorithm OBJECT IDENTIFIER,
419 * parameters ANY DEFINED BY algorithm OPTIONAL }
420 * -- contains a value of the type
421 * -- registered for use with the
422 * -- algorithm object identifier value
423 * </pre>
424 *
425 * <p>The algorithm name is determined from the <code>algorithm</code>
426 * OID string.
427 *
428 * @return the signature algorithm name.
429 */
430 public abstract String getSigAlgName();
431
432 /**
433 * Gets the signature algorithm OID string from the CRL.
434 * An OID is represented by a set of nonnegative whole numbers separated
435 * by periods.
436 * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
437 * with DSA signature algorithm defined in
438 * <a href="http://www.ietf.org/rfc/rfc3279.txt">RFC 3279: Algorithms and
439 * Identifiers for the Internet X.509 Public Key Infrastructure Certificate
440 * and CRL Profile</a>.
441 *
442 * <p>See {@link #getSigAlgName() getSigAlgName} for
443 * relevant ASN.1 definitions.
444 *
445 * @return the signature algorithm OID string.
446 */
447 public abstract String getSigAlgOID();
448
449 /**
450 * Gets the DER-encoded signature algorithm parameters from this
451 * CRL's signature algorithm. In most cases, the signature
452 * algorithm parameters are null; the parameters are usually
453 * supplied with the public key.
454 * If access to individual parameter values is needed then use
455 * {@link java.security.AlgorithmParameters AlgorithmParameters}
456 * and instantiate with the name returned by
457 * {@link #getSigAlgName() getSigAlgName}.
458 *
459 * <p>See {@link #getSigAlgName() getSigAlgName} for
460 * relevant ASN.1 definitions.
461 *
462 * @return the DER-encoded signature algorithm parameters, or
463 * null if no parameters are present.
464 */
465 public abstract byte[] getSigAlgParams();
466 }