1 /* 2 * Copyright (c) 2002, 2010, 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 sun.security.validator; 27 28 import java.util.*; 29 30 import java.security.AlgorithmConstraints; 31 import java.security.KeyStore; 32 import java.security.cert.*; 33 34 /** 35 * Validator abstract base class. Concrete classes are instantiated by calling 36 * one of the getInstance() methods. All methods defined in this class 37 * must be safe for concurrent use by multiple threads.<p> 38 * 39 * The model is that a Validator instance is created specifying validation 40 * settings, such as trust anchors or PKIX parameters. Then one or more 41 * paths are validated using those parameters. In some cases, additional 42 * information can be provided per path validation. This is independent of 43 * the validation parameters and currently only used for TLS server validation. 44 * <p> 45 * Path validation is performed by calling one of the validate() methods. It 46 * specifies a suggested path to be used for validation if available, or only 47 * the end entity certificate otherwise. Optionally additional certificates can 48 * be specified that the caller believes could be helpful. Implementations are 49 * free to make use of this information or validate the path using other means. 50 * validate() also checks that the end entity certificate is suitable for the 51 * intended purpose as described below. 52 * 53 * <p>There are two orthogonal parameters to select the Validator 54 * implementation: type and variant. Type selects the validation algorithm. 55 * Currently supported are TYPE_SIMPLE and TYPE_PKIX. See SimpleValidator and 56 * PKIXValidator for details. 57 * <p> 58 * Variant controls additional extension checks. Currently supported are 59 * five variants: 60 * <ul> 61 * <li>VAR_GENERIC (no additional checks), 62 * <li>VAR_TLS_CLIENT (TLS client specific checks) 63 * <li>VAR_TLS_SERVER (TLS server specific checks), and 64 * <li>VAR_CODE_SIGNING (code signing specific checks). 65 * <li>VAR_JCE_SIGNING (JCE code signing specific checks). 66 * <li>VAR_TSA_SERVER (TSA server specific checks). 67 * <li>VAR_PLUGIN_CODE_SIGNING (Plugin/WebStart code signing specific checks). 68 * </ul> 69 * See EndEntityChecker for more information. 70 * <p> 71 * Examples: 72 * <pre> 73 * // instantiate validator specifying type, variant, and trust anchors 74 * Validator validator = Validator.getInstance(Validator.TYPE_PKIX, 75 * Validator.VAR_TLS_CLIENT, 76 * trustedCerts); 77 * // validate one or more chains using the validator 78 * validator.validate(chain); // throws CertificateException if failed 79 * </pre> 80 * 81 * @see SimpleValidator 82 * @see PKIXValidator 83 * @see EndEntityChecker 84 * 85 * @author Andreas Sterbenz 86 */ 87 public abstract class Validator { 88 89 final static X509Certificate[] CHAIN0 = {}; 90 91 /** 92 * Constant for a validator of type Simple. 93 * @see #getInstance 94 */ 95 public final static String TYPE_SIMPLE = "Simple"; 96 97 /** 98 * Constant for a validator of type PKIX. 99 * @see #getInstance 100 */ 101 public final static String TYPE_PKIX = "PKIX"; 102 103 /** 104 * Constant for a Generic variant of a validator. 105 * @see #getInstance 106 */ 107 public final static String VAR_GENERIC = "generic"; 108 109 /** 110 * Constant for a Code Signing variant of a validator. 111 * @see #getInstance 112 */ 113 public final static String VAR_CODE_SIGNING = "code signing"; 114 115 /** 116 * Constant for a JCE Code Signing variant of a validator. 117 * @see #getInstance 118 */ 119 public final static String VAR_JCE_SIGNING = "jce signing"; 120 121 /** 122 * Constant for a TLS Client variant of a validator. 123 * @see #getInstance 124 */ 125 public final static String VAR_TLS_CLIENT = "tls client"; 126 127 /** 128 * Constant for a TLS Server variant of a validator. 129 * @see #getInstance 130 */ 131 public final static String VAR_TLS_SERVER = "tls server"; 132 133 /** 134 * Constant for a TSA Server variant of a validator. 135 * @see #getInstance 136 */ 137 public final static String VAR_TSA_SERVER = "tsa server"; 138 139 /** 140 * Constant for a Code Signing variant of a validator for use by 141 * the J2SE Plugin/WebStart code. 142 * @see #getInstance 143 */ 144 public final static String VAR_PLUGIN_CODE_SIGNING = "plugin code signing"; 145 146 final EndEntityChecker endEntityChecker; 147 final String variant; 148 149 /** 150 * @deprecated 151 * @see #setValidationDate 152 */ 153 @Deprecated 154 volatile Date validationDate; 155 156 Validator(String type, String variant) { 157 this.variant = variant; 158 endEntityChecker = EndEntityChecker.getInstance(type, variant); 159 } 160 161 /** 162 * Get a new Validator instance using the trusted certificates from the 163 * specified KeyStore as trust anchors. 164 */ 165 public static Validator getInstance(String type, String variant, 166 KeyStore ks) { 167 return getInstance(type, variant, KeyStores.getTrustedCerts(ks)); 168 } 169 170 /** 171 * Get a new Validator instance using the Set of X509Certificates as trust 172 * anchors. 173 */ 174 public static Validator getInstance(String type, String variant, 175 Collection<X509Certificate> trustedCerts) { 176 if (type.equals(TYPE_SIMPLE)) { 177 return new SimpleValidator(variant, trustedCerts); 178 } else if (type.equals(TYPE_PKIX)) { 179 return new PKIXValidator(variant, trustedCerts); 180 } else { 181 throw new IllegalArgumentException 182 ("Unknown validator type: " + type); 183 } 184 } 185 186 /** 187 * Get a new Validator instance using the provided PKIXBuilderParameters. 188 * This method can only be used with the PKIX validator. 189 */ 190 public static Validator getInstance(String type, String variant, 191 PKIXBuilderParameters params) { 192 if (type.equals(TYPE_PKIX) == false) { 193 throw new IllegalArgumentException 194 ("getInstance(PKIXBuilderParameters) can only be used " 195 + "with PKIX validator"); 196 } 197 return new PKIXValidator(variant, params); 198 } 199 200 /** 201 * Validate the given certificate chain. 202 */ 203 public final X509Certificate[] validate(X509Certificate[] chain) 204 throws CertificateException { 205 return validate(chain, null, null); 206 } 207 208 /** 209 * Validate the given certificate chain. If otherCerts is non-null, it is 210 * a Collection of additional X509Certificates that could be helpful for 211 * path building. 212 */ 213 public final X509Certificate[] validate(X509Certificate[] chain, 214 Collection<X509Certificate> otherCerts) throws CertificateException { 215 return validate(chain, otherCerts, null); 216 } 217 218 /** 219 * Validate the given certificate chain. If otherCerts is non-null, it is 220 * a Collection of additional X509Certificates that could be helpful for 221 * path building. 222 * <p> 223 * Parameter is an additional parameter with variant specific meaning. 224 * Currently, it is only defined for TLS_SERVER variant validators, where 225 * it must be non null and the name of the TLS key exchange algorithm being 226 * used (see JSSE X509TrustManager specification). In the future, it 227 * could be used to pass in a PKCS#7 object for code signing to check time 228 * stamps. 229 * <p> 230 * @return a non-empty chain that was used to validate the path. The 231 * end entity cert is at index 0, the trust anchor at index n-1. 232 */ 233 public final X509Certificate[] validate(X509Certificate[] chain, 234 Collection<X509Certificate> otherCerts, Object parameter) 235 throws CertificateException { 236 return validate(chain, otherCerts, null, parameter); 237 } 238 239 /** 240 * Validate the given certificate chain. 241 * 242 * @param chain the target certificate chain 243 * @param otherCerts a Collection of additional X509Certificates that 244 * could be helpful for path building (or null) 245 * @param constraints algorithm constraints for certification path 246 * processing 247 * @param parameter an additional parameter with variant specific meaning. 248 * Currently, it is only defined for TLS_SERVER variant validators, 249 * where it must be non null and the name of the TLS key exchange 250 * algorithm being used (see JSSE X509TrustManager specification). 251 * In the future, it could be used to pass in a PKCS#7 object for 252 * code signing to check time stamps. 253 * @return a non-empty chain that was used to validate the path. The 254 * end entity cert is at index 0, the trust anchor at index n-1. 255 */ 256 public final X509Certificate[] validate(X509Certificate[] chain, 257 Collection<X509Certificate> otherCerts, 258 AlgorithmConstraints constraints, 259 Object parameter) throws CertificateException { 260 chain = engineValidate(chain, otherCerts, constraints, parameter); 261 262 // omit EE extension check if EE cert is also trust anchor 263 if (chain.length > 1) { 264 endEntityChecker.check(chain[0], parameter); 265 } 266 267 return chain; 268 } 269 270 abstract X509Certificate[] engineValidate(X509Certificate[] chain, 271 Collection<X509Certificate> otherCerts, 272 AlgorithmConstraints constraints, 273 Object parameter) throws CertificateException; 274 275 /** 276 * Returns an immutable Collection of the X509Certificates this instance 277 * uses as trust anchors. 278 */ 279 public abstract Collection<X509Certificate> getTrustedCertificates(); 280 281 /** 282 * Set the date to be used for subsequent validations. NOTE that 283 * this is not a supported API, it is provided to simplify 284 * writing tests only. 285 * 286 * @deprecated 287 */ 288 @Deprecated 289 public void setValidationDate(Date validationDate) { 290 this.validationDate = validationDate; 291 } 292 293 }