28 import java.util.Collection; |
28 import java.util.Collection; |
29 import java.util.Set; |
29 import java.util.Set; |
30 |
30 |
31 /** |
31 /** |
32 * An abstract class that performs one or more checks on an |
32 * An abstract class that performs one or more checks on an |
33 * <code>X509Certificate</code>. |
33 * {@code X509Certificate}. |
34 * |
34 * |
35 * <p>A concrete implementation of the <code>PKIXCertPathChecker</code> class |
35 * <p>A concrete implementation of the {@code PKIXCertPathChecker} class |
36 * can be created to extend the PKIX certification path validation algorithm. |
36 * can be created to extend the PKIX certification path validation algorithm. |
37 * For example, an implementation may check for and process a critical private |
37 * For example, an implementation may check for and process a critical private |
38 * extension of each certificate in a certification path. |
38 * extension of each certificate in a certification path. |
39 * |
39 * |
40 * <p>Instances of <code>PKIXCertPathChecker</code> are passed as parameters |
40 * <p>Instances of {@code PKIXCertPathChecker} are passed as parameters |
41 * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers} |
41 * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers} |
42 * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods |
42 * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods |
43 * of the <code>PKIXParameters</code> and <code>PKIXBuilderParameters</code> |
43 * of the {@code PKIXParameters} and {@code PKIXBuilderParameters} |
44 * class. Each of the <code>PKIXCertPathChecker</code>s {@link #check check} |
44 * class. Each of the {@code PKIXCertPathChecker}s {@link #check check} |
45 * methods will be called, in turn, for each certificate processed by a PKIX |
45 * methods will be called, in turn, for each certificate processed by a PKIX |
46 * <code>CertPathValidator</code> or <code>CertPathBuilder</code> |
46 * {@code CertPathValidator} or {@code CertPathBuilder} |
47 * implementation. |
47 * implementation. |
48 * |
48 * |
49 * <p>A <code>PKIXCertPathChecker</code> may be called multiple times on |
49 * <p>A {@code PKIXCertPathChecker} may be called multiple times on |
50 * successive certificates in a certification path. Concrete subclasses |
50 * successive certificates in a certification path. Concrete subclasses |
51 * are expected to maintain any internal state that may be necessary to |
51 * are expected to maintain any internal state that may be necessary to |
52 * check successive certificates. The {@link #init init} method is used |
52 * check successive certificates. The {@link #init init} method is used |
53 * to initialize the internal state of the checker so that the certificates |
53 * to initialize the internal state of the checker so that the certificates |
54 * of a new certification path may be checked. A stateful implementation |
54 * of a new certification path may be checked. A stateful implementation |
55 * <b>must</b> override the {@link #clone clone} method if necessary in |
55 * <b>must</b> override the {@link #clone clone} method if necessary in |
56 * order to allow a PKIX <code>CertPathBuilder</code> to efficiently |
56 * order to allow a PKIX {@code CertPathBuilder} to efficiently |
57 * backtrack and try other paths. In these situations, the |
57 * backtrack and try other paths. In these situations, the |
58 * <code>CertPathBuilder</code> is able to restore prior path validation |
58 * {@code CertPathBuilder} is able to restore prior path validation |
59 * states by restoring the cloned <code>PKIXCertPathChecker</code>s. |
59 * states by restoring the cloned {@code PKIXCertPathChecker}s. |
60 * |
60 * |
61 * <p>The order in which the certificates are presented to the |
61 * <p>The order in which the certificates are presented to the |
62 * <code>PKIXCertPathChecker</code> may be either in the forward direction |
62 * {@code PKIXCertPathChecker} may be either in the forward direction |
63 * (from target to most-trusted CA) or in the reverse direction (from |
63 * (from target to most-trusted CA) or in the reverse direction (from |
64 * most-trusted CA to target). A <code>PKIXCertPathChecker</code> implementation |
64 * most-trusted CA to target). A {@code PKIXCertPathChecker} implementation |
65 * <b>must</b> support reverse checking (the ability to perform its checks when |
65 * <b>must</b> support reverse checking (the ability to perform its checks when |
66 * it is presented with certificates in the reverse direction) and <b>may</b> |
66 * it is presented with certificates in the reverse direction) and <b>may</b> |
67 * support forward checking (the ability to perform its checks when it is |
67 * support forward checking (the ability to perform its checks when it is |
68 * presented with certificates in the forward direction). The |
68 * presented with certificates in the forward direction). The |
69 * {@link #isForwardCheckingSupported isForwardCheckingSupported} method |
69 * {@link #isForwardCheckingSupported isForwardCheckingSupported} method |
94 * Default constructor. |
94 * Default constructor. |
95 */ |
95 */ |
96 protected PKIXCertPathChecker() {} |
96 protected PKIXCertPathChecker() {} |
97 |
97 |
98 /** |
98 /** |
99 * Initializes the internal state of this <code>PKIXCertPathChecker</code>. |
99 * Initializes the internal state of this {@code PKIXCertPathChecker}. |
100 * <p> |
100 * <p> |
101 * The <code>forward</code> flag specifies the order that |
101 * The {@code forward} flag specifies the order that |
102 * certificates will be passed to the {@link #check check} method |
102 * certificates will be passed to the {@link #check check} method |
103 * (forward or reverse). A <code>PKIXCertPathChecker</code> <b>must</b> |
103 * (forward or reverse). A {@code PKIXCertPathChecker} <b>must</b> |
104 * support reverse checking and <b>may</b> support forward checking. |
104 * support reverse checking and <b>may</b> support forward checking. |
105 * |
105 * |
106 * @param forward the order that certificates are presented to |
106 * @param forward the order that certificates are presented to |
107 * the <code>check</code> method. If <code>true</code>, certificates |
107 * the {@code check} method. If {@code true}, certificates |
108 * are presented from target to most-trusted CA (forward); if |
108 * are presented from target to most-trusted CA (forward); if |
109 * <code>false</code>, from most-trusted CA to target (reverse). |
109 * {@code false}, from most-trusted CA to target (reverse). |
110 * @throws CertPathValidatorException if this |
110 * @throws CertPathValidatorException if this |
111 * <code>PKIXCertPathChecker</code> is unable to check certificates in |
111 * {@code PKIXCertPathChecker} is unable to check certificates in |
112 * the specified order; it should never be thrown if the forward flag |
112 * the specified order; it should never be thrown if the forward flag |
113 * is false since reverse checking must be supported |
113 * is false since reverse checking must be supported |
114 */ |
114 */ |
115 @Override |
115 @Override |
116 public abstract void init(boolean forward) |
116 public abstract void init(boolean forward) |
117 throws CertPathValidatorException; |
117 throws CertPathValidatorException; |
118 |
118 |
119 /** |
119 /** |
120 * Indicates if forward checking is supported. Forward checking refers |
120 * Indicates if forward checking is supported. Forward checking refers |
121 * to the ability of the <code>PKIXCertPathChecker</code> to perform |
121 * to the ability of the {@code PKIXCertPathChecker} to perform |
122 * its checks when certificates are presented to the <code>check</code> |
122 * its checks when certificates are presented to the {@code check} |
123 * method in the forward direction (from target to most-trusted CA). |
123 * method in the forward direction (from target to most-trusted CA). |
124 * |
124 * |
125 * @return <code>true</code> if forward checking is supported, |
125 * @return {@code true} if forward checking is supported, |
126 * <code>false</code> otherwise |
126 * {@code false} otherwise |
127 */ |
127 */ |
128 @Override |
128 @Override |
129 public abstract boolean isForwardCheckingSupported(); |
129 public abstract boolean isForwardCheckingSupported(); |
130 |
130 |
131 /** |
131 /** |
132 * Returns an immutable <code>Set</code> of X.509 certificate extensions |
132 * Returns an immutable {@code Set} of X.509 certificate extensions |
133 * that this <code>PKIXCertPathChecker</code> supports (i.e. recognizes, is |
133 * that this {@code PKIXCertPathChecker} supports (i.e. recognizes, is |
134 * able to process), or <code>null</code> if no extensions are supported. |
134 * able to process), or {@code null} if no extensions are supported. |
135 * <p> |
135 * <p> |
136 * Each element of the set is a <code>String</code> representing the |
136 * Each element of the set is a {@code String} representing the |
137 * Object Identifier (OID) of the X.509 extension that is supported. |
137 * Object Identifier (OID) of the X.509 extension that is supported. |
138 * The OID is represented by a set of nonnegative integers separated by |
138 * The OID is represented by a set of nonnegative integers separated by |
139 * periods. |
139 * periods. |
140 * <p> |
140 * <p> |
141 * All X.509 certificate extensions that a <code>PKIXCertPathChecker</code> |
141 * All X.509 certificate extensions that a {@code PKIXCertPathChecker} |
142 * might possibly be able to process should be included in the set. |
142 * might possibly be able to process should be included in the set. |
143 * |
143 * |
144 * @return an immutable <code>Set</code> of X.509 extension OIDs (in |
144 * @return an immutable {@code Set} of X.509 extension OIDs (in |
145 * <code>String</code> format) supported by this |
145 * {@code String} format) supported by this |
146 * <code>PKIXCertPathChecker</code>, or <code>null</code> if no |
146 * {@code PKIXCertPathChecker}, or {@code null} if no |
147 * extensions are supported |
147 * extensions are supported |
148 */ |
148 */ |
149 public abstract Set<String> getSupportedExtensions(); |
149 public abstract Set<String> getSupportedExtensions(); |
150 |
150 |
151 /** |
151 /** |
152 * Performs the check(s) on the specified certificate using its internal |
152 * Performs the check(s) on the specified certificate using its internal |
153 * state and removes any critical extensions that it processes from the |
153 * state and removes any critical extensions that it processes from the |
154 * specified collection of OID strings that represent the unresolved |
154 * specified collection of OID strings that represent the unresolved |
155 * critical extensions. The certificates are presented in the order |
155 * critical extensions. The certificates are presented in the order |
156 * specified by the <code>init</code> method. |
156 * specified by the {@code init} method. |
157 * |
157 * |
158 * @param cert the <code>Certificate</code> to be checked |
158 * @param cert the {@code Certificate} to be checked |
159 * @param unresolvedCritExts a <code>Collection</code> of OID strings |
159 * @param unresolvedCritExts a {@code Collection} of OID strings |
160 * representing the current set of unresolved critical extensions |
160 * representing the current set of unresolved critical extensions |
161 * @exception CertPathValidatorException if the specified certificate does |
161 * @exception CertPathValidatorException if the specified certificate does |
162 * not pass the check |
162 * not pass the check |
163 */ |
163 */ |
164 public abstract void check(Certificate cert, |
164 public abstract void check(Certificate cert, |