/*

 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.security.cert;

import java.util.Collection;

import java.util.Set;

/**

 * An abstract class that performs one or more checks on an

 * {@code X509Certificate}.

 *

 * <p>A concrete implementation of the {@code PKIXCertPathChecker} class

 * can be created to extend the PKIX certification path validation algorithm.

 * For example, an implementation may check for and process a critical private

 * extension of each certificate in a certification path.

 *

 * <p>Instances of {@code PKIXCertPathChecker} are passed as parameters

 * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers}

 * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods

 * of the {@code PKIXParameters} and {@code PKIXBuilderParameters}

 * class. Each of the {@code PKIXCertPathChecker}s {@link #check check}

 * methods will be called, in turn, for each certificate processed by a PKIX

 * {@code CertPathValidator} or {@code CertPathBuilder}

 * implementation.

 *

 * <p>A {@code PKIXCertPathChecker} may be called multiple times on

 * successive certificates in a certification path. Concrete subclasses

 * are expected to maintain any internal state that may be necessary to

 * check successive certificates. The {@link #init init} method is used

 * to initialize the internal state of the checker so that the certificates

 * of a new certification path may be checked. A stateful implementation

 * <b>must</b> override the {@link #clone clone} method if necessary in

 * order to allow a PKIX {@code CertPathBuilder} to efficiently

 * backtrack and try other paths. In these situations, the

 * {@code CertPathBuilder} is able to restore prior path validation

 * states by restoring the cloned {@code PKIXCertPathChecker}s.

 *

 * <p>The order in which the certificates are presented to the

 * {@code PKIXCertPathChecker} may be either in the forward direction

 * (from target to most-trusted CA) or in the reverse direction (from

 * most-trusted CA to target). A {@code PKIXCertPathChecker} implementation

 * <b>must</b> support reverse checking (the ability to perform its checks when

 * it is presented with certificates in the reverse direction) and <b>may</b>

 * support forward checking (the ability to perform its checks when it is

 * presented with certificates in the forward direction). The

 * {@link #isForwardCheckingSupported isForwardCheckingSupported} method

 * indicates whether forward checking is supported.

 * <p>

 * Additional input parameters required for executing the check may be

 * specified through constructors of concrete implementations of this class.

 * <p>

 * <b>Concurrent Access</b>

 * <p>

 * Unless otherwise specified, the methods defined in this class are not

 * thread-safe. Multiple threads that need to access a single

 * object concurrently should synchronize amongst themselves and

 * provide the necessary locking. Multiple threads each manipulating

 * separate objects need not synchronize.

 *

 * @see PKIXParameters

 * @see PKIXBuilderParameters

 *

 * @since       1.4

 * @author      Yassir Elley

 * @author      Sean Mullan

 */

public abstract class PKIXCertPathChecker

    implements CertPathChecker, Cloneable {

    /**

     * Default constructor.

     */

    protected PKIXCertPathChecker() {}

    /**

     * Initializes the internal state of this {@code PKIXCertPathChecker}.

     * <p>

     * The {@code forward} flag specifies the order that

     * certificates will be passed to the {@link #check check} method

     * (forward or reverse). A {@code PKIXCertPathChecker} <b>must</b>

     * support reverse checking and <b>may</b> support forward checking.

     *

     * @param forward the order that certificates are presented to

     * the {@code check} method. If {@code true}, certificates

     * are presented from target to most-trusted CA (forward); if

     * {@code false}, from most-trusted CA to target (reverse).

     * @throws CertPathValidatorException if this

     * {@code PKIXCertPathChecker} is unable to check certificates in

     * the specified order; it should never be thrown if the forward flag

     * is false since reverse checking must be supported

     */

    @Override

    public abstract void init(boolean forward)

        throws CertPathValidatorException;

    /**

     * Indicates if forward checking is supported. Forward checking refers

     * to the ability of the {@code PKIXCertPathChecker} to perform

     * its checks when certificates are presented to the {@code check}

     * method in the forward direction (from target to most-trusted CA).

     *

     * @return {@code true} if forward checking is supported,

     * {@code false} otherwise

     */

    @Override

    public abstract boolean isForwardCheckingSupported();

    /**

     * Returns an immutable {@code Set} of X.509 certificate extensions

     * that this {@code PKIXCertPathChecker} supports (i.e. recognizes, is

     * able to process), or {@code null} if no extensions are supported.

     * <p>

     * Each element of the set is a {@code String} representing the

     * Object Identifier (OID) of the X.509 extension that is supported.

     * The OID is represented by a set of nonnegative integers separated by

     * periods.

     * <p>

     * All X.509 certificate extensions that a {@code PKIXCertPathChecker}

     * might possibly be able to process should be included in the set.

     *

     * @return an immutable {@code Set} of X.509 extension OIDs (in

     * {@code String} format) supported by this

     * {@code PKIXCertPathChecker}, or {@code null} if no

     * extensions are supported

     */

    public abstract Set<String> getSupportedExtensions();

    /**

     * Performs the check(s) on the specified certificate using its internal

     * state and removes any critical extensions that it processes from the

     * specified collection of OID strings that represent the unresolved

     * critical extensions. The certificates are presented in the order

     * specified by the {@code init} method.

     *

     * @param cert the {@code Certificate} to be checked

     * @param unresolvedCritExts a {@code Collection} of OID strings

     * representing the current set of unresolved critical extensions

     * @exception CertPathValidatorException if the specified certificate does

     * not pass the check

     */

    public abstract void check(Certificate cert,

            Collection<String> unresolvedCritExts)

            throws CertPathValidatorException;

    /**

     * {@inheritDoc}

     *

     * <p>This implementation calls

     * {@code check(cert, java.util.Collections.<String>emptySet())}.

     */

    @Override

    public void check(Certificate cert) throws CertPathValidatorException {

        check(cert, java.util.Collections.<String>emptySet());

    }

    /**

     * Returns a clone of this object. Calls the {@code Object.clone()}

     * method.

     * All subclasses which maintain state must support and

     * override this method, if necessary.

     *

     * @return a copy of this {@code PKIXCertPathChecker}

     */

    @Override

    public Object clone() {

        try {

            return super.clone();

        } catch (CloneNotSupportedException e) {

            /* Cannot happen */

            throw new InternalError(e.toString(), e);

        }

    }

}