1 /*
2 * Copyright 2000-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.AccessController;
29 import java.security.InvalidAlgorithmParameterException;
30 import java.security.NoSuchAlgorithmException;
31 import java.security.NoSuchProviderException;
32 import java.security.PrivilegedAction;
33 import java.security.Provider;
34 import java.security.Security;
35 import java.util.Collection;
36
37 import sun.security.jca;
38 import sun.security.jca.GetInstance.Instance;
39
40 /**
41 * A class for retrieving <code>Certificate</code>s and <code>CRL</code>s
42 * from a repository.
43 * <p>
44 * This class uses a provider-based architecture.
45 * To create a <code>CertStore</code>, call one of the static
46 * <code>getInstance</code> methods, passing in the type of
47 * <code>CertStore</code> desired, any applicable initialization parameters
48 * and optionally the name of the provider desired.
49 * <p>
50 * Once the <code>CertStore</code> has been created, it can be used to
51 * retrieve <code>Certificate</code>s and <code>CRL</code>s by calling its
52 * {@link #getCertificates(CertSelector selector) getCertificates} and
53 * {@link #getCRLs(CRLSelector selector) getCRLs} methods.
54 * <p>
55 * Unlike a {@link java.security.KeyStore KeyStore}, which provides access
56 * to a cache of private keys and trusted certificates, a
57 * <code>CertStore</code> is designed to provide access to a potentially
58 * vast repository of untrusted certificates and CRLs. For example, an LDAP
59 * implementation of <code>CertStore</code> provides access to certificates
60 * and CRLs stored in one or more directories using the LDAP protocol and the
61 * schema as defined in the RFC service attribute. See Appendix A in the
62 * <a href= "../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA">
63 * Java Certification Path API Programmer's Guide</a> for more information about
64 * standard <code>CertStore</code> types.
65 * <p>
66 * <b>Concurrent Access</b>
67 * <p>
68 * All public methods of <code>CertStore</code> objects must be thread-safe.
69 * That is, multiple threads may concurrently invoke these methods on a
70 * single <code>CertStore</code> object (or more than one) with no
71 * ill effects. This allows a <code>CertPathBuilder</code> to search for a
72 * CRL while simultaneously searching for further certificates, for instance.
73 * <p>
74 * The static methods of this class are also guaranteed to be thread-safe.
75 * Multiple threads may concurrently invoke the static methods defined in
76 * this class with no ill effects.
77 *
78 * @since 1.4
79 * @author Sean Mullan, Steve Hanna
80 */
81 public class CertStore {
82 /*
83 * Constant to lookup in the Security properties file to determine
84 * the default certstore type. In the Security properties file, the
85 * default certstore type is given as:
86 * <pre>
87 * certstore.type=LDAP
88 * </pre>
89 */
90 private static final String CERTSTORE_TYPE = "certstore.type";
91 private CertStoreSpi storeSpi;
92 private Provider provider;
93 private String type;
94 private CertStoreParameters params;
95
96 /**
97 * Creates a <code>CertStore</code> object of the given type, and
98 * encapsulates the given provider implementation (SPI object) in it.
99 *
100 * @param storeSpi the provider implementation
101 * @param provider the provider
102 * @param type the type
103 * @param params the initialization parameters (may be <code>null</code>)
104 */
105 protected CertStore(CertStoreSpi storeSpi, Provider provider,
106 String type, CertStoreParameters params) {
107 this.storeSpi = storeSpi;
108 this.provider = provider;
109 this.type = type;
110 if (params != null)
111 this.params = (CertStoreParameters) params.clone();
112 }
113
114 /**
115 * Returns a <code>Collection</code> of <code>Certificate</code>s that
116 * match the specified selector. If no <code>Certificate</code>s
117 * match the selector, an empty <code>Collection</code> will be returned.
118 * <p>
119 * For some <code>CertStore</code> types, the resulting
120 * <code>Collection</code> may not contain <b>all</b> of the
121 * <code>Certificate</code>s that match the selector. For instance,
122 * an LDAP <code>CertStore</code> may not search all entries in the
123 * directory. Instead, it may just search entries that are likely to
124 * contain the <code>Certificate</code>s it is looking for.
125 * <p>
126 * Some <code>CertStore</code> implementations (especially LDAP
127 * <code>CertStore</code>s) may throw a <code>CertStoreException</code>
128 * unless a non-null <code>CertSelector</code> is provided that
129 * includes specific criteria that can be used to find the certificates.
130 * Issuer and/or subject names are especially useful criteria.
131 *
132 * @param selector A <code>CertSelector</code> used to select which
133 * <code>Certificate</code>s should be returned. Specify <code>null</code>
134 * to return all <code>Certificate</code>s (if supported).
135 * @return A <code>Collection</code> of <code>Certificate</code>s that
136 * match the specified selector (never <code>null</code>)
137 * @throws CertStoreException if an exception occurs
138 */
139 public final Collection<? extends Certificate> getCertificates
140 (CertSelector selector) throws CertStoreException {
141 return storeSpi.engineGetCertificates(selector);
142 }
143
144 /**
145 * Returns a <code>Collection</code> of <code>CRL</code>s that
146 * match the specified selector. If no <code>CRL</code>s
147 * match the selector, an empty <code>Collection</code> will be returned.
148 * <p>
149 * For some <code>CertStore</code> types, the resulting
150 * <code>Collection</code> may not contain <b>all</b> of the
151 * <code>CRL</code>s that match the selector. For instance,
152 * an LDAP <code>CertStore</code> may not search all entries in the
153 * directory. Instead, it may just search entries that are likely to
154 * contain the <code>CRL</code>s it is looking for.
155 * <p>
156 * Some <code>CertStore</code> implementations (especially LDAP
157 * <code>CertStore</code>s) may throw a <code>CertStoreException</code>
158 * unless a non-null <code>CRLSelector</code> is provided that
159 * includes specific criteria that can be used to find the CRLs.
160 * Issuer names and/or the certificate to be checked are especially useful.
161 *
162 * @param selector A <code>CRLSelector</code> used to select which
163 * <code>CRL</code>s should be returned. Specify <code>null</code>
164 * to return all <code>CRL</code>s (if supported).
165 * @return A <code>Collection</code> of <code>CRL</code>s that
166 * match the specified selector (never <code>null</code>)
167 * @throws CertStoreException if an exception occurs
168 */
169 public final Collection<? extends CRL> getCRLs(CRLSelector selector)
170 throws CertStoreException {
171 return storeSpi.engineGetCRLs(selector);
172 }
173
174 /**
175 * Returns a <code>CertStore</code> object that implements the specified
176 * <code>CertStore</code> type and is initialized with the specified
177 * parameters.
178 *
179 * <p> This method traverses the list of registered security Providers,
180 * starting with the most preferred Provider.
181 * A new CertStore object encapsulating the
182 * CertStoreSpi implementation from the first
183 * Provider that supports the specified type is returned.
184 *
185 * <p> Note that the list of registered providers may be retrieved via
186 * the {@link Security#getProviders() Security.getProviders()} method.
187 *
188 * <p>The <code>CertStore</code> that is returned is initialized with the
189 * specified <code>CertStoreParameters</code>. The type of parameters
190 * needed may vary between different types of <code>CertStore</code>s.
191 * Note that the specified <code>CertStoreParameters</code> object is
192 * cloned.
193 *
194 * @param type the name of the requested <code>CertStore</code> type.
195 * See Appendix A in the <a href=
196 * "../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA">
197 * Java Certification Path API Programmer's Guide </a>
198 * for information about standard types.
199 *
200 * @param params the initialization parameters (may be <code>null</code>).
201 *
202 * @return a <code>CertStore</code> object that implements the specified
203 * <code>CertStore</code> type.
204 *
205 * @throws NoSuchAlgorithmException if no Provider supports a
206 * CertStoreSpi implementation for the specified type.
207 *
208 * @throws InvalidAlgorithmParameterException if the specified
209 * initialization parameters are inappropriate for this
210 * <code>CertStore</code>.
211 *
212 * @see java.security.Provider
213 */
214 public static CertStore getInstance(String type, CertStoreParameters params)
215 throws InvalidAlgorithmParameterException,
216 NoSuchAlgorithmException {
217 try {
218 Instance instance = GetInstance.getInstance("CertStore",
219 CertStoreSpi.class, type, params);
220 return new CertStore((CertStoreSpi)instance.impl,
221 instance.provider, type, params);
222 } catch (NoSuchAlgorithmException e) {
223 return handleException(e);
224 }
225 }
226
227 private static CertStore handleException(NoSuchAlgorithmException e)
228 throws NoSuchAlgorithmException, InvalidAlgorithmParameterException {
229 Throwable cause = e.getCause();
230 if (cause instanceof InvalidAlgorithmParameterException) {
231 throw (InvalidAlgorithmParameterException)cause;
232 }
233 throw e;
234 }
235
236 /**
237 * Returns a <code>CertStore</code> object that implements the specified
238 * <code>CertStore</code> type.
239 *
240 * <p> A new CertStore object encapsulating the
241 * CertStoreSpi implementation from the specified provider
242 * is returned. The specified provider must be registered
243 * in the security provider list.
244 *
245 * <p> Note that the list of registered providers may be retrieved via
246 * the {@link Security#getProviders() Security.getProviders()} method.
247 *
248 * <p>The <code>CertStore</code> that is returned is initialized with the
249 * specified <code>CertStoreParameters</code>. The type of parameters
250 * needed may vary between different types of <code>CertStore</code>s.
251 * Note that the specified <code>CertStoreParameters</code> object is
252 * cloned.
253 *
254 * @param type the requested <code>CertStore</code> type.
255 * See Appendix A in the <a href=
256 * "../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA">
257 * Java Certification Path API Programmer's Guide </a>
258 * for information about standard types.
259 *
260 * @param params the initialization parameters (may be <code>null</code>).
261 *
262 * @param provider the name of the provider.
263 *
264 * @return a <code>CertStore</code> object that implements the
265 * specified type.
266 *
267 * @throws NoSuchAlgorithmException if a CertStoreSpi
268 * implementation for the specified type is not
269 * available from the specified provider.
270 *
271 * @throws InvalidAlgorithmParameterException if the specified
272 * initialization parameters are inappropriate for this
273 * <code>CertStore</code>.
274 *
275 * @throws NoSuchProviderException if the specified provider is not
276 * registered in the security provider list.
277 *
278 * @exception IllegalArgumentException if the <code>provider</code> is
279 * null or empty.
280 *
281 * @see java.security.Provider
282 */
283 public static CertStore getInstance(String type,
284 CertStoreParameters params, String provider)
285 throws InvalidAlgorithmParameterException,
286 NoSuchAlgorithmException, NoSuchProviderException {
287 try {
288 Instance instance = GetInstance.getInstance("CertStore",
289 CertStoreSpi.class, type, params, provider);
290 return new CertStore((CertStoreSpi)instance.impl,
291 instance.provider, type, params);
292 } catch (NoSuchAlgorithmException e) {
293 return handleException(e);
294 }
295 }
296
297 /**
298 * Returns a <code>CertStore</code> object that implements the specified
299 * <code>CertStore</code> type.
300 *
301 * <p> A new CertStore object encapsulating the
302 * CertStoreSpi implementation from the specified Provider
303 * object is returned. Note that the specified Provider object
304 * does not have to be registered in the provider list.
305 *
306 * <p>The <code>CertStore</code> that is returned is initialized with the
307 * specified <code>CertStoreParameters</code>. The type of parameters
308 * needed may vary between different types of <code>CertStore</code>s.
309 * Note that the specified <code>CertStoreParameters</code> object is
310 * cloned.
311 *
312 * @param type the requested <code>CertStore</code> type.
313 * See Appendix A in the <a href=
314 * "../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA">
315 * Java Certification Path API Programmer's Guide </a>
316 * for information about standard types.
317 *
318 * @param params the initialization parameters (may be <code>null</code>).
319 *
320 * @param provider the provider.
321 *
322 * @return a <code>CertStore</code> object that implements the
323 * specified type.
324 *
325 * @exception NoSuchAlgorithmException if a CertStoreSpi
326 * implementation for the specified type is not available
327 * from the specified Provider object.
328 *
329 * @throws InvalidAlgorithmParameterException if the specified
330 * initialization parameters are inappropriate for this
331 * <code>CertStore</code>
332 *
333 * @exception IllegalArgumentException if the <code>provider</code> is
334 * null.
335 *
336 * @see java.security.Provider
337 */
338 public static CertStore getInstance(String type, CertStoreParameters params,
339 Provider provider) throws NoSuchAlgorithmException,
340 InvalidAlgorithmParameterException {
341 try {
342 Instance instance = GetInstance.getInstance("CertStore",
343 CertStoreSpi.class, type, params, provider);
344 return new CertStore((CertStoreSpi)instance.impl,
345 instance.provider, type, params);
346 } catch (NoSuchAlgorithmException e) {
347 return handleException(e);
348 }
349 }
350
351 /**
352 * Returns the parameters used to initialize this <code>CertStore</code>.
353 * Note that the <code>CertStoreParameters</code> object is cloned before
354 * it is returned.
355 *
356 * @return the parameters used to initialize this <code>CertStore</code>
357 * (may be <code>null</code>)
358 */
359 public final CertStoreParameters getCertStoreParameters() {
360 return (params == null ? null : (CertStoreParameters) params.clone());
361 }
362
363 /**
364 * Returns the type of this <code>CertStore</code>.
365 *
366 * @return the type of this <code>CertStore</code>
367 */
368 public final String getType() {
369 return this.type;
370 }
371
372 /**
373 * Returns the provider of this <code>CertStore</code>.
374 *
375 * @return the provider of this <code>CertStore</code>
376 */
377 public final Provider getProvider() {
378 return this.provider;
379 }
380
381 /**
382 * Returns the default <code>CertStore</code> type as specified in the
383 * Java security properties file, or the string "LDAP" if no
384 * such property exists. The Java security properties file is located in
385 * the file named <JAVA_HOME>/lib/security/java.security.
386 * <JAVA_HOME> refers to the value of the java.home system property,
387 * and specifies the directory where the JRE is installed.
388 *
389 * <p>The default <code>CertStore</code> type can be used by applications
390 * that do not want to use a hard-coded type when calling one of the
391 * <code>getInstance</code> methods, and want to provide a default
392 * <code>CertStore</code> type in case a user does not specify its own.
393 *
394 * <p>The default <code>CertStore</code> type can be changed by setting
395 * the value of the "certstore.type" security property (in the Java
396 * security properties file) to the desired type.
397 *
398 * @return the default <code>CertStore</code> type as specified in the
399 * Java security properties file, or the string "LDAP"
400 * if no such property exists.
401 */
402 public final static String getDefaultType() {
403 String cstype;
404 cstype = AccessController.doPrivileged(new PrivilegedAction<String>() {
405 public String run() {
406 return Security.getProperty(CERTSTORE_TYPE);
407 }
408 });
409 if (cstype == null) {
410 cstype = "LDAP";
411 }
412 return cstype;
413 }
414 }
Save This Page