1. /*

  2.  * @(#)PKIXCertPathChecker.java	1.5 03/01/23

  3.  *

  4.  * Copyright 2003 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.util.Collection;

  11. import java.util.Set;

  12. 

  13. /**

  14.  * An abstract class that performs one or more checks on an 

  15.  * <code>X509Certificate</code>. 

  16.  * 

  17.  * <p>A concrete implementation of the <code>PKIXCertPathChecker</code> class 

  18.  * can be created to extend the PKIX certification path validation algorithm.

  19.  * For example, an implementation may check for and process a critical private

  20.  * extension of each certificate in a certification path.

  21.  *

  22.  * <p>Instances of <code>PKIXCertPathChecker</code> are passed as parameters

  23.  * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers}

  24.  * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods 

  25.  * of the <code>PKIXParameters</code> and <code>PKIXBuilderParameters</code>

  26.  * class. Each of the <code>PKIXCertPathChecker</code>s {@link #check check}

  27.  * methods will be called, in turn, for each certificate processed by a PKIX 

  28.  * <code>CertPathValidator</code> or <code>CertPathBuilder</code> 

  29.  * implementation.

  30.  * 

  31.  * <p>A <code>PKIXCertPathChecker</code> may be called multiple times on 

  32.  * successive certificates in a certification path. Concrete subclasses

  33.  * are expected to maintain any internal state that may be necessary to 

  34.  * check successive certificates. The {@link #init init} method is used 

  35.  * to initialize the internal state of the checker so that the certificates 

  36.  * of a new certification path may be checked. A stateful implementation

  37.  * <b>must</b> override the {@link #clone clone} method if necessary in 

  38.  * order to allow a PKIX <code>CertPathBuilder</code> to efficiently 

  39.  * backtrack and try other paths. In these situations, the 

  40.  * <code>CertPathBuilder</code> is able to restore prior path validation 

  41.  * states by restoring the cloned <code>PKIXCertPathChecker</code>s.

  42.  *

  43.  * <p>The order in which the certificates are presented to the 

  44.  * <code>PKIXCertPathChecker</code> may be either in the forward direction 

  45.  * (from target to most-trusted CA) or in the reverse direction (from 

  46.  * most-trusted CA to target). A <code>PKIXCertPathChecker</code> implementation

  47.  * <b>must</b> support reverse checking (the ability to perform its checks when

  48.  * it is presented with certificates in the reverse direction) and <b>may</b> 

  49.  * support forward checking (the ability to perform its checks when it is 

  50.  * presented with certificates in the forward direction). The 

  51.  * {@link #isForwardCheckingSupported isForwardCheckingSupported} method 

  52.  * indicates whether forward checking is supported.

  53.  * <p>

  54.  * Additional input parameters required for executing the check may be 

  55.  * specified through constructors of concrete implementations of this class.

  56.  * <p>

  57.  * <b>Concurrent Access</b>

  58.  * <p>

  59.  * Unless otherwise specified, the methods defined in this class are not

  60.  * thread-safe. Multiple threads that need to access a single

  61.  * object concurrently should synchronize amongst themselves and

  62.  * provide the necessary locking. Multiple threads each manipulating

  63.  * separate objects need not synchronize.

  64.  *

  65.  * @see PKIXParameters 

  66.  * @see PKIXBuilderParameters

  67.  *

  68.  * @version 	1.5 01/23/03

  69.  * @since	1.4

  70.  * @author	Yassir Elley

  71.  * @author	Sean Mullan

  72.  */

  73. public abstract class PKIXCertPathChecker implements Cloneable {

  74. 

  75.     /**

  76.      * Default constructor.

  77.      */

  78.     protected PKIXCertPathChecker() {}

  79. 

  80.     /**

  81.      * Initializes the internal state of this <code>PKIXCertPathChecker</code>.

  82.      * <p> 

  83.      * The <code>forward</code> flag specifies the order that

  84.      * certificates will be passed to the {@link #check check} method

  85.      * (forward or reverse). A <code>PKIXCertPathChecker</code> <b>must</b> 

  86.      * support reverse checking and <b>may</b> support forward checking. 

  87.      *

  88.      * @param forward the order that certificates are presented to

  89.      * the <code>check</code> method. If <code>true</code>, certificates 

  90.      * are presented from target to most-trusted CA (forward); if 

  91.      * <code>false</code>, from most-trusted CA to target (reverse).

  92.      * @throws CertPathValidatorException if this 

  93.      * <code>PKIXCertPathChecker</code> is unable to check certificates in 

  94.      * the specified order; it should never be thrown if the forward flag 

  95.      * is false since reverse checking must be supported

  96.      */

  97.     public abstract void init(boolean forward) 

  98. 	throws CertPathValidatorException;

  99. 

  100.     /**

  101.      * Indicates if forward checking is supported. Forward checking refers

  102.      * to the ability of the <code>PKIXCertPathChecker</code> to perform 

  103.      * its checks when certificates are presented to the <code>check</code>

  104.      * method in the forward direction (from target to most-trusted CA).

  105.      *

  106.      * @return <code>true</code> if forward checking is supported, 

  107.      * <code>false</code> otherwise

  108.      */

  109.     public abstract boolean isForwardCheckingSupported();

  110. 

  111.     /**

  112.      * Returns an immutable <code>Set</code> of X.509 certificate extensions 

  113.      * that this <code>PKIXCertPathChecker</code> supports (i.e. recognizes, is 

  114.      * able to process), or <code>null</code> if no extensions are supported. 

  115.      * <p>

  116.      * Each element of the set is a <code>String</code> representing the

  117.      * Object Identifier (OID) of the X.509 extension that is supported.

  118.      * The OID is represented by a set of nonnegative integers separated by

  119.      * periods.

  120.      * <p>

  121.      * All X.509 certificate extensions that a <code>PKIXCertPathChecker</code>

  122.      * might possibly be able to process should be included in the set.

  123.      *

  124.      * @return an immutable <code>Set</code> of X.509 extension OIDs (in

  125.      * <code>String</code> format) supported by this 

  126.      * <code>PKIXCertPathChecker</code>, or <code>null</code> if no 

  127.      * extensions are supported

  128.      */

  129.     public abstract Set getSupportedExtensions();

  130. 

  131.     /**

  132.      * Performs the check(s) on the specified certificate using its internal 

  133.      * state and removes any critical extensions that it processes from the 

  134.      * specified collection of OID strings that represent the unresolved 

  135.      * critical extensions. The certificates are presented in the order 

  136.      * specified by the <code>init</code> method.

  137.      *

  138.      * @param cert the <code>Certificate</code> to be checked

  139.      * @param unresolvedCritExts a <code>Collection</code> of OID strings 

  140.      * representing the current set of unresolved critical extensions

  141.      * @exception CertPathValidatorException if the specified certificate does 

  142.      * not pass the check

  143.      */

  144.     public abstract void check(Certificate cert, Collection unresolvedCritExts)

  145. 	throws CertPathValidatorException;

  146. 

  147.     /**

  148.      * Returns a clone of this object. Calls the <code>Object.clone()</code>

  149.      * method.

  150.      * All subclasses which maintain state must support and

  151.      * override this method, if necessary.

  152.      * 

  153.      * @return a copy of this <code>PKIXCertPathChecker</code>

  154.      */

  155.     public Object clone() {

  156. 	try {

  157. 	    return super.clone();

  158. 	} catch (CloneNotSupportedException e) {

  159. 	    /* Cannot happen */

  160. 	    throw new InternalError(e.toString());

  161. 	}

  162.     }

  163. }