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;

  11. import java.security.InvalidAlgorithmParameterException;

  12. import java.security.NoSuchAlgorithmException;

  13. import java.security.NoSuchProviderException;

  14. import java.security.PrivilegedAction;

  15. import java.security.Provider;

  16. import java.security.Security;

  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 CPB_TYPE = "certpathbuilder.type";

  69.     private static final Debug debug = Debug.getInstance("certpath");

  70.     private CertPathBuilderSpi builderSpi;

  71.     private Provider provider;

  72.     private String 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 builderSpi, Provider provider, 

  83. 	String 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 getInstance(String algorithm)

  109. 	    throws NoSuchAlgorithmException {

  110. 	Instance instance = GetInstance.getInstance("CertPathBuilder", 

  111. 	    CertPathBuilderSpi.class, algorithm);

  112. 	return new CertPathBuilder((CertPathBuilderSpi)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 getInstance(String algorithm, String provider)

  132. 	   throws NoSuchAlgorithmException, NoSuchProviderException {

  133. 	Instance instance = GetInstance.getInstance("CertPathBuilder", 

  134. 	    CertPathBuilderSpi.class, algorithm, provider);

  135. 	return new CertPathBuilder((CertPathBuilderSpi)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 getInstance(String algorithm,

  155. 	    Provider provider) throws NoSuchAlgorithmException {

  156. 	Instance instance = GetInstance.getInstance("CertPathBuilder", 

  157. 	    CertPathBuilderSpi.class, algorithm, provider);

  158. 	return new CertPathBuilder((CertPathBuilderSpi)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 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 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 build(CertPathParameters params)

  192. 	throws CertPathBuilderException, InvalidAlgorithmParameterException

  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 "PKIX"

  200.      * if no such property exists. The Java security properties file is

  201.      * located in the file named <JAVA_HOME>/lib/security/java.security,

  202.      * where <JAVA_HOME> 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 "PKIX"

  216.      * if no such property exists.

  217.      */

  218.     public final static String getDefaultType() {

  219.         String cpbtype;

  220.         cpbtype = (String)AccessController.doPrivileged(new PrivilegedAction() {

  221.             public Object run() {

  222.                 return Security.getProperty(CPB_TYPE);

  223.             }

  224.         });

  225.         if (cpbtype == null) {

  226.             cpbtype = "PKIX";

  227.         }

  228.         return cpbtype;

  229.     }

  230. }