1 /*
2  * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package java.security.cert;
27 
28 import java.util.Collection;
29 import java.util.Set;
30 
31 /**
32  * An abstract class that performs one or more checks on an
33  * {@code X509Certificate}.
34  *
35  * <p>A concrete implementation of the {@code PKIXCertPathChecker} class
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
38  * extension of each certificate in a certification path.
39  *
40  * <p>Instances of {@code PKIXCertPathChecker} are passed as parameters
41  * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers}
42  * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods
43  * of the {@code PKIXParameters} and {@code PKIXBuilderParameters}
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
46  * {@code CertPathValidator} or {@code CertPathBuilder}
47  * implementation.
48  *
49  * <p>A {@code PKIXCertPathChecker} may be called multiple times on
50  * successive certificates in a certification path. Concrete subclasses
51  * are expected to maintain any internal state that may be necessary to
52  * check successive certificates. The {@link #init init} method is used
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
55  * <b>must</b> override the {@link #clone clone} method if necessary in
56  * order to allow a PKIX {@code CertPathBuilder} to efficiently
57  * backtrack and try other paths. In these situations, the
58  * {@code CertPathBuilder} is able to restore prior path validation
59  * states by restoring the cloned {@code PKIXCertPathChecker}s.
60  *
61  * <p>The order in which the certificates are presented to the
62  * {@code PKIXCertPathChecker} may be either in the forward direction
63  * (from target to most-trusted CA) or in the reverse direction (from
64  * most-trusted CA to target). A {@code PKIXCertPathChecker} implementation
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>
67  * support forward checking (the ability to perform its checks when it is
68  * presented with certificates in the forward direction). The
69  * {@link #isForwardCheckingSupported isForwardCheckingSupported} method
70  * indicates whether forward checking is supported.
71  * <p>
72  * Additional input parameters required for executing the check may be
73  * specified through constructors of concrete implementations of this class.
74  * <p>
75  * <b>Concurrent Access</b>
76  * <p>
77  * Unless otherwise specified, the methods defined in this class are not
78  * thread-safe. Multiple threads that need to access a single
79  * object concurrently should synchronize amongst themselves and
80  * provide the necessary locking. Multiple threads each manipulating
81  * separate objects need not synchronize.
82  *
83  * @see PKIXParameters
84  * @see PKIXBuilderParameters
85  *
86  * @since       1.4
87  * @author      Yassir Elley
88  * @author      Sean Mullan
89  */
90 public abstract class PKIXCertPathChecker
91     implements CertPathChecker, Cloneable {
92 
93     /**
94      * Default constructor.
95      */
PKIXCertPathChecker()96     protected PKIXCertPathChecker() {}
97 
98     /**
99      * Initializes the internal state of this {@code PKIXCertPathChecker}.
100      * <p>
101      * The {@code forward} flag specifies the order that
102      * certificates will be passed to the {@link #check check} method
103      * (forward or reverse). A {@code PKIXCertPathChecker} <b>must</b>
104      * support reverse checking and <b>may</b> support forward checking.
105      *
106      * @param forward the order that certificates are presented to
107      * the {@code check} method. If {@code true}, certificates
108      * are presented from target to most-trusted CA (forward); if
109      * {@code false}, from most-trusted CA to target (reverse).
110      * @throws CertPathValidatorException if this
111      * {@code PKIXCertPathChecker} is unable to check certificates in
112      * the specified order; it should never be thrown if the forward flag
113      * is false since reverse checking must be supported
114      */
115     @Override
init(boolean forward)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} to perform
122      * its checks when certificates are presented to the {@code check}
123      * method in the forward direction (from target to most-trusted CA).
124      *
125      * @return {@code true} if forward checking is supported,
126      * {@code false} otherwise
127      */
128     @Override
isForwardCheckingSupported()129     public abstract boolean isForwardCheckingSupported();
130 
131     /**
132      * Returns an immutable {@code Set} of X.509 certificate extensions
133      * that this {@code PKIXCertPathChecker} supports (i.e. recognizes, is
134      * able to process), or {@code null} if no extensions are supported.
135      * <p>
136      * Each element of the set is a {@code String} representing the
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
139      * periods.
140      * <p>
141      * All X.509 certificate extensions that a {@code PKIXCertPathChecker}
142      * might possibly be able to process should be included in the set.
143      *
144      * @return an immutable {@code Set} of X.509 extension OIDs (in
145      * {@code String} format) supported by this
146      * {@code PKIXCertPathChecker}, or {@code null} if no
147      * extensions are supported
148      */
getSupportedExtensions()149     public abstract Set<String> getSupportedExtensions();
150 
151     /**
152      * Performs the check(s) on the specified certificate using its internal
153      * state and removes any critical extensions that it processes from the
154      * specified collection of OID strings that represent the unresolved
155      * critical extensions. The certificates are presented in the order
156      * specified by the {@code init} method.
157      *
158      * @param cert the {@code Certificate} to be checked
159      * @param unresolvedCritExts a {@code Collection} of OID strings
160      * representing the current set of unresolved critical extensions
161      * @exception CertPathValidatorException if the specified certificate does
162      * not pass the check
163      */
check(Certificate cert, Collection<String> unresolvedCritExts)164     public abstract void check(Certificate cert,
165             Collection<String> unresolvedCritExts)
166             throws CertPathValidatorException;
167 
168     /**
169      * {@inheritDoc}
170      *
171      * <p>This implementation calls
172      * {@code check(cert, java.util.Collections.<String>emptySet())}.
173      */
174     @Override
check(Certificate cert)175     public void check(Certificate cert) throws CertPathValidatorException {
176         check(cert, java.util.Collections.<String>emptySet());
177     }
178 
179     /**
180      * Returns a clone of this object. Calls the {@code Object.clone()}
181      * method.
182      * All subclasses which maintain state must support and
183      * override this method, if necessary.
184      *
185      * @return a copy of this {@code PKIXCertPathChecker}
186      */
187     @Override
clone()188     public Object clone() {
189         try {
190             return super.clone();
191         } catch (CloneNotSupportedException e) {
192             /* Cannot happen */
193             throw new InternalError(e.toString(), e);
194         }
195     }
196 }
197