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 sun.security.util.Debug;
36
37 import sun.security.jca;
38 import sun.security.jca.GetInstance.Instance;
39
40 /**
41 * A class for validating certification paths (also known as certificate
42 * chains).
43 * <p>
44 * This class uses a provider-based architecture.
45 * To create a <code>CertPathValidator</code>,
46 * call one of the static <code>getInstance</code> methods, passing in the
47 * algorithm name of the <code>CertPathValidator</code> desired and
48 * optionally the name of the provider desired.
49 * <p>
50 * Once a <code>CertPathValidator</code> object has been created, it can
51 * be used to validate certification paths by calling the {@link #validate
52 * validate} method and passing it the <code>CertPath</code> to be validated
53 * and an algorithm-specific set of parameters. If successful, the result is
54 * returned in an object that implements the
55 * <code>CertPathValidatorResult</code> interface.
56 * <p>
57 * <b>Concurrent Access</b>
58 * <p>
59 * The static methods of this class are guaranteed to be thread-safe.
60 * Multiple threads may concurrently invoke the static methods defined in
61 * this class with no ill effects.
62 * <p>
63 * However, this is not true for the non-static methods defined by this class.
64 * Unless otherwise documented by a specific provider, threads that need to
65 * access a single <code>CertPathValidator</code> instance concurrently should
66 * synchronize amongst themselves and provide the necessary locking. Multiple
67 * threads each manipulating a different <code>CertPathValidator</code>
68 * instance need not synchronize.
69 *
70 * @see CertPath
71 *
72 * @since 1.4
73 * @author Yassir Elley
74 */
75 public class CertPathValidator {
76
77 /*
78 * Constant to lookup in the Security properties file to determine
79 * the default certpathvalidator type. In the Security properties file,
80 * the default certpathvalidator type is given as:
81 * <pre>
82 * certpathvalidator.type=PKIX
83 * </pre>
84 */
85 private static final String CPV_TYPE = "certpathvalidator.type";
86 private static final Debug debug = Debug.getInstance("certpath");
87 private CertPathValidatorSpi validatorSpi;
88 private Provider provider;
89 private String algorithm;
90
91 /**
92 * Creates a <code>CertPathValidator</code> object of the given algorithm,
93 * and encapsulates the given provider implementation (SPI object) in it.
94 *
95 * @param validatorSpi the provider implementation
96 * @param provider the provider
97 * @param algorithm the algorithm name
98 */
99 protected CertPathValidator(CertPathValidatorSpi validatorSpi,
100 Provider provider, String algorithm)
101 {
102 this.validatorSpi = validatorSpi;
103 this.provider = provider;
104 this.algorithm = algorithm;
105 }
106
107 /**
108 * Returns a <code>CertPathValidator</code> object that implements the
109 * specified algorithm.
110 *
111 * <p> This method traverses the list of registered security Providers,
112 * starting with the most preferred Provider.
113 * A new CertPathValidator object encapsulating the
114 * CertPathValidatorSpi implementation from the first
115 * Provider that supports the specified algorithm is returned.
116 *
117 * <p> Note that the list of registered providers may be retrieved via
118 * the {@link Security#getProviders() Security.getProviders()} method.
119 *
120 * @param algorithm the name of the requested <code>CertPathValidator</code>
121 * algorithm. See Appendix A in the <a href=
122 * "../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA">
123 * Java Certification Path API Programmer's Guide </a>
124 * for information about standard algorithm names.
125 *
126 * @return a <code>CertPathValidator</code> object that implements the
127 * specified algorithm.
128 *
129 * @exception NoSuchAlgorithmException if no Provider supports a
130 * CertPathValidatorSpi implementation for the
131 * specified algorithm.
132 *
133 * @see java.security.Provider
134 */
135 public static CertPathValidator getInstance(String algorithm)
136 throws NoSuchAlgorithmException {
137 Instance instance = GetInstance.getInstance("CertPathValidator",
138 CertPathValidatorSpi.class, algorithm);
139 return new CertPathValidator((CertPathValidatorSpi)instance.impl,
140 instance.provider, algorithm);
141 }
142
143 /**
144 * Returns a <code>CertPathValidator</code> object that implements the
145 * specified algorithm.
146 *
147 * <p> A new CertPathValidator object encapsulating the
148 * CertPathValidatorSpi implementation from the specified provider
149 * is returned. The specified provider must be registered
150 * in the security provider list.
151 *
152 * <p> Note that the list of registered providers may be retrieved via
153 * the {@link Security#getProviders() Security.getProviders()} method.
154 *
155 * @param algorithm the name of the requested <code>CertPathValidator</code>
156 * algorithm. See Appendix A in the <a href=
157 * "../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA">
158 * Java Certification Path API Programmer's Guide </a>
159 * for information about standard algorithm names.
160 *
161 * @param provider the name of the provider.
162 *
163 * @return a <code>CertPathValidator</code> object that implements the
164 * specified algorithm.
165 *
166 * @exception NoSuchAlgorithmException if a CertPathValidatorSpi
167 * implementation for the specified algorithm is not
168 * available from the specified provider.
169 *
170 * @exception NoSuchProviderException if the specified provider is not
171 * registered in the security provider list.
172 *
173 * @exception IllegalArgumentException if the <code>provider</code> is
174 * null or empty.
175 *
176 * @see java.security.Provider
177 */
178 public static CertPathValidator getInstance(String algorithm,
179 String provider) throws NoSuchAlgorithmException,
180 NoSuchProviderException {
181 Instance instance = GetInstance.getInstance("CertPathValidator",
182 CertPathValidatorSpi.class, algorithm, provider);
183 return new CertPathValidator((CertPathValidatorSpi)instance.impl,
184 instance.provider, algorithm);
185 }
186
187 /**
188 * Returns a <code>CertPathValidator</code> object that implements the
189 * specified algorithm.
190 *
191 * <p> A new CertPathValidator object encapsulating the
192 * CertPathValidatorSpi implementation from the specified Provider
193 * object is returned. Note that the specified Provider object
194 * does not have to be registered in the provider list.
195 *
196 * @param algorithm the name of the requested
197 * <code>CertPathValidator</code> algorithm.
198 * See Appendix A in the <a href=
199 * "../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA">
200 * Java Certification Path API Programmer's Guide </a>
201 * for information about standard algorithm names.
202 *
203 * @param provider the provider.
204 *
205 * @return a <code>CertPathValidator</code> object that implements the
206 * specified algorithm.
207 *
208 * @exception NoSuchAlgorithmException if a CertPathValidatorSpi
209 * implementation for the specified algorithm is not available
210 * from the specified Provider object.
211 *
212 * @exception IllegalArgumentException if the <code>provider</code> is
213 * null.
214 *
215 * @see java.security.Provider
216 */
217 public static CertPathValidator getInstance(String algorithm,
218 Provider provider) throws NoSuchAlgorithmException {
219 Instance instance = GetInstance.getInstance("CertPathValidator",
220 CertPathValidatorSpi.class, algorithm, provider);
221 return new CertPathValidator((CertPathValidatorSpi)instance.impl,
222 instance.provider, algorithm);
223 }
224
225 /**
226 * Returns the <code>Provider</code> of this
227 * <code>CertPathValidator</code>.
228 *
229 * @return the <code>Provider</code> of this <code>CertPathValidator</code>
230 */
231 public final Provider getProvider() {
232 return this.provider;
233 }
234
235 /**
236 * Returns the algorithm name of this <code>CertPathValidator</code>.
237 *
238 * @return the algorithm name of this <code>CertPathValidator</code>
239 */
240 public final String getAlgorithm() {
241 return this.algorithm;
242 }
243
244 /**
245 * Validates the specified certification path using the specified
246 * algorithm parameter set.
247 * <p>
248 * The <code>CertPath</code> specified must be of a type that is
249 * supported by the validation algorithm, otherwise an
250 * <code>InvalidAlgorithmParameterException</code> will be thrown. For
251 * example, a <code>CertPathValidator</code> that implements the PKIX
252 * algorithm validates <code>CertPath</code> objects of type X.509.
253 *
254 * @param certPath the <code>CertPath</code> to be validated
255 * @param params the algorithm parameters
256 * @return the result of the validation algorithm
257 * @exception CertPathValidatorException if the <code>CertPath</code>
258 * does not validate
259 * @exception InvalidAlgorithmParameterException if the specified
260 * parameters or the type of the specified <code>CertPath</code> are
261 * inappropriate for this <code>CertPathValidator</code>
262 */
263 public final CertPathValidatorResult validate(CertPath certPath,
264 CertPathParameters params)
265 throws CertPathValidatorException, InvalidAlgorithmParameterException
266 {
267 return validatorSpi.engineValidate(certPath, params);
268 }
269
270 /**
271 * Returns the default <code>CertPathValidator</code> type as specified in
272 * the Java security properties file, or the string "PKIX"
273 * if no such property exists. The Java security properties file is
274 * located in the file named <JAVA_HOME>/lib/security/java.security.
275 * <JAVA_HOME> refers to the value of the java.home system property,
276 * and specifies the directory where the JRE is installed.
277 *
278 * <p>The default <code>CertPathValidator</code> type can be used by
279 * applications that do not want to use a hard-coded type when calling one
280 * of the <code>getInstance</code> methods, and want to provide a default
281 * type in case a user does not specify its own.
282 *
283 * <p>The default <code>CertPathValidator</code> type can be changed by
284 * setting the value of the "certpathvalidator.type" security property
285 * (in the Java security properties file) to the desired type.
286 *
287 * @return the default <code>CertPathValidator</code> type as specified
288 * in the Java security properties file, or the string "PKIX"
289 * if no such property exists.
290 */
291 public final static String getDefaultType() {
292 String cpvtype;
293 cpvtype = AccessController.doPrivileged(new PrivilegedAction<String>() {
294 public String run() {
295 return Security.getProperty(CPV_TYPE);
296 }
297 });
298 if (cpvtype == null) {
299 cpvtype = "PKIX";
300 }
301 return cpvtype;
302 }
303 }
Save This Page