PKIXCertPathChecker


1   /*
2    * @(#)PKIXCertPathChecker.java 1.7 03/12/19
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.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.7 12/19/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  <String  > 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, 
145         Collection  <String  > unresolvedCritExts) 
146         throws CertPathValidatorException  ;
147 
148     /**
149      * Returns a clone of this object. Calls the <code>Object.clone()</code>
150      * method.
151      * All subclasses which maintain state must support and
152      * override this method, if necessary.
153      * 
154      * @return a copy of this <code>PKIXCertPathChecker</code>
155      */
156     public Object   clone() {
157     try {
158         return super.clone();
159     } catch (CloneNotSupportedException   e) {
160         /* Cannot happen */
161         throw new InternalError  (e.toString());
162     }
163     }
164 }
165
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags