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
26package java.security.cert;
27
28import java.util.Collection;
29import 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 */
90public abstract class PKIXCertPathChecker
91    implements CertPathChecker, Cloneable {
92
93    /**
94     * Default constructor.
95     */
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
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
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     */
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     */
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
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
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