View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, 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} 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  * }</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} object is an
126      * {@code instanceof} {@code X509CRL}, 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}
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} (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
253      *
254      * Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
255      *             -- v3 does not apply to CRLs but appears for consistency
256      *             -- with definition of Version for certs
257      * </pre>
258      *
259      * @return the version number, i.e. 1 or 2.
260      */
261     public abstract int getVersion();
262 
263     /**
264      * <strong>Denigrated</strong>, replaced by {@linkplain
265      * #getIssuerX500Principal()}. This method returns the {@code issuer}
266      * as an implementation specific Principal object, which should not be
267      * relied upon by portable code.
268      *
269      * <p>
270      * Gets the {@code issuer} (issuer distinguished name) value from
271      * the CRL. The issuer name identifies the entity that signed (and
272      * issued) the CRL.
273      *
274      * <p>The issuer name field contains an
275      * X.500 distinguished name (DN).
276      * The ASN.1 definition for this is:
277      * <pre>
278      * issuer    Name
279      *
280      * Name ::= CHOICE { RDNSequence }
281      * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
282      * RelativeDistinguishedName ::=
283      *     SET OF AttributeValueAssertion
284      *
285      * AttributeValueAssertion ::= SEQUENCE {
286      *                               AttributeType,
287      *                               AttributeValue }
288      * AttributeType ::= OBJECT IDENTIFIER
289      * AttributeValue ::= ANY
290      * </pre>
291      * The {@code Name} describes a hierarchical name composed of
292      * attributes,
293      * such as country name, and corresponding values, such as US.
294      * The type of the {@code AttributeValue} component is determined by
295      * the {@code AttributeType}; in general it will be a
296      * {@code directoryString}. A {@code directoryString} is usually
297      * one of {@code PrintableString},
298      * {@code TeletexString} or {@code UniversalString}.
299      *
300      * @return a Principal whose name is the issuer distinguished name.
301      */
302     public abstract Principal getIssuerDN();
303 
304     /**
305      * Returns the issuer (issuer distinguished name) value from the
306      * CRL as an {@code X500Principal}.
307      * <p>
308      * It is recommended that subclasses override this method.
309      *
310      * @return an {@code X500Principal} representing the issuer
311      *          distinguished name
312      * @since 1.4
313      */
314     public X500Principal getIssuerX500Principal() {
315         if (issuerPrincipal == null) {
316             issuerPrincipal = X509CRLImpl.getIssuerX500Principal(this);
317         }
318         return issuerPrincipal;
319     }
320 
321     /**
322      * Gets the {@code thisUpdate} date from the CRL.
323      * The ASN.1 definition for this is:
324      * <pre>
325      * thisUpdate   ChoiceOfTime
326      * ChoiceOfTime ::= CHOICE {
327      *     utcTime        UTCTime,
328      *     generalTime    GeneralizedTime }
329      * </pre>
330      *
331      * @return the {@code thisUpdate} date from the CRL.
332      */
333     public abstract Date getThisUpdate();
334 
335     /**
336      * Gets the {@code nextUpdate} date from the CRL.
337      *
338      * @return the {@code nextUpdate} date from the CRL, or null if
339      * not present.
340      */
341     public abstract Date getNextUpdate();
342 
343     /**
344      * Gets the CRL entry, if any, with the given certificate serialNumber.
345      *
346      * @param serialNumber the serial number of the certificate for which a CRL entry
347      * is to be looked up
348      * @return the entry with the given serial number, or null if no such entry
349      * exists in this CRL.
350      * @see X509CRLEntry
351      */
352     public abstract X509CRLEntry
353         getRevokedCertificate(BigInteger serialNumber);
354 
355     /**
356      * Get the CRL entry, if any, for the given certificate.
357      *
358      * <p>This method can be used to lookup CRL entries in indirect CRLs,
359      * that means CRLs that contain entries from issuers other than the CRL
360      * issuer. The default implementation will only return entries for
361      * certificates issued by the CRL issuer. Subclasses that wish to
362      * support indirect CRLs should override this method.
363      *
364      * @param certificate the certificate for which a CRL entry is to be looked
365      *   up
366      * @return the entry for the given certificate, or null if no such entry
367      *   exists in this CRL.
368      * @exception NullPointerException if certificate is null
369      *
370      * @since 1.5
371      */
372     public X509CRLEntry getRevokedCertificate(X509Certificate certificate) {
373         X500Principal certIssuer = certificate.getIssuerX500Principal();
374         X500Principal crlIssuer = getIssuerX500Principal();
375         if (certIssuer.equals(crlIssuer) == false) {
376             return null;
377         }
378         return getRevokedCertificate(certificate.getSerialNumber());
379     }
380 
381     /**
382      * Gets all the entries from this CRL.
383      * This returns a Set of X509CRLEntry objects.
384      *
385      * @return all the entries or null if there are none present.
386      * @see X509CRLEntry
387      */
388     public abstract Set<? extends X509CRLEntry> getRevokedCertificates();
389 
390     /**
391      * Gets the DER-encoded CRL information, the
392      * {@code tbsCertList} from this CRL.
393      * This can be used to verify the signature independently.
394      *
395      * @return the DER-encoded CRL information.
396      * @exception CRLException if an encoding error occurs.
397      */
398     public abstract byte[] getTBSCertList() throws CRLException;
399 
400     /**
401      * Gets the {@code signature} value (the raw signature bits) from
402      * the CRL.
403      * The ASN.1 definition for this is:
404      * <pre>
405      * signature     BIT STRING
406      * </pre>
407      *
408      * @return the signature.
409      */
410     public abstract byte[] getSignature();
411 
412     /**
413      * Gets the signature algorithm name for the CRL
414      * signature algorithm. An example is the string "SHA256withRSA".
415      * The ASN.1 definition for this is:
416      * <pre>
417      * signatureAlgorithm   AlgorithmIdentifier
418      *
419      * AlgorithmIdentifier  ::=  SEQUENCE  {
420      *     algorithm               OBJECT IDENTIFIER,
421      *     parameters              ANY DEFINED BY algorithm OPTIONAL  }
422      *                             -- contains a value of the type
423      *                             -- registered for use with the
424      *                             -- algorithm object identifier value
425      * </pre>
426      *
427      * <p>The algorithm name is determined from the {@code algorithm}
428      * OID string.
429      *
430      * @return the signature algorithm name.
431      */
432     public abstract String getSigAlgName();
433 
434     /**
435      * Gets the signature algorithm OID string from the CRL.
436      * An OID is represented by a set of nonnegative whole numbers separated
437      * by periods.
438      * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
439      * with DSA signature algorithm defined in
440      * <a href="http://www.ietf.org/rfc/rfc3279.txt">RFC 3279: Algorithms and
441      * Identifiers for the Internet X.509 Public Key Infrastructure Certificate
442      * and CRL Profile</a>.
443      *
444      * <p>See {@link #getSigAlgName() getSigAlgName} for
445      * relevant ASN.1 definitions.
446      *
447      * @return the signature algorithm OID string.
448      */
449     public abstract String getSigAlgOID();
450 
451     /**
452      * Gets the DER-encoded signature algorithm parameters from this
453      * CRL's signature algorithm. In most cases, the signature
454      * algorithm parameters are null; the parameters are usually
455      * supplied with the public key.
456      * If access to individual parameter values is needed then use
457      * {@link java.security.AlgorithmParameters AlgorithmParameters}
458      * and instantiate with the name returned by
459      * {@link #getSigAlgName() getSigAlgName}.
460      *
461      * <p>See {@link #getSigAlgName() getSigAlgName} for
462      * relevant ASN.1 definitions.
463      *
464      * @return the DER-encoded signature algorithm parameters, or
465      *         null if no parameters are present.
466      */
467     public abstract byte[] getSigAlgParams();
468 }