36 |
36 |
37 import sun.security.jca.*; |
37 import sun.security.jca.*; |
38 import sun.security.jca.GetInstance.Instance; |
38 import sun.security.jca.GetInstance.Instance; |
39 |
39 |
40 /** |
40 /** |
41 * A class for retrieving <code>Certificate</code>s and <code>CRL</code>s |
41 * A class for retrieving {@code Certificate}s and {@code CRL}s |
42 * from a repository. |
42 * from a repository. |
43 * <p> |
43 * <p> |
44 * This class uses a provider-based architecture. |
44 * This class uses a provider-based architecture. |
45 * To create a <code>CertStore</code>, call one of the static |
45 * To create a {@code CertStore}, call one of the static |
46 * <code>getInstance</code> methods, passing in the type of |
46 * {@code getInstance} methods, passing in the type of |
47 * <code>CertStore</code> desired, any applicable initialization parameters |
47 * {@code CertStore} desired, any applicable initialization parameters |
48 * and optionally the name of the provider desired. |
48 * and optionally the name of the provider desired. |
49 * <p> |
49 * <p> |
50 * Once the <code>CertStore</code> has been created, it can be used to |
50 * Once the {@code CertStore} has been created, it can be used to |
51 * retrieve <code>Certificate</code>s and <code>CRL</code>s by calling its |
51 * retrieve {@code Certificate}s and {@code CRL}s by calling its |
52 * {@link #getCertificates(CertSelector selector) getCertificates} and |
52 * {@link #getCertificates(CertSelector selector) getCertificates} and |
53 * {@link #getCRLs(CRLSelector selector) getCRLs} methods. |
53 * {@link #getCRLs(CRLSelector selector) getCRLs} methods. |
54 * <p> |
54 * <p> |
55 * Unlike a {@link java.security.KeyStore KeyStore}, which provides access |
55 * Unlike a {@link java.security.KeyStore KeyStore}, which provides access |
56 * to a cache of private keys and trusted certificates, a |
56 * to a cache of private keys and trusted certificates, a |
57 * <code>CertStore</code> is designed to provide access to a potentially |
57 * {@code CertStore} is designed to provide access to a potentially |
58 * vast repository of untrusted certificates and CRLs. For example, an LDAP |
58 * vast repository of untrusted certificates and CRLs. For example, an LDAP |
59 * implementation of <code>CertStore</code> provides access to certificates |
59 * implementation of {@code CertStore} provides access to certificates |
60 * and CRLs stored in one or more directories using the LDAP protocol and the |
60 * and CRLs stored in one or more directories using the LDAP protocol and the |
61 * schema as defined in the RFC service attribute. |
61 * schema as defined in the RFC service attribute. |
62 * |
62 * |
63 * <p> Every implementation of the Java platform is required to support the |
63 * <p> Every implementation of the Java platform is required to support the |
64 * following standard <code>CertStore</code> type: |
64 * following standard {@code CertStore} type: |
65 * <ul> |
65 * <ul> |
66 * <li><tt>Collection</tt></li> |
66 * <li>{@code Collection}</li> |
67 * </ul> |
67 * </ul> |
68 * This type is described in the <a href= |
68 * This type is described in the <a href= |
69 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertStore"> |
69 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertStore"> |
70 * CertStore section</a> of the |
70 * CertStore section</a> of the |
71 * Java Cryptography Architecture Standard Algorithm Name Documentation. |
71 * Java Cryptography Architecture Standard Algorithm Name Documentation. |
102 private Provider provider; |
102 private Provider provider; |
103 private String type; |
103 private String type; |
104 private CertStoreParameters params; |
104 private CertStoreParameters params; |
105 |
105 |
106 /** |
106 /** |
107 * Creates a <code>CertStore</code> object of the given type, and |
107 * Creates a {@code CertStore} object of the given type, and |
108 * encapsulates the given provider implementation (SPI object) in it. |
108 * encapsulates the given provider implementation (SPI object) in it. |
109 * |
109 * |
110 * @param storeSpi the provider implementation |
110 * @param storeSpi the provider implementation |
111 * @param provider the provider |
111 * @param provider the provider |
112 * @param type the type |
112 * @param type the type |
113 * @param params the initialization parameters (may be <code>null</code>) |
113 * @param params the initialization parameters (may be {@code null}) |
114 */ |
114 */ |
115 protected CertStore(CertStoreSpi storeSpi, Provider provider, |
115 protected CertStore(CertStoreSpi storeSpi, Provider provider, |
116 String type, CertStoreParameters params) { |
116 String type, CertStoreParameters params) { |
117 this.storeSpi = storeSpi; |
117 this.storeSpi = storeSpi; |
118 this.provider = provider; |
118 this.provider = provider; |
120 if (params != null) |
120 if (params != null) |
121 this.params = (CertStoreParameters) params.clone(); |
121 this.params = (CertStoreParameters) params.clone(); |
122 } |
122 } |
123 |
123 |
124 /** |
124 /** |
125 * Returns a <code>Collection</code> of <code>Certificate</code>s that |
125 * Returns a {@code Collection} of {@code Certificate}s that |
126 * match the specified selector. If no <code>Certificate</code>s |
126 * match the specified selector. If no {@code Certificate}s |
127 * match the selector, an empty <code>Collection</code> will be returned. |
127 * match the selector, an empty {@code Collection} will be returned. |
128 * <p> |
128 * <p> |
129 * For some <code>CertStore</code> types, the resulting |
129 * For some {@code CertStore} types, the resulting |
130 * <code>Collection</code> may not contain <b>all</b> of the |
130 * {@code Collection} may not contain <b>all</b> of the |
131 * <code>Certificate</code>s that match the selector. For instance, |
131 * {@code Certificate}s that match the selector. For instance, |
132 * an LDAP <code>CertStore</code> may not search all entries in the |
132 * an LDAP {@code CertStore} may not search all entries in the |
133 * directory. Instead, it may just search entries that are likely to |
133 * directory. Instead, it may just search entries that are likely to |
134 * contain the <code>Certificate</code>s it is looking for. |
134 * contain the {@code Certificate}s it is looking for. |
135 * <p> |
135 * <p> |
136 * Some <code>CertStore</code> implementations (especially LDAP |
136 * Some {@code CertStore} implementations (especially LDAP |
137 * <code>CertStore</code>s) may throw a <code>CertStoreException</code> |
137 * {@code CertStore}s) may throw a {@code CertStoreException} |
138 * unless a non-null <code>CertSelector</code> is provided that |
138 * unless a non-null {@code CertSelector} is provided that |
139 * includes specific criteria that can be used to find the certificates. |
139 * includes specific criteria that can be used to find the certificates. |
140 * Issuer and/or subject names are especially useful criteria. |
140 * Issuer and/or subject names are especially useful criteria. |
141 * |
141 * |
142 * @param selector A <code>CertSelector</code> used to select which |
142 * @param selector A {@code CertSelector} used to select which |
143 * <code>Certificate</code>s should be returned. Specify <code>null</code> |
143 * {@code Certificate}s should be returned. Specify {@code null} |
144 * to return all <code>Certificate</code>s (if supported). |
144 * to return all {@code Certificate}s (if supported). |
145 * @return A <code>Collection</code> of <code>Certificate</code>s that |
145 * @return A {@code Collection} of {@code Certificate}s that |
146 * match the specified selector (never <code>null</code>) |
146 * match the specified selector (never {@code null}) |
147 * @throws CertStoreException if an exception occurs |
147 * @throws CertStoreException if an exception occurs |
148 */ |
148 */ |
149 public final Collection<? extends Certificate> getCertificates |
149 public final Collection<? extends Certificate> getCertificates |
150 (CertSelector selector) throws CertStoreException { |
150 (CertSelector selector) throws CertStoreException { |
151 return storeSpi.engineGetCertificates(selector); |
151 return storeSpi.engineGetCertificates(selector); |
152 } |
152 } |
153 |
153 |
154 /** |
154 /** |
155 * Returns a <code>Collection</code> of <code>CRL</code>s that |
155 * Returns a {@code Collection} of {@code CRL}s that |
156 * match the specified selector. If no <code>CRL</code>s |
156 * match the specified selector. If no {@code CRL}s |
157 * match the selector, an empty <code>Collection</code> will be returned. |
157 * match the selector, an empty {@code Collection} will be returned. |
158 * <p> |
158 * <p> |
159 * For some <code>CertStore</code> types, the resulting |
159 * For some {@code CertStore} types, the resulting |
160 * <code>Collection</code> may not contain <b>all</b> of the |
160 * {@code Collection} may not contain <b>all</b> of the |
161 * <code>CRL</code>s that match the selector. For instance, |
161 * {@code CRL}s that match the selector. For instance, |
162 * an LDAP <code>CertStore</code> may not search all entries in the |
162 * an LDAP {@code CertStore} may not search all entries in the |
163 * directory. Instead, it may just search entries that are likely to |
163 * directory. Instead, it may just search entries that are likely to |
164 * contain the <code>CRL</code>s it is looking for. |
164 * contain the {@code CRL}s it is looking for. |
165 * <p> |
165 * <p> |
166 * Some <code>CertStore</code> implementations (especially LDAP |
166 * Some {@code CertStore} implementations (especially LDAP |
167 * <code>CertStore</code>s) may throw a <code>CertStoreException</code> |
167 * {@code CertStore}s) may throw a {@code CertStoreException} |
168 * unless a non-null <code>CRLSelector</code> is provided that |
168 * unless a non-null {@code CRLSelector} is provided that |
169 * includes specific criteria that can be used to find the CRLs. |
169 * includes specific criteria that can be used to find the CRLs. |
170 * Issuer names and/or the certificate to be checked are especially useful. |
170 * Issuer names and/or the certificate to be checked are especially useful. |
171 * |
171 * |
172 * @param selector A <code>CRLSelector</code> used to select which |
172 * @param selector A {@code CRLSelector} used to select which |
173 * <code>CRL</code>s should be returned. Specify <code>null</code> |
173 * {@code CRL}s should be returned. Specify {@code null} |
174 * to return all <code>CRL</code>s (if supported). |
174 * to return all {@code CRL}s (if supported). |
175 * @return A <code>Collection</code> of <code>CRL</code>s that |
175 * @return A {@code Collection} of {@code CRL}s that |
176 * match the specified selector (never <code>null</code>) |
176 * match the specified selector (never {@code null}) |
177 * @throws CertStoreException if an exception occurs |
177 * @throws CertStoreException if an exception occurs |
178 */ |
178 */ |
179 public final Collection<? extends CRL> getCRLs(CRLSelector selector) |
179 public final Collection<? extends CRL> getCRLs(CRLSelector selector) |
180 throws CertStoreException { |
180 throws CertStoreException { |
181 return storeSpi.engineGetCRLs(selector); |
181 return storeSpi.engineGetCRLs(selector); |
182 } |
182 } |
183 |
183 |
184 /** |
184 /** |
185 * Returns a <code>CertStore</code> object that implements the specified |
185 * Returns a {@code CertStore} object that implements the specified |
186 * <code>CertStore</code> type and is initialized with the specified |
186 * {@code CertStore} type and is initialized with the specified |
187 * parameters. |
187 * parameters. |
188 * |
188 * |
189 * <p> This method traverses the list of registered security Providers, |
189 * <p> This method traverses the list of registered security Providers, |
190 * starting with the most preferred Provider. |
190 * starting with the most preferred Provider. |
191 * A new CertStore object encapsulating the |
191 * A new CertStore object encapsulating the |
193 * Provider that supports the specified type is returned. |
193 * Provider that supports the specified type is returned. |
194 * |
194 * |
195 * <p> Note that the list of registered providers may be retrieved via |
195 * <p> Note that the list of registered providers may be retrieved via |
196 * the {@link Security#getProviders() Security.getProviders()} method. |
196 * the {@link Security#getProviders() Security.getProviders()} method. |
197 * |
197 * |
198 * <p>The <code>CertStore</code> that is returned is initialized with the |
198 * <p>The {@code CertStore} that is returned is initialized with the |
199 * specified <code>CertStoreParameters</code>. The type of parameters |
199 * specified {@code CertStoreParameters}. The type of parameters |
200 * needed may vary between different types of <code>CertStore</code>s. |
200 * needed may vary between different types of {@code CertStore}s. |
201 * Note that the specified <code>CertStoreParameters</code> object is |
201 * Note that the specified {@code CertStoreParameters} object is |
202 * cloned. |
202 * cloned. |
203 * |
203 * |
204 * @param type the name of the requested <code>CertStore</code> type. |
204 * @param type the name of the requested {@code CertStore} type. |
205 * See the CertStore section in the <a href= |
205 * See the CertStore section in the <a href= |
206 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertStore"> |
206 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertStore"> |
207 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> |
207 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> |
208 * for information about standard types. |
208 * for information about standard types. |
209 * |
209 * |
210 * @param params the initialization parameters (may be <code>null</code>). |
210 * @param params the initialization parameters (may be {@code null}). |
211 * |
211 * |
212 * @return a <code>CertStore</code> object that implements the specified |
212 * @return a {@code CertStore} object that implements the specified |
213 * <code>CertStore</code> type. |
213 * {@code CertStore} type. |
214 * |
214 * |
215 * @throws NoSuchAlgorithmException if no Provider supports a |
215 * @throws NoSuchAlgorithmException if no Provider supports a |
216 * CertStoreSpi implementation for the specified type. |
216 * CertStoreSpi implementation for the specified type. |
217 * |
217 * |
218 * @throws InvalidAlgorithmParameterException if the specified |
218 * @throws InvalidAlgorithmParameterException if the specified |
219 * initialization parameters are inappropriate for this |
219 * initialization parameters are inappropriate for this |
220 * <code>CertStore</code>. |
220 * {@code CertStore}. |
221 * |
221 * |
222 * @see java.security.Provider |
222 * @see java.security.Provider |
223 */ |
223 */ |
224 public static CertStore getInstance(String type, CertStoreParameters params) |
224 public static CertStore getInstance(String type, CertStoreParameters params) |
225 throws InvalidAlgorithmParameterException, |
225 throws InvalidAlgorithmParameterException, |
242 } |
242 } |
243 throw e; |
243 throw e; |
244 } |
244 } |
245 |
245 |
246 /** |
246 /** |
247 * Returns a <code>CertStore</code> object that implements the specified |
247 * Returns a {@code CertStore} object that implements the specified |
248 * <code>CertStore</code> type. |
248 * {@code CertStore} type. |
249 * |
249 * |
250 * <p> A new CertStore object encapsulating the |
250 * <p> A new CertStore object encapsulating the |
251 * CertStoreSpi implementation from the specified provider |
251 * CertStoreSpi implementation from the specified provider |
252 * is returned. The specified provider must be registered |
252 * is returned. The specified provider must be registered |
253 * in the security provider list. |
253 * in the security provider list. |
254 * |
254 * |
255 * <p> Note that the list of registered providers may be retrieved via |
255 * <p> Note that the list of registered providers may be retrieved via |
256 * the {@link Security#getProviders() Security.getProviders()} method. |
256 * the {@link Security#getProviders() Security.getProviders()} method. |
257 * |
257 * |
258 * <p>The <code>CertStore</code> that is returned is initialized with the |
258 * <p>The {@code CertStore} that is returned is initialized with the |
259 * specified <code>CertStoreParameters</code>. The type of parameters |
259 * specified {@code CertStoreParameters}. The type of parameters |
260 * needed may vary between different types of <code>CertStore</code>s. |
260 * needed may vary between different types of {@code CertStore}s. |
261 * Note that the specified <code>CertStoreParameters</code> object is |
261 * Note that the specified {@code CertStoreParameters} object is |
262 * cloned. |
262 * cloned. |
263 * |
263 * |
264 * @param type the requested <code>CertStore</code> type. |
264 * @param type the requested {@code CertStore} type. |
265 * See the CertStore section in the <a href= |
265 * See the CertStore section in the <a href= |
266 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertStore"> |
266 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertStore"> |
267 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> |
267 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> |
268 * for information about standard types. |
268 * for information about standard types. |
269 * |
269 * |
270 * @param params the initialization parameters (may be <code>null</code>). |
270 * @param params the initialization parameters (may be {@code null}). |
271 * |
271 * |
272 * @param provider the name of the provider. |
272 * @param provider the name of the provider. |
273 * |
273 * |
274 * @return a <code>CertStore</code> object that implements the |
274 * @return a {@code CertStore} object that implements the |
275 * specified type. |
275 * specified type. |
276 * |
276 * |
277 * @throws NoSuchAlgorithmException if a CertStoreSpi |
277 * @throws NoSuchAlgorithmException if a CertStoreSpi |
278 * implementation for the specified type is not |
278 * implementation for the specified type is not |
279 * available from the specified provider. |
279 * available from the specified provider. |
280 * |
280 * |
281 * @throws InvalidAlgorithmParameterException if the specified |
281 * @throws InvalidAlgorithmParameterException if the specified |
282 * initialization parameters are inappropriate for this |
282 * initialization parameters are inappropriate for this |
283 * <code>CertStore</code>. |
283 * {@code CertStore}. |
284 * |
284 * |
285 * @throws NoSuchProviderException if the specified provider is not |
285 * @throws NoSuchProviderException if the specified provider is not |
286 * registered in the security provider list. |
286 * registered in the security provider list. |
287 * |
287 * |
288 * @exception IllegalArgumentException if the <code>provider</code> is |
288 * @exception IllegalArgumentException if the {@code provider} is |
289 * null or empty. |
289 * null or empty. |
290 * |
290 * |
291 * @see java.security.Provider |
291 * @see java.security.Provider |
292 */ |
292 */ |
293 public static CertStore getInstance(String type, |
293 public static CertStore getInstance(String type, |
303 return handleException(e); |
303 return handleException(e); |
304 } |
304 } |
305 } |
305 } |
306 |
306 |
307 /** |
307 /** |
308 * Returns a <code>CertStore</code> object that implements the specified |
308 * Returns a {@code CertStore} object that implements the specified |
309 * <code>CertStore</code> type. |
309 * {@code CertStore} type. |
310 * |
310 * |
311 * <p> A new CertStore object encapsulating the |
311 * <p> A new CertStore object encapsulating the |
312 * CertStoreSpi implementation from the specified Provider |
312 * CertStoreSpi implementation from the specified Provider |
313 * object is returned. Note that the specified Provider object |
313 * object is returned. Note that the specified Provider object |
314 * does not have to be registered in the provider list. |
314 * does not have to be registered in the provider list. |
315 * |
315 * |
316 * <p>The <code>CertStore</code> that is returned is initialized with the |
316 * <p>The {@code CertStore} that is returned is initialized with the |
317 * specified <code>CertStoreParameters</code>. The type of parameters |
317 * specified {@code CertStoreParameters}. The type of parameters |
318 * needed may vary between different types of <code>CertStore</code>s. |
318 * needed may vary between different types of {@code CertStore}s. |
319 * Note that the specified <code>CertStoreParameters</code> object is |
319 * Note that the specified {@code CertStoreParameters} object is |
320 * cloned. |
320 * cloned. |
321 * |
321 * |
322 * @param type the requested <code>CertStore</code> type. |
322 * @param type the requested {@code CertStore} type. |
323 * See the CertStore section in the <a href= |
323 * See the CertStore section in the <a href= |
324 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertStore"> |
324 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertStore"> |
325 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> |
325 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> |
326 * for information about standard types. |
326 * for information about standard types. |
327 * |
327 * |
328 * @param params the initialization parameters (may be <code>null</code>). |
328 * @param params the initialization parameters (may be {@code null}). |
329 * |
329 * |
330 * @param provider the provider. |
330 * @param provider the provider. |
331 * |
331 * |
332 * @return a <code>CertStore</code> object that implements the |
332 * @return a {@code CertStore} object that implements the |
333 * specified type. |
333 * specified type. |
334 * |
334 * |
335 * @exception NoSuchAlgorithmException if a CertStoreSpi |
335 * @exception NoSuchAlgorithmException if a CertStoreSpi |
336 * implementation for the specified type is not available |
336 * implementation for the specified type is not available |
337 * from the specified Provider object. |
337 * from the specified Provider object. |
338 * |
338 * |
339 * @throws InvalidAlgorithmParameterException if the specified |
339 * @throws InvalidAlgorithmParameterException if the specified |
340 * initialization parameters are inappropriate for this |
340 * initialization parameters are inappropriate for this |
341 * <code>CertStore</code> |
341 * {@code CertStore} |
342 * |
342 * |
343 * @exception IllegalArgumentException if the <code>provider</code> is |
343 * @exception IllegalArgumentException if the {@code provider} is |
344 * null. |
344 * null. |
345 * |
345 * |
346 * @see java.security.Provider |
346 * @see java.security.Provider |
347 */ |
347 */ |
348 public static CertStore getInstance(String type, CertStoreParameters params, |
348 public static CertStore getInstance(String type, CertStoreParameters params, |
357 return handleException(e); |
357 return handleException(e); |
358 } |
358 } |
359 } |
359 } |
360 |
360 |
361 /** |
361 /** |
362 * Returns the parameters used to initialize this <code>CertStore</code>. |
362 * Returns the parameters used to initialize this {@code CertStore}. |
363 * Note that the <code>CertStoreParameters</code> object is cloned before |
363 * Note that the {@code CertStoreParameters} object is cloned before |
364 * it is returned. |
364 * it is returned. |
365 * |
365 * |
366 * @return the parameters used to initialize this <code>CertStore</code> |
366 * @return the parameters used to initialize this {@code CertStore} |
367 * (may be <code>null</code>) |
367 * (may be {@code null}) |
368 */ |
368 */ |
369 public final CertStoreParameters getCertStoreParameters() { |
369 public final CertStoreParameters getCertStoreParameters() { |
370 return (params == null ? null : (CertStoreParameters) params.clone()); |
370 return (params == null ? null : (CertStoreParameters) params.clone()); |
371 } |
371 } |
372 |
372 |
373 /** |
373 /** |
374 * Returns the type of this <code>CertStore</code>. |
374 * Returns the type of this {@code CertStore}. |
375 * |
375 * |
376 * @return the type of this <code>CertStore</code> |
376 * @return the type of this {@code CertStore} |
377 */ |
377 */ |
378 public final String getType() { |
378 public final String getType() { |
379 return this.type; |
379 return this.type; |
380 } |
380 } |
381 |
381 |
382 /** |
382 /** |
383 * Returns the provider of this <code>CertStore</code>. |
383 * Returns the provider of this {@code CertStore}. |
384 * |
384 * |
385 * @return the provider of this <code>CertStore</code> |
385 * @return the provider of this {@code CertStore} |
386 */ |
386 */ |
387 public final Provider getProvider() { |
387 public final Provider getProvider() { |
388 return this.provider; |
388 return this.provider; |
389 } |
389 } |
390 |
390 |