Java tutorial
/* * 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); } } }