KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > security > cert > CertStore


1 /*
2  * @(#)CertStore.java 1.13 04/06/28
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.AccessController JavaDoc;
11 import java.security.InvalidAlgorithmParameterException JavaDoc;
12 import java.security.NoSuchAlgorithmException JavaDoc;
13 import java.security.NoSuchProviderException JavaDoc;
14 import java.security.PrivilegedAction JavaDoc;
15 import java.security.Provider JavaDoc;
16 import java.security.Security JavaDoc;
17 import java.util.Collection JavaDoc;
18
19 import sun.security.jca.*;
20 import sun.security.jca.GetInstance.Instance;
21
22 /**
23  * A class for retrieving <code>Certificate</code>s and <code>CRL</code>s
24  * from a repository.
25  * <p>
26  * This class uses a provider-based architecture, as described in the
27  * Java Cryptography Architecture.
28  * To create a <code>CertStore</code>, call one of the static
29  * <code>getInstance</code> methods, passing in the type of
30  * <code>CertStore</code> desired, any applicable initialization parameters
31  * and optionally the name of the provider desired.
32  * <p>
33  * Once the <code>CertStore</code> has been created, it can be used to
34  * retrieve <code>Certificate</code>s and <code>CRL</code>s by calling its
35  * {@link #getCertificates(CertSelector selector) getCertificates} and
36  * {@link #getCRLs(CRLSelector selector) getCRLs} methods.
37  * <p>
38  * Unlike a {@link java.security.KeyStore KeyStore}, which provides access
39  * to a cache of private keys and trusted certificates, a
40  * <code>CertStore</code> is designed to provide access to a potentially
41  * vast repository of untrusted certificates and CRLs. For example, an LDAP
42  * implementation of <code>CertStore</code> provides access to certificates
43  * and CRLs stored in one or more directories using the LDAP protocol and the
44  * schema as defined in the RFC service attribute. See Appendix A in the
45  * <a HREF= "../../../../guide/security/certpath/CertPathProgGuide.html#AppA">
46  * Java Certification Path API Programmer's Guide</a> for more information about
47  * standard <code>CertStore</code> types.
48  * <p>
49  * <b>Concurrent Access</b>
50  * <p>
51  * All public methods of <code>CertStore</code> objects must be thread-safe.
52  * That is, multiple threads may concurrently invoke these methods on a
53  * single <code>CertStore</code> object (or more than one) with no
54  * ill effects. This allows a <code>CertPathBuilder</code> to search for a
55  * CRL while simultaneously searching for further certificates, for instance.
56  * <p>
57  * The static methods of this class are also guaranteed to be thread-safe.
58  * Multiple threads may concurrently invoke the static methods defined in
59  * this class with no ill effects.
60  *
61  * @version 1.13 06/28/04
62  * @since 1.4
63  * @author Sean Mullan, Steve Hanna
64  */

