001 /*
002 * Copyright 2000-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.security.cert;
027
028 import java.util.Collection;
029 import java.util.Set;
030
031 /**
032 * An abstract class that performs one or more checks on an
033 * <code>X509Certificate</code>.
034 *
035 * <p>A concrete implementation of the <code>PKIXCertPathChecker</code> class
036 * can be created to extend the PKIX certification path validation algorithm.
037 * For example, an implementation may check for and process a critical private
038 * extension of each certificate in a certification path.
039 *
040 * <p>Instances of <code>PKIXCertPathChecker</code> are passed as parameters
041 * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers}
042 * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods
043 * of the <code>PKIXParameters</code> and <code>PKIXBuilderParameters</code>
044 * class. Each of the <code>PKIXCertPathChecker</code>s {@link #check check}
045 * methods will be called, in turn, for each certificate processed by a PKIX
046 * <code>CertPathValidator</code> or <code>CertPathBuilder</code>
047 * implementation.
048 *
049 * <p>A <code>PKIXCertPathChecker</code> may be called multiple times on
050 * successive certificates in a certification path. Concrete subclasses
051 * are expected to maintain any internal state that may be necessary to
052 * check successive certificates. The {@link #init init} method is used
053 * to initialize the internal state of the checker so that the certificates
054 * of a new certification path may be checked. A stateful implementation
055 * <b>must</b> override the {@link #clone clone} method if necessary in
056 * order to allow a PKIX <code>CertPathBuilder</code> to efficiently
057 * backtrack and try other paths. In these situations, the
058 * <code>CertPathBuilder</code> is able to restore prior path validation
059 * states by restoring the cloned <code>PKIXCertPathChecker</code>s.
060 *
061 * <p>The order in which the certificates are presented to the
062 * <code>PKIXCertPathChecker</code> may be either in the forward direction
063 * (from target to most-trusted CA) or in the reverse direction (from
064 * most-trusted CA to target). A <code>PKIXCertPathChecker</code> implementation
065 * <b>must</b> support reverse checking (the ability to perform its checks when
066 * it is presented with certificates in the reverse direction) and <b>may</b>
067 * support forward checking (the ability to perform its checks when it is
068 * presented with certificates in the forward direction). The
069 * {@link #isForwardCheckingSupported isForwardCheckingSupported} method
070 * indicates whether forward checking is supported.
071 * <p>
072 * Additional input parameters required for executing the check may be
073 * specified through constructors of concrete implementations of this class.
074 * <p>
075 * <b>Concurrent Access</b>
076 * <p>
077 * Unless otherwise specified, the methods defined in this class are not
078 * thread-safe. Multiple threads that need to access a single
079 * object concurrently should synchronize amongst themselves and
080 * provide the necessary locking. Multiple threads each manipulating
081 * separate objects need not synchronize.
082 *
083 * @see PKIXParameters
084 * @see PKIXBuilderParameters
085 *
086 * @version 1.14 05/05/07
087 * @since 1.4
088 * @author Yassir Elley
089 * @author Sean Mullan
090 */
091 public abstract class PKIXCertPathChecker implements Cloneable {
092
093 /**
094 * Default constructor.
095 */
096 protected PKIXCertPathChecker() {
097 }
098
099 /**
100 * Initializes the internal state of this <code>PKIXCertPathChecker</code>.
101 * <p>
102 * The <code>forward</code> flag specifies the order that
103 * certificates will be passed to the {@link #check check} method
104 * (forward or reverse). A <code>PKIXCertPathChecker</code> <b>must</b>
105 * support reverse checking and <b>may</b> support forward checking.
106 *
107 * @param forward the order that certificates are presented to
108 * the <code>check</code> method. If <code>true</code>, certificates
109 * are presented from target to most-trusted CA (forward); if
110 * <code>false</code>, from most-trusted CA to target (reverse).
111 * @throws CertPathValidatorException if this
112 * <code>PKIXCertPathChecker</code> is unable to check certificates in
113 * the specified order; it should never be thrown if the forward flag
114 * is false since reverse checking must be supported
115 */
116 public abstract void init(boolean forward)
117 throws CertPathValidatorException;
118
119 /**
120 * Indicates if forward checking is supported. Forward checking refers
121 * to the ability of the <code>PKIXCertPathChecker</code> to perform
122 * its checks when certificates are presented to the <code>check</code>
123 * method in the forward direction (from target to most-trusted CA).
124 *
125 * @return <code>true</code> if forward checking is supported,
126 * <code>false</code> otherwise
127 */
128 public abstract boolean isForwardCheckingSupported();
129
130 /**
131 * Returns an immutable <code>Set</code> of X.509 certificate extensions
132 * that this <code>PKIXCertPathChecker</code> supports (i.e. recognizes, is
133 * able to process), or <code>null</code> if no extensions are supported.
134 * <p>
135 * Each element of the set is a <code>String</code> representing the
136 * Object Identifier (OID) of the X.509 extension that is supported.
137 * The OID is represented by a set of nonnegative integers separated by
138 * periods.
139 * <p>
140 * All X.509 certificate extensions that a <code>PKIXCertPathChecker</code>
141 * might possibly be able to process should be included in the set.
142 *
143 * @return an immutable <code>Set</code> of X.509 extension OIDs (in
144 * <code>String</code> format) supported by this
145 * <code>PKIXCertPathChecker</code>, or <code>null</code> if no
146 * extensions are supported
147 */
148 public abstract Set<String> getSupportedExtensions();
149
150 /**
151 * Performs the check(s) on the specified certificate using its internal
152 * state and removes any critical extensions that it processes from the
153 * specified collection of OID strings that represent the unresolved
154 * critical extensions. The certificates are presented in the order
155 * specified by the <code>init</code> method.
156 *
157 * @param cert the <code>Certificate</code> to be checked
158 * @param unresolvedCritExts a <code>Collection</code> of OID strings
159 * representing the current set of unresolved critical extensions
160 * @exception CertPathValidatorException if the specified certificate does
161 * not pass the check
162 */
163 public abstract void check(Certificate cert,
164 Collection<String> unresolvedCritExts)
165 throws CertPathValidatorException;
166
167 /**
168 * Returns a clone of this object. Calls the <code>Object.clone()</code>
169 * method.
170 * All subclasses which maintain state must support and
171 * override this method, if necessary.
172 *
173 * @return a copy of this <code>PKIXCertPathChecker</code>
174 */
175 public Object clone() {
176 try {
177 return super .clone();
178 } catch (CloneNotSupportedException e) {
179 /* Cannot happen */
180 throw new InternalError(e.toString());
181 }
182 }
183 }
|