KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)CertPathBuilder.java 1.9 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 sun.security.util.Debug;
18
19 import sun.security.jca.*;
20 import sun.security.jca.GetInstance.Instance;
21
22 /**
23  * A class for building certification paths (also known as certificate chains).
24  * <p>
25  * This class uses a provider-based architecture, as described in the Java
26  * Cryptography Architecture. To create a <code>CertPathBuilder</code>, call
27  * one of the static <code>getInstance</code> methods, passing in the
28  * algorithm name of the <code>CertPathBuilder</code> desired and optionally
29  * the name of the provider desired.
30  * <p>
31  * Once a <code>CertPathBuilder</code> object has been created, certification
32  * paths can be constructed by calling the {@link #build build} method and
33  * passing it an algorithm-specific set of parameters. If successful, the
34  * result (including the <code>CertPath</code> that was built) is returned
35  * in an object that implements the <code>CertPathBuilderResult</code>
36  * interface.
37  * <p>
38  * <b>Concurrent Access</b>
39  * <p>
40  * The static methods of this class are guaranteed to be thread-safe.
41  * Multiple threads may concurrently invoke the static methods defined in
42  * this class with no ill effects.
43  * <p>
44  * However, this is not true for the non-static methods defined by this class.
45  * Unless otherwise documented by a specific provider, threads that need to
46  * access a single <code>CertPathBuilder</code> instance concurrently should
47  * synchronize amongst themselves and provide the necessary locking. Multiple
48  * threads each manipulating a different <code>CertPathBuilder</code> instance
49  * need not synchronize.
50  *
51  * @see CertPath
52  *
53  * @version 1.9 06/28/04
54  * @since 1.4
55  * @author Sean Mullan
56  * @author Yassir Elley
57  */
58 public class CertPathBuilder {
59
60     /*
61      * Constant to lookup in the Security properties file to determine
62      * the default certpathbuilder type. In the Security properties file,
63      * the default certpathbuilder type is given as:
64      * <pre>
65      * certpathbuilder.type=PKIX
66      * </pre>
67      */
68     private static final String JavaDoc CPB_TYPE = "certpathbuilder.type";
69     private static final Debug debug = Debug.getInstance("certpath");
70     private CertPathBuilderSpi JavaDoc builderSpi;
71     private Provider JavaDoc provider;
72     private String JavaDoc algorithm;
73
74     /**
75      * Creates a <code>CertPathBuilder</code> object of the given algorithm,
76      * and encapsulates the given provider implementation (SPI object) in it.
77      *
78      * @param builderSpi the provider implementation
79      * @param provider the provider
80      * @param algorithm the algorithm name
81      */
82     protected CertPathBuilder(CertPathBuilderSpi JavaDoc builderSpi, Provider JavaDoc provider,
83     String JavaDoc algorithm)
84     {
85     this.builderSpi = builderSpi;
86     this.provider = provider;
87     this.algorithm = algorithm;
88     }
89
90     /**
91      * Returns a <code>CertPathBuilder</code> object that implements the
92      * specified algorithm.
93      * <p>
94      * If the default provider package provides an implementation of the
95      * specified <code>CertPathBuilder</code> algorithm, an instance of
96      * <code>CertPathBuilder</code> containing that implementation is returned.
97      * If the requested algorithm is not available in the default package,
98      * other packages are searched.
99      *
100      * @param algorithm the name of the requested <code>CertPathBuilder</code>
101      * algorithm
102      * @return a <code>CertPathBuilder</code> object that implements the
103      * specified algorithm
104      * @throws NoSuchAlgorithmException if the requested algorithm is
105      * not available in the default provider package or any of the other
106      * provider packages that were searched
107      */
108     public static CertPathBuilder JavaDoc getInstance(String JavaDoc algorithm)
109         throws NoSuchAlgorithmException JavaDoc {
110     Instance instance = GetInstance.getInstance("CertPathBuilder",
111         CertPathBuilderSpi JavaDoc.class, algorithm);
112     return new CertPathBuilder JavaDoc((CertPathBuilderSpi JavaDoc)instance.impl,
113         instance.provider, algorithm);
114     }
115
116     /**
117      * Returns a <code>CertPathBuilder</code> object that implements the
118      * specified algorithm, as supplied by the specified provider.
119      *
120      * @param algorithm the name of the requested <code>CertPathBuilder</code>
121      * algorithm
122      * @param provider the name of the provider
123      * @return a <code>CertPathBuilder</code> object that implements the
124      * specified algorithm, as supplied by the specified provider
125      * @throws NoSuchAlgorithmException if the requested algorithm is
126      * not available from the specified provider
127      * @throws NoSuchProviderException if the provider has not been configured
128      * @exception IllegalArgumentException if the <code>provider</code> is
129      * null
130      */
131     public static CertPathBuilder JavaDoc getInstance(String JavaDoc algorithm, String JavaDoc provider)
132        throws NoSuchAlgorithmException JavaDoc, NoSuchProviderException JavaDoc {
133     Instance instance = GetInstance.getInstance("CertPathBuilder",
134         CertPathBuilderSpi JavaDoc.class, algorithm, provider);
135     return new CertPathBuilder JavaDoc((CertPathBuilderSpi JavaDoc)instance.impl,
136         instance.provider, algorithm);
137     }
138
139     /**
140      * Returns a <code>CertPathBuilder</code> object that implements the
141      * specified algorithm, as supplied by the specified provider.
142      * Note: the <code>provider</code> doesn't have to be registered.
143      *
144      * @param algorithm the name of the requested <code>CertPathBuilder</code>
145      * algorithm
146      * @param provider the provider
147      * @return a <code>CertPathBuilder</code> object that implements the
148      * specified algorithm, as supplied by the specified provider
149      * @exception NoSuchAlgorithmException if the requested algorithm is
150      * not available from the specified provider
151      * @exception IllegalArgumentException if the <code>provider</code> is
152      * null.
153      */
154     public static CertPathBuilder JavaDoc getInstance(String JavaDoc algorithm,
155         Provider JavaDoc provider) throws NoSuchAlgorithmException JavaDoc {
156     Instance instance = GetInstance.getInstance("CertPathBuilder",
157         CertPathBuilderSpi JavaDoc.class, algorithm, provider);
158     return new CertPathBuilder JavaDoc((CertPathBuilderSpi JavaDoc)instance.impl,
159         instance.provider, algorithm);
160     }
161     
162     /**
163      * Returns the provider of this <code>CertPathBuilder</code>.
164      *
165      * @return the provider of this <code>CertPathBuilder</code>
166      */
167     public final Provider JavaDoc getProvider() {
168     return this.provider;
169     }
170
171     /**
172      * Returns the name of the algorithm of this <code>CertPathBuilder</code>.
173      *
174      * @return the name of the algorithm of this <code>CertPathBuilder</code>
175      */
176     public final String JavaDoc getAlgorithm() {
177     return this.algorithm;
178     }
179
180     /**
181      * Attempts to build a certification path using the specified algorithm
182      * parameter set.
183      *
184      * @param params the algorithm parameters
185      * @return the result of the build algorithm
186      * @throws CertPathBuilderException if the builder is unable to construct
187      * a certification path that satisfies the specified parameters
188      * @throws InvalidAlgorithmParameterException if the specified parameters
189      * are inappropriate for this <code>CertPathBuilder</code>
190      */
191     public final CertPathBuilderResult JavaDoc build(CertPathParameters JavaDoc params)
192     throws CertPathBuilderException JavaDoc, InvalidAlgorithmParameterException JavaDoc
193     {
194     return builderSpi.engineBuild(params);
195     }
196
197     /**
198      * Returns the default <code>CertPathBuilder</code> type as specified in
199      * the Java security properties file, or the string &quot;PKIX&quot;
200      * if no such property exists. The Java security properties file is
201      * located in the file named &lt;JAVA_HOME&gt;/lib/security/java.security,
202      * where &lt;JAVA_HOME&gt; refers to the directory where the JDK was
203      * installed.
204      *
205      * <p>The default <code>CertPathBuilder</code> type can be used by
206      * applications that do not want to use a hard-coded type when calling one
207      * of the <code>getInstance</code> methods, and want to provide a default
208      * type in case a user does not specify its own.
209      *
210      * <p>The default <code>CertPathBuilder</code> type can be changed by
211      * setting the value of the "certpathbuilder.type" security property
212      * (in the Java security properties file) to the desired type.
213      *
214      * @return the default <code>CertPathBuilder</code> type as specified
215      * in the Java security properties file, or the string &quot;PKIX&quot;
216      * if no such property exists.
217      */
218     public final static String JavaDoc getDefaultType() {
219         String JavaDoc cpbtype;
220         cpbtype = (String JavaDoc)AccessController.doPrivileged(new PrivilegedAction JavaDoc() {
221             public Object JavaDoc run() {
222                 return Security.getProperty(CPB_TYPE);
223             }
224         });
225         if (cpbtype == null) {
226             cpbtype = "PKIX";
227         }
228         return cpbtype;
229     }
230 }
231
Popular Tags