X509CRL


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