1 /* 2 * Copyright (c) 2012, 2013, 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 package java.security.cert; 26 27 import java.net.URI; 28 import java.util.ArrayList; 29 import java.util.Collections; 30 import java.util.HashMap; 31 import java.util.HashSet; 32 import java.util.List; 33 import java.util.Map; 34 import java.util.Map.Entry; 35 import java.util.Set; 36 37 /** 38 * A {@code PKIXCertPathChecker} for checking the revocation status of 39 * certificates with the PKIX algorithm. 40 * 41 * <p>A {@code PKIXRevocationChecker} checks the revocation status of 42 * certificates with the Online Certificate Status Protocol (OCSP) or 43 * Certificate Revocation Lists (CRLs). OCSP is described in RFC 2560 and 44 * is a network protocol for determining the status of a certificate. A CRL 45 * is a time-stamped list identifying revoked certificates, and RFC 5280 46 * describes an algorithm for determining the revocation status of certificates 47 * using CRLs. 48 * 49 * <p>Each {@code PKIXRevocationChecker} must be able to check the revocation 50 * status of certificates with OCSP and CRLs. By default, OCSP is the 51 * preferred mechanism for checking revocation status, with CRLs as the 52 * fallback mechanism. However, this preference can be switched to CRLs with 53 * the {@link Option#PREFER_CRLS PREFER_CRLS} option. In addition, the fallback 54 * mechanism can be disabled with the {@link Option#NO_FALLBACK NO_FALLBACK} 55 * option. 56 * 57 * <p>A {@code PKIXRevocationChecker} is obtained by calling the 58 * {@link CertPathValidator#getRevocationChecker getRevocationChecker} method 59 * of a PKIX {@code CertPathValidator}. Additional parameters and options 60 * specific to revocation can be set (by calling the 61 * {@link #setOcspResponder setOcspResponder} method for instance). The 62 * {@code PKIXRevocationChecker} is added to a {@code PKIXParameters} object 63 * using the {@link PKIXParameters#addCertPathChecker addCertPathChecker} 64 * or {@link PKIXParameters#setCertPathCheckers setCertPathCheckers} method, 65 * and then the {@code PKIXParameters} is passed along with the {@code CertPath} 66 * to be validated to the {@link CertPathValidator#validate validate} method 67 * of a PKIX {@code CertPathValidator}. When supplying a revocation checker in 68 * this manner, it will be used to check revocation irrespective of the setting 69 * of the {@link PKIXParameters#isRevocationEnabled RevocationEnabled} flag. 70 * Similarly, a {@code PKIXRevocationChecker} may be added to a 71 * {@code PKIXBuilderParameters} object for use with a PKIX 72 * {@code CertPathBuilder}. 73 * 74 * <p>Note that when a {@code PKIXRevocationChecker} is added to 75 * {@code PKIXParameters}, it clones the {@code PKIXRevocationChecker}; 76 * thus any subsequent modifications to the {@code PKIXRevocationChecker} 77 * have no effect. 78 * 79 * <p>Any parameter that is not set (or is set to {@code null}) will be set to 80 * the default value for that parameter. 81 * 82 * <p><b>Concurrent Access</b> 83 * 84 * <p>Unless otherwise specified, the methods defined in this class are not 85 * thread-safe. Multiple threads that need to access a single object 86 * concurrently should synchronize amongst themselves and provide the 87 * necessary locking. Multiple threads each manipulating separate objects 88 * need not synchronize. 89 * 90 * <p>See RFC 2560: X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - 91 * OCSP, RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation 92 * List (CRL) Profile (Android note: this paragraph was originally in a malformed "see" tag below, 93 * moved here for correct construction of the docs). 94 * 95 * @since 1.8 96 97 */ 98 public abstract class PKIXRevocationChecker extends PKIXCertPathChecker { 99 private URI ocspResponder; 100 private X509Certificate ocspResponderCert; 101 private List<Extension> ocspExtensions = Collections.<Extension>emptyList(); 102 private Map<X509Certificate, byte[]> ocspResponses = Collections.emptyMap(); 103 private Set<Option> options = Collections.emptySet(); 104 105 /** 106 * Default constructor. 107 */ PKIXRevocationChecker()108 protected PKIXRevocationChecker() {} 109 110 /** 111 * Sets the URI that identifies the location of the OCSP responder. This 112 * overrides the {@code ocsp.responderURL} security property and any 113 * responder specified in a certificate's Authority Information Access 114 * Extension, as defined in RFC 5280. 115 * 116 * @param uri the responder URI 117 */ setOcspResponder(URI uri)118 public void setOcspResponder(URI uri) { 119 this.ocspResponder = uri; 120 } 121 122 /** 123 * Gets the URI that identifies the location of the OCSP responder. This 124 * overrides the {@code ocsp.responderURL} security property. If this 125 * parameter or the {@code ocsp.responderURL} property is not set, the 126 * location is determined from the certificate's Authority Information 127 * Access Extension, as defined in RFC 5280. 128 * 129 * @return the responder URI, or {@code null} if not set 130 */ getOcspResponder()131 public URI getOcspResponder() { 132 return ocspResponder; 133 } 134 135 /** 136 * Sets the OCSP responder's certificate. This overrides the 137 * {@code ocsp.responderCertSubjectName}, 138 * {@code ocsp.responderCertIssuerName}, 139 * and {@code ocsp.responderCertSerialNumber} security properties. 140 * 141 * @param cert the responder's certificate 142 */ setOcspResponderCert(X509Certificate cert)143 public void setOcspResponderCert(X509Certificate cert) { 144 this.ocspResponderCert = cert; 145 } 146 147 /** 148 * Gets the OCSP responder's certificate. This overrides the 149 * {@code ocsp.responderCertSubjectName}, 150 * {@code ocsp.responderCertIssuerName}, 151 * and {@code ocsp.responderCertSerialNumber} security properties. If this 152 * parameter or the aforementioned properties are not set, then the 153 * responder's certificate is determined as specified in RFC 2560. 154 * 155 * @return the responder's certificate, or {@code null} if not set 156 */ getOcspResponderCert()157 public X509Certificate getOcspResponderCert() { 158 return ocspResponderCert; 159 } 160 161 // request extensions; single extensions not supported 162 /** 163 * Sets the optional OCSP request extensions. 164 * 165 * @param extensions a list of extensions. The list is copied to protect 166 * against subsequent modification. 167 */ setOcspExtensions(List<Extension> extensions)168 public void setOcspExtensions(List<Extension> extensions) 169 { 170 this.ocspExtensions = (extensions == null) 171 ? Collections.<Extension>emptyList() 172 : new ArrayList<Extension>(extensions); 173 } 174 175 /** 176 * Gets the optional OCSP request extensions. 177 * 178 * @return an unmodifiable list of extensions. The list is empty if no 179 * extensions have been specified. 180 */ getOcspExtensions()181 public List<Extension> getOcspExtensions() { 182 return Collections.unmodifiableList(ocspExtensions); 183 } 184 185 /** 186 * Sets the OCSP responses. These responses are used to determine 187 * the revocation status of the specified certificates when OCSP is used. 188 * 189 * @param responses a map of OCSP responses. Each key is an 190 * {@code X509Certificate} that maps to the corresponding 191 * DER-encoded OCSP response for that certificate. A deep copy of 192 * the map is performed to protect against subsequent modification. 193 */ setOcspResponses(Map<X509Certificate, byte[]> responses)194 public void setOcspResponses(Map<X509Certificate, byte[]> responses) 195 { 196 if (responses == null) { 197 this.ocspResponses = Collections.<X509Certificate, byte[]>emptyMap(); 198 } else { 199 Map<X509Certificate, byte[]> copy = new HashMap<>(responses.size()); 200 for (Map.Entry<X509Certificate, byte[]> e : responses.entrySet()) { 201 copy.put(e.getKey(), e.getValue().clone()); 202 } 203 this.ocspResponses = copy; 204 } 205 } 206 207 /** 208 * Gets the OCSP responses. These responses are used to determine 209 * the revocation status of the specified certificates when OCSP is used. 210 * 211 * @return a map of OCSP responses. Each key is an 212 * {@code X509Certificate} that maps to the corresponding 213 * DER-encoded OCSP response for that certificate. A deep copy of 214 * the map is returned to protect against subsequent modification. 215 * Returns an empty map if no responses have been specified. 216 */ getOcspResponses()217 public Map<X509Certificate, byte[]> getOcspResponses() { 218 Map<X509Certificate, byte[]> copy = new HashMap<>(ocspResponses.size()); 219 for (Map.Entry<X509Certificate, byte[]> e : ocspResponses.entrySet()) { 220 copy.put(e.getKey(), e.getValue().clone()); 221 } 222 return copy; 223 } 224 225 /** 226 * Sets the revocation options. 227 * 228 * @param options a set of revocation options. The set is copied to protect 229 * against subsequent modification. 230 */ setOptions(Set<Option> options)231 public void setOptions(Set<Option> options) { 232 this.options = (options == null) 233 ? Collections.<Option>emptySet() 234 : new HashSet<Option>(options); 235 } 236 237 /** 238 * Gets the revocation options. 239 * 240 * @return an unmodifiable set of revocation options. The set is empty if 241 * no options have been specified. 242 */ getOptions()243 public Set<Option> getOptions() { 244 return Collections.unmodifiableSet(options); 245 } 246 247 /** 248 * Returns a list containing the exceptions that are ignored by the 249 * revocation checker when the {@link Option#SOFT_FAIL SOFT_FAIL} option 250 * is set. The list is cleared each time {@link #init init} is called. 251 * The list is ordered in ascending order according to the certificate 252 * index returned by {@link CertPathValidatorException#getIndex getIndex} 253 * method of each entry. 254 * <p> 255 * An implementation of {@code PKIXRevocationChecker} is responsible for 256 * adding the ignored exceptions to the list. 257 * 258 * @return an unmodifiable list containing the ignored exceptions. The list 259 * is empty if no exceptions have been ignored. 260 */ getSoftFailExceptions()261 public abstract List<CertPathValidatorException> getSoftFailExceptions(); 262 263 @Override clone()264 public PKIXRevocationChecker clone() { 265 PKIXRevocationChecker copy = (PKIXRevocationChecker)super.clone(); 266 copy.ocspExtensions = new ArrayList<>(ocspExtensions); 267 copy.ocspResponses = new HashMap<>(ocspResponses); 268 // deep-copy the encoded responses, since they are mutable 269 for (Map.Entry<X509Certificate, byte[]> entry : 270 copy.ocspResponses.entrySet()) 271 { 272 byte[] encoded = entry.getValue(); 273 entry.setValue(encoded.clone()); 274 } 275 copy.options = new HashSet<>(options); 276 return copy; 277 } 278 279 /** 280 * Various revocation options that can be specified for the revocation 281 * checking mechanism. 282 */ 283 public enum Option { 284 /** 285 * Only check the revocation status of end-entity certificates. 286 */ 287 ONLY_END_ENTITY, 288 /** 289 * Prefer CRLs to OSCP. The default behavior is to prefer OCSP. Each 290 * PKIX implementation should document further details of their 291 * specific preference rules and fallback policies. 292 */ 293 PREFER_CRLS, 294 /** 295 * Disable the fallback mechanism. 296 */ 297 NO_FALLBACK, 298 /** 299 * Allow revocation check to succeed if the revocation status cannot be 300 * determined for one of the following reasons: 301 * <ul> 302 * <li>The CRL or OCSP response cannot be obtained because of a 303 * network error. 304 * <li>The OCSP responder returns one of the following errors 305 * specified in section 2.3 of RFC 2560: internalError or tryLater. 306 * </ul><br> 307 * Note that these conditions apply to both OCSP and CRLs, and unless 308 * the {@code NO_FALLBACK} option is set, the revocation check is 309 * allowed to succeed only if both mechanisms fail under one of the 310 * conditions as stated above. 311 * Exceptions that cause the network errors are ignored but can be 312 * later retrieved by calling the 313 * {@link #getSoftFailExceptions getSoftFailExceptions} method. 314 */ 315 SOFT_FAIL 316 } 317 } 318