1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.security.cert;
19
20import java.util.Collection;
21import java.util.Set;
22
23/**
24 * The class specifying the interface to extend the certification path
25 * validation algorithm by checks to perform on an {@code X509Certificate}.
26 * <p>
27 * The checks are added to a certification path validation using the
28 * {@link PKIXParameters#setCertPathCheckers(java.util.List)
29 * setCertPathCheckers} or
30 * {@link PKIXBuilderParameters#addCertPathChecker(PKIXCertPathChecker)
31 * addCertPathChecker} of the {@code PKIXParameters} and {@code
32 * PKIXBuilderParameters} class respectively. The
33 * {@link #check(Certificate, Collection) check} method will be called for each
34 * certificate processed by a {@code CertPathBuilder} of {@code
35 * CertPathValidator}.
36 * <p>
37 * A {@code PKIXCertPathChecker} implementation <u>must</u> support reverse
38 * checking (from trusted CA to target) and <u>may</u> support forward checking
39 * (from target to trusted CA). The return value of {@code
40 * isForwardCheckingSupported} indicates whether forward checking is supported.
41 */
42public abstract class PKIXCertPathChecker implements Cloneable {
43
44    /**
45     * Creates a new {@code PKIXCertPathChecker} instance.
46     */
47    protected PKIXCertPathChecker() {}
48
49    /**
50     * Clones this {@code PKIXCertPathChecker} instance.
51     *
52     * @return the cloned instance.
53     */
54    public Object clone() {
55        try {
56            return super.clone();
57        } catch (CloneNotSupportedException e) {
58            throw new AssertionError(e);
59        }
60    }
61
62    /**
63     * Initializes this {@code PKIXCertPathChecker} instance for specified
64     * <i>checking direction</i>.
65     *
66     * @param forward
67     *            the direction of the certification path processing, {@code
68     *            true} if the certificates are processed in forward direction
69     *            (from target to trusted CA), {@code false} if processed in
70     *            reverse direction (from trusted CA to target).
71     * @throws CertPathValidatorException
72     *             if initialization of this {@code PKIXCertPathChecker}
73     *             instance fails, or if it cannot process certificates in the
74     *             specified order.
75     */
76    public abstract void init(boolean forward)
77        throws CertPathValidatorException;
78
79    /**
80     * Returns whether this {@code PKIXCertPathChecker} instance supports
81     * <i>forward checking</i>.
82     *
83     * @return {@code true} if this {@code PKIXCertPathChecker} instance
84     *         supports forward checking, otherwise {@code false}.
85     */
86    public abstract boolean isForwardCheckingSupported();
87
88    /**
89     * Returns the list of extensions of X.509 certificates that this {@code
90     * PKIXCertPathChecker} is able to process.
91     *
92     * @return the list of extensions of X.509 certificates that this {@code
93     *         PKIXCertPathChecker} is able to process, or {@code null} if there
94     *         are none.
95     */
96    public abstract Set<String> getSupportedExtensions();
97
98    /**
99     * Checks the specified certificate and removes the processed critical
100     * extensions from the specified list of X.509 extension <i>OID</i>s.
101     *
102     * @param cert
103     *            the certificate.
104     * @param unresolvedCritExts
105     *            the list of critical X.509 extension OID strings.
106     * @throws CertPathValidatorException
107     *             if check(s) fail on the specified certificate.
108     */
109    public abstract void check(Certificate cert, Collection<String> unresolvedCritExts)
110        throws CertPathValidatorException;
111}
112