65 public class CertStore {
66     /*
67      * Constant to lookup in the Security properties file to determine
68      * the default certstore type. In the Security properties file, the
69      * default certstore type is given as:
70      * <pre>
71      * certstore.type=LDAP
72      * </pre>
73      */

74     private static final String JavaDoc CERTSTORE_TYPE = "certstore.type";
75     private CertStoreSpi JavaDoc storeSpi;
76     private Provider JavaDoc provider;
77     private String JavaDoc type;
78     private CertStoreParameters JavaDoc params;
79
80     /**
81      * Creates a <code>CertStore</code> object of the given type, and
82      * encapsulates the given provider implementation (SPI object) in it.
83      *
84      * @param storeSpi the provider implementation
85      * @param provider the provider
86      * @param type the type
87      * @param params the initialization parameters (may be <code>null</code>)
88      */

89     protected CertStore(CertStoreSpi JavaDoc storeSpi, Provider JavaDoc provider,
90             String JavaDoc type, CertStoreParameters JavaDoc params) {
91         this.storeSpi = storeSpi;
92         this.provider = provider;
93         this.type = type;
94     if (params != null)
95         this.params = (CertStoreParameters JavaDoc) params.clone();
96     }
97
98     /**
99      * Returns a <code>Collection</code> of <code>Certificate</code>s that
100      * match the specified selector. If no <code>Certificate</code>s
101      * match the selector, an empty <code>Collection</code> will be returned.
102      * <p>
103      * For some <code>CertStore</code> types, the resulting
104      * <code>Collection</code> may not contain <b>all</b> of the
105      * <code>Certificate</code>s that match the selector. For instance,
106      * an LDAP <code>CertStore</code> may not search all entries in the
107      * directory. Instead, it may just search entries that are likely to
108      * contain the <code>Certificate</code>s it is looking for.
109      * <p>
110      * Some <code>CertStore</code> implementations (especially LDAP
111      * <code>CertStore</code>s) may throw a <code>CertStoreException</code>
112      * unless a non-null <code>CertSelector</code> is provided that
113      * includes specific criteria that can be used to find the certificates.
114      * Issuer and/or subject names are especially useful criteria.
115      *
116      * @param selector A <code>CertSelector</code> used to select which
117      * <code>Certificate</code>s should be returned. Specify <code>null</code>
118      * to return all <code>Certificate</code>s (if supported).
119      * @return A <code>Collection</code> of <code>Certificate</code>s that
120      * match the specified selector (never <code>null</code>)
121      * @throws CertStoreException if an exception occurs
122      */

123     public final Collection JavaDoc<? extends Certificate JavaDoc> getCertificates
124         (CertSelector JavaDoc selector) throws CertStoreException JavaDoc {
125         return storeSpi.engineGetCertificates(selector);
126     }
127    
128     /**
129      * Returns a <code>Collection</code> of <code>CRL</code>s that
130      * match the specified selector. If no <code>CRL</code>s
131      * match the selector, an empty <code>Collection</code> will be returned.
132      * <p>
133      * For some <code>CertStore</code> types, the resulting
134      * <code>Collection</code> may not contain <b>all</b> of the
135      * <code>CRL</code>s that match the selector. For instance,
136      * an LDAP <code>CertStore</code> may not search all entries in the
137      * directory. Instead, it may just search entries that are likely to
138      * contain the <code>CRL</code>s it is looking for.
139      * <p>
140      * Some <code>CertStore</code> implementations (especially LDAP
141      * <code>CertStore</code>s) may throw a <code>CertStoreException</code>
142      * unless a non-null <code>CRLSelector</code> is provided that
143      * includes specific criteria that can be used to find the CRLs.
144      * Issuer names and/or the certificate to be checked are especially useful.
145      *
146      * @param selector A <code>CRLSelector</code> used to select which
147      * <code>CRL</code>s should be returned. Specify <code>null</code>
148      * to return all <code>CRL</code>s (if supported).
149      * @return A <code>Collection</code> of <code>CRL</code>s that
150      * match the specified selector (never <code>null</code>)
151      * @throws CertStoreException if an exception occurs
152      */

153     public final Collection JavaDoc<? extends CRL JavaDoc> getCRLs(CRLSelector JavaDoc selector)
154         throws CertStoreException JavaDoc {
155         return storeSpi.engineGetCRLs(selector);
156     }
157    
158     /**
159      * Returns a <code>CertStore</code> object that implements the specified
160      * <code>CertStore</code> type and is initialized with the specified
161      * parameters.
162      *
163      * <p>If the default provider package provides an implementation
164      * of the specified <code>CertStore</code> type, an instance of
165      * <code>CertStore</code> containing that implementation is returned.
166      * If the requested type is not available in the default package, other
167      * packages are searched.
168      *
169      * <p>The <code>CertStore</code> that is returned is initialized with the
170      * specified <code>CertStoreParameters</code>. The type of parameters
171      * needed may vary between different types of <code>CertStore</code>s.
172      * Note that the specified <code>CertStoreParameters</code> object is
173      * cloned.
174      *
175      * @param type the name of the requested <code>CertStore</code> type
176      * @param params the initialization parameters (may be <code>null</code>)
177      * @return a <code>CertStore</code> object that implements the specified
178      * <code>CertStore</code> type
179      * @throws NoSuchAlgorithmException if the requested type is not
180      * available in the default provider package or any of the other provider
181      * packages that were searched
182      * @throws InvalidAlgorithmParameterException if the specified
183      * initialization parameters are inappropriate for this
184      * <code>CertStore</code>
185      */

186     public static CertStore JavaDoc getInstance(String JavaDoc type, CertStoreParameters JavaDoc params)
187         throws InvalidAlgorithmParameterException JavaDoc,
188         NoSuchAlgorithmException JavaDoc {
189     try {
190         Instance instance = GetInstance.getInstance("CertStore",
191             CertStoreSpi JavaDoc.class, type, params);
192         return new CertStore JavaDoc((CertStoreSpi JavaDoc)instance.impl,
193             instance.provider, type, params);
194     } catch (NoSuchAlgorithmException JavaDoc e) {
195         return handleException(e);
196     }
197     }
198     
199     private static CertStore JavaDoc handleException(NoSuchAlgorithmException JavaDoc e)
200         throws NoSuchAlgorithmException JavaDoc, InvalidAlgorithmParameterException JavaDoc {
201     Throwable JavaDoc cause = e.getCause();
202     if (cause instanceof InvalidAlgorithmParameterException JavaDoc) {
203         throw (InvalidAlgorithmParameterException JavaDoc)cause;
204     }
205     throw e;
206     }
207     
208     /**
209      * Returns a <code>CertStore</code> object that implements the specified
210      * <code>CertStore</code> type, as supplied by the specified provider
211      * and initialized with the specified parameters.
212      *
213      * <p>The <code>CertStore</code> that is returned is initialized with the
214      * specified <code>CertStoreParameters</code>. The type of parameters
215      * needed may vary between different types of <code>CertStore</code>s.
216      * Note that the specified <code>CertStoreParameters</code> object is
217      * cloned.
218      *
219      * @param type the requested <code>CertStore</code> type
220      * @param params the initialization parameters (may be <code>null</code>)
221      * @param provider the name of the provider
222      * @return a <code>CertStore</code> object that implements the
223      * specified type, as supplied by the specified provider
224      * @throws NoSuchAlgorithmException if the requested type is not
225      * available from the specified provider
226      * @throws InvalidAlgorithmParameterException if the specified
227      * initialization parameters are inappropriate for this
228      * <code>CertStore</code>
229      * @throws NoSuchProviderException if the provider has not been configured
230      * @exception IllegalArgumentException if the <code>provider</code> is
231      * null
232      */

233     public static CertStore JavaDoc getInstance(String JavaDoc type,
234         CertStoreParameters JavaDoc params, String JavaDoc provider)
235         throws InvalidAlgorithmParameterException JavaDoc,
236         NoSuchAlgorithmException JavaDoc, NoSuchProviderException JavaDoc {
237     try {
238         Instance instance = GetInstance.getInstance("CertStore",
239             CertStoreSpi JavaDoc.class, type, params, provider);
240         return new CertStore JavaDoc((CertStoreSpi JavaDoc)instance.impl,
241             instance.provider, type, params);
242     } catch (NoSuchAlgorithmException JavaDoc e) {
243         return handleException(e);
244     }
245     }
246     
247     /**
248      * Returns a <code>CertStore</code> object that implements the specified
249      * <code>CertStore</code> type, as supplied by the specified provider and
250      * initialized with the specified parameters.
251      * Note: the <code>provider</code> doesn't have to be registered.
252      *
253      * <p>The <code>CertStore</code> that is returned is initialized with the
254      * specified <code>CertStoreParameters</code>. The type of parameters
255      * needed may vary between different types of <code>CertStore</code>s.
256      * Note that the specified <code>CertStoreParameters</code> object is
257      * cloned.
258      *
259      * @param type the requested <code>CertStore</code> type
260      * @param params the initialization parameters (may be <code>null</code>)
261      * @param provider the provider
262      * @return a <code>CertStore</code> object that implements the
263      * specified type, as supplied by the specified provider
264      * @exception NoSuchAlgorithmException if the requested type is not
265      * available from the specified provider
266      * @throws InvalidAlgorithmParameterException if the specified
267      * initialization parameters are inappropriate for this
268      * <code>CertStore</code>
269      * @exception IllegalArgumentException if the <code>provider</code> is
270      * null
271      */

272     public static CertStore JavaDoc getInstance(String JavaDoc type, CertStoreParameters JavaDoc params,
273         Provider JavaDoc provider) throws NoSuchAlgorithmException JavaDoc,
274         InvalidAlgorithmParameterException JavaDoc {
275     try {
276         Instance instance = GetInstance.getInstance("CertStore",
277             CertStoreSpi JavaDoc.class, type, params, provider);
278         return new CertStore JavaDoc((CertStoreSpi JavaDoc)instance.impl,
279             instance.provider, type, params);
280     } catch (NoSuchAlgorithmException JavaDoc e) {
281         return handleException(e);
282     }
283     }
284     
285     /**
286      * Returns the parameters used to initialize this <code>CertStore</code>.
287      * Note that the <code>CertStoreParameters</code> object is cloned before
288      * it is returned.
289      *
290      * @return the parameters used to initialize this <code>CertStore</code>
291      * (may be <code>null</code>)
292      */

293     public final CertStoreParameters JavaDoc getCertStoreParameters() {
294         return (params == null ? null : (CertStoreParameters JavaDoc) params.clone());
295     }
296
297     /**
298      * Returns the type of this <code>CertStore</code>.
299      *
300      * @return the type of this <code>CertStore</code>
301      */

302     public final String JavaDoc getType() {
303         return this.type;
304     }
305
306     /**
307      * Returns the provider of this <code>CertStore</code>.
308      *
309      * @return the provider of this <code>CertStore</code>
310      */

311     public final Provider JavaDoc getProvider() {
312         return this.provider;
313     }
314
315     /**
316      * Returns the default <code>CertStore</code> type as specified in the
317      * Java security properties file, or the string &quot;LDAP&quot; if no
318      * such property exists. The Java security properties file is located in
319      * the file named &lt;JAVA_HOME&gt;/lib/security/java.security, where
320      * &lt;JAVA_HOME&gt; refers to the directory where the JDK was installed.
321      *
322      * <p>The default <code>CertStore</code> type can be used by applications
323      * that do not want to use a hard-coded type when calling one of the
324      * <code>getInstance</code> methods, and want to provide a default
325      * <code>CertStore</code> type in case a user does not specify its own.
326      *
327      * <p>The default <code>CertStore</code> type can be changed by setting
328      * the value of the "certstore.type" security property (in the Java
329      * security properties file) to the desired type.
330      *
331      * @return the default <code>CertStore</code> type as specified in the
332      * Java security properties file, or the string &quot;LDAP&quot;
333      * if no such property exists.
334      */

335     public final static String JavaDoc getDefaultType() {
336         String JavaDoc cstype;
337         cstype = (String JavaDoc)AccessController.doPrivileged(new PrivilegedAction JavaDoc() {
338             public Object JavaDoc run() {
339                 return Security.getProperty(CERTSTORE_TYPE);
340             }
341         });
342         if (cstype == null) {
343             cstype = "LDAP";
344         }
345         return cstype;
346     }
347 }
348
Popular Tags