1 /*
   2  * Copyright (c) 2000, 2016, 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.security.AccessController;
  29 import java.security.InvalidAlgorithmParameterException;
  30 import java.security.NoSuchAlgorithmException;
  31 import java.security.NoSuchProviderException;
  32 import java.security.PrivilegedAction;
  33 import java.security.Provider;
  34 import java.security.Security;
  35 import sun.security.util.Debug;
  36 
  37 import sun.security.jca.*;
  38 import sun.security.jca.GetInstance.Instance;
  39 
  40 /**
  41  * A class for validating certification paths (also known as certificate
  42  * chains).
  43  * <p>
  44  * This class uses a provider-based architecture.
  45  * To create a {@code CertPathValidator},
  46  * call one of the static {@code getInstance} methods, passing in the
  47  * algorithm name of the {@code CertPathValidator} desired and
  48  * optionally the name of the provider desired.
  49  *
  50  * <p>Once a {@code CertPathValidator} object has been created, it can
  51  * be used to validate certification paths by calling the {@link #validate
  52  * validate} method and passing it the {@code CertPath} to be validated
  53  * and an algorithm-specific set of parameters. If successful, the result is
  54  * returned in an object that implements the
  55  * {@code CertPathValidatorResult} interface.
  56  *
  57  * <p>The {@link #getRevocationChecker} method allows an application to specify
  58  * additional algorithm-specific parameters and options used by the
  59  * {@code CertPathValidator} when checking the revocation status of
  60  * certificates. Here is an example demonstrating how it is used with the PKIX
  61  * algorithm:
  62  *
  63  * <pre>
  64  * CertPathValidator cpv = CertPathValidator.getInstance("PKIX");
  65  * PKIXRevocationChecker rc = (PKIXRevocationChecker)cpv.getRevocationChecker();
  66  * rc.setOptions(EnumSet.of(Option.SOFT_FAIL));
  67  * params.addCertPathChecker(rc);
  68  * CertPathValidatorResult cpvr = cpv.validate(path, params);
  69  * </pre>
  70  *
  71  * <p>Every implementation of the Java platform is required to support the
  72  * following standard {@code CertPathValidator} algorithm:
  73  * <ul>
  74  * <li>{@code PKIX}</li>
  75  * </ul>
  76  * This algorithm is described in the <a href=
  77  * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathValidator">
  78  * CertPathValidator section</a> of the
  79  * Java Cryptography Architecture Standard Algorithm Name Documentation.
  80  * Consult the release documentation for your implementation to see if any
  81  * other algorithms are supported.
  82  *
  83  * <p>
  84  * <b>Concurrent Access</b>
  85  * <p>
  86  * The static methods of this class are guaranteed to be thread-safe.
  87  * Multiple threads may concurrently invoke the static methods defined in
  88  * this class with no ill effects.
  89  * <p>
  90  * However, this is not true for the non-static methods defined by this class.
  91  * Unless otherwise documented by a specific provider, threads that need to
  92  * access a single {@code CertPathValidator} instance concurrently should
  93  * synchronize amongst themselves and provide the necessary locking. Multiple
  94  * threads each manipulating a different {@code CertPathValidator}
  95  * instance need not synchronize.
  96  *
  97  * @see CertPath
  98  *
  99  * @since       1.4
 100  * @author      Yassir Elley
 101  */
 102 public class CertPathValidator {
 103 
 104     /*
 105      * Constant to lookup in the Security properties file to determine
 106      * the default certpathvalidator type. In the Security properties file,
 107      * the default certpathvalidator type is given as:
 108      * <pre>
 109      * certpathvalidator.type=PKIX
 110      * </pre>
 111      */
 112     private static final String CPV_TYPE = "certpathvalidator.type";
 113     private final CertPathValidatorSpi validatorSpi;
 114     private final Provider provider;
 115     private final String algorithm;
 116 
 117     /**
 118      * Creates a {@code CertPathValidator} object of the given algorithm,
 119      * and encapsulates the given provider implementation (SPI object) in it.
 120      *
 121      * @param validatorSpi the provider implementation
 122      * @param provider the provider
 123      * @param algorithm the algorithm name
 124      */
 125     protected CertPathValidator(CertPathValidatorSpi validatorSpi,
 126         Provider provider, String algorithm)
 127     {
 128         this.validatorSpi = validatorSpi;
 129         this.provider = provider;
 130         this.algorithm = algorithm;
 131     }
 132 
 133     /**
 134      * Returns a {@code CertPathValidator} object that implements the
 135      * specified algorithm.
 136      *
 137      * <p> This method traverses the list of registered security Providers,
 138      * starting with the most preferred Provider.
 139      * A new CertPathValidator object encapsulating the
 140      * CertPathValidatorSpi implementation from the first
 141      * Provider that supports the specified algorithm is returned.
 142      *
 143      * <p> Note that the list of registered providers may be retrieved via
 144      * the {@link Security#getProviders() Security.getProviders()} method.
 145      *
 146      * @implNote
 147      * The JDK Reference Implementation additionally uses the
 148      * {@code jdk.security.provider.preferred}
 149      * {@link Security#getProperty(String) Security} property to determine
 150      * the preferred provider order for the specified algorithm. This
 151      * may be different than the order of providers returned by
 152      * {@link Security#getProviders() Security.getProviders()}.
 153      *
 154      * @param algorithm the name of the requested {@code CertPathValidator}
 155      *  algorithm. See the CertPathValidator section in the <a href=
 156      *  "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathValidator">
 157      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 158      * for information about standard algorithm names.
 159      *
 160      * @return a {@code CertPathValidator} object that implements the
 161      *          specified algorithm.
 162      *
 163      * @exception NoSuchAlgorithmException if no Provider supports a
 164      *          CertPathValidatorSpi implementation for the
 165      *          specified algorithm.
 166      *
 167      * @see java.security.Provider
 168      */
 169     public static CertPathValidator getInstance(String algorithm)
 170             throws NoSuchAlgorithmException {
 171         Instance instance = GetInstance.getInstance("CertPathValidator",
 172             CertPathValidatorSpi.class, algorithm);
 173         return new CertPathValidator((CertPathValidatorSpi)instance.impl,
 174             instance.provider, algorithm);
 175     }
 176 
 177     /**
 178      * Returns a {@code CertPathValidator} object that implements the
 179      * specified algorithm.
 180      *
 181      * <p> A new CertPathValidator object encapsulating the
 182      * CertPathValidatorSpi implementation from the specified provider
 183      * is returned.  The specified provider must be registered
 184      * in the security provider list.
 185      *
 186      * <p> Note that the list of registered providers may be retrieved via
 187      * the {@link Security#getProviders() Security.getProviders()} method.
 188      *
 189      * @param algorithm the name of the requested {@code CertPathValidator}
 190      *  algorithm. See the CertPathValidator section in the <a href=
 191      *  "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathValidator">
 192      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 193      * for information about standard algorithm names.
 194      *
 195      * @param provider the name of the provider.
 196      *
 197      * @return a {@code CertPathValidator} object that implements the
 198      *          specified algorithm.
 199      *
 200      * @exception NoSuchAlgorithmException if a CertPathValidatorSpi
 201      *          implementation for the specified algorithm is not
 202      *          available from the specified provider.
 203      *
 204      * @exception NoSuchProviderException if the specified provider is not
 205      *          registered in the security provider list.
 206      *
 207      * @exception IllegalArgumentException if the {@code provider} is
 208      *          null or empty.
 209      *
 210      * @see java.security.Provider
 211      */
 212     public static CertPathValidator getInstance(String algorithm,
 213             String provider) throws NoSuchAlgorithmException,
 214             NoSuchProviderException {
 215         Instance instance = GetInstance.getInstance("CertPathValidator",
 216             CertPathValidatorSpi.class, algorithm, provider);
 217         return new CertPathValidator((CertPathValidatorSpi)instance.impl,
 218             instance.provider, algorithm);
 219     }
 220 
 221     /**
 222      * Returns a {@code CertPathValidator} object that implements the
 223      * specified algorithm.
 224      *
 225      * <p> A new CertPathValidator object encapsulating the
 226      * CertPathValidatorSpi implementation from the specified Provider
 227      * object is returned.  Note that the specified Provider object
 228      * does not have to be registered in the provider list.
 229      *
 230      * @param algorithm the name of the requested {@code CertPathValidator}
 231      * algorithm. See the CertPathValidator section in the <a href=
 232      * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathValidator">
 233      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 234      * for information about standard algorithm names.
 235      *
 236      * @param provider the provider.
 237      *
 238      * @return a {@code CertPathValidator} object that implements the
 239      *          specified algorithm.
 240      *
 241      * @exception NoSuchAlgorithmException if a CertPathValidatorSpi
 242      *          implementation for the specified algorithm is not available
 243      *          from the specified Provider object.
 244      *
 245      * @exception IllegalArgumentException if the {@code provider} is
 246      *          null.
 247      *
 248      * @see java.security.Provider
 249      */
 250     public static CertPathValidator getInstance(String algorithm,
 251             Provider provider) throws NoSuchAlgorithmException {
 252         Instance instance = GetInstance.getInstance("CertPathValidator",
 253             CertPathValidatorSpi.class, algorithm, provider);
 254         return new CertPathValidator((CertPathValidatorSpi)instance.impl,
 255             instance.provider, algorithm);
 256     }
 257 
 258     /**
 259      * Returns the {@code Provider} of this
 260      * {@code CertPathValidator}.
 261      *
 262      * @return the {@code Provider} of this {@code CertPathValidator}
 263      */
 264     public final Provider getProvider() {
 265         return this.provider;
 266     }
 267 
 268     /**
 269      * Returns the algorithm name of this {@code CertPathValidator}.
 270      *
 271      * @return the algorithm name of this {@code CertPathValidator}
 272      */
 273     public final String getAlgorithm() {
 274         return this.algorithm;
 275     }
 276 
 277     /**
 278      * Validates the specified certification path using the specified
 279      * algorithm parameter set.
 280      * <p>
 281      * The {@code CertPath} specified must be of a type that is
 282      * supported by the validation algorithm, otherwise an
 283      * {@code InvalidAlgorithmParameterException} will be thrown. For
 284      * example, a {@code CertPathValidator} that implements the PKIX
 285      * algorithm validates {@code CertPath} objects of type X.509.
 286      *
 287      * @param certPath the {@code CertPath} to be validated
 288      * @param params the algorithm parameters
 289      * @return the result of the validation algorithm
 290      * @exception CertPathValidatorException if the {@code CertPath}
 291      * does not validate
 292      * @exception InvalidAlgorithmParameterException if the specified
 293      * parameters or the type of the specified {@code CertPath} are
 294      * inappropriate for this {@code CertPathValidator}
 295      */
 296     public final CertPathValidatorResult validate(CertPath certPath,
 297         CertPathParameters params)
 298         throws CertPathValidatorException, InvalidAlgorithmParameterException
 299     {
 300         return validatorSpi.engineValidate(certPath, params);
 301     }
 302 
 303     /**
 304      * Returns the default {@code CertPathValidator} type as specified by
 305      * the {@code certpathvalidator.type} security property, or the string
 306      * {@literal "PKIX"} if no such property exists.
 307      *
 308      * <p>The default {@code CertPathValidator} type can be used by
 309      * applications that do not want to use a hard-coded type when calling one
 310      * of the {@code getInstance} methods, and want to provide a default
 311      * type in case a user does not specify its own.
 312      *
 313      * <p>The default {@code CertPathValidator} type can be changed by
 314      * setting the value of the {@code certpathvalidator.type} security
 315      * property to the desired type.
 316      *
 317      * @see java.security.Security security properties
 318      * @return the default {@code CertPathValidator} type as specified
 319      * by the {@code certpathvalidator.type} security property, or the string
 320      * {@literal "PKIX"} if no such property exists.
 321      */
 322     public static final String getDefaultType() {
 323         String cpvtype =
 324             AccessController.doPrivileged(new PrivilegedAction<>() {
 325                 public String run() {
 326                     return Security.getProperty(CPV_TYPE);
 327                 }
 328             });
 329         return (cpvtype == null) ? "PKIX" : cpvtype;
 330     }
 331 
 332     /**
 333      * Returns a {@code CertPathChecker} that the encapsulated
 334      * {@code CertPathValidatorSpi} implementation uses to check the revocation
 335      * status of certificates. A PKIX implementation returns objects of
 336      * type {@code PKIXRevocationChecker}. Each invocation of this method
 337      * returns a new instance of {@code CertPathChecker}.
 338      *
 339      * <p>The primary purpose of this method is to allow callers to specify
 340      * additional input parameters and options specific to revocation checking.
 341      * See the class description for an example.
 342      *
 343      * @return a {@code CertPathChecker}
 344      * @throws UnsupportedOperationException if the service provider does not
 345      *         support this method
 346      * @since 1.8
 347      */
 348     public final CertPathChecker getRevocationChecker() {
 349         return validatorSpi.engineGetRevocationChecker();
 350     }
 351 }