1 /* 2 * Copyright (c) 2000, 2012, 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.util.Collection; 29 import java.util.Set; 30 31 /** 32 * An abstract class that performs one or more checks on an 33 * <code>X509Certificate</code>. 34 * 35 * <p>A concrete implementation of the <code>PKIXCertPathChecker</code> class 36 * can be created to extend the PKIX certification path validation algorithm. 37 * For example, an implementation may check for and process a critical private 38 * extension of each certificate in a certification path. 39 * 40 * <p>Instances of <code>PKIXCertPathChecker</code> are passed as parameters 41 * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers} 42 * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods 43 * of the <code>PKIXParameters</code> and <code>PKIXBuilderParameters</code> 44 * class. Each of the <code>PKIXCertPathChecker</code>s {@link #check check} 45 * methods will be called, in turn, for each certificate processed by a PKIX 46 * <code>CertPathValidator</code> or <code>CertPathBuilder</code> 47 * implementation. 48 * 49 * <p>A <code>PKIXCertPathChecker</code> may be called multiple times on 50 * successive certificates in a certification path. Concrete subclasses 51 * are expected to maintain any internal state that may be necessary to 52 * check successive certificates. The {@link #init init} method is used 53 * to initialize the internal state of the checker so that the certificates 54 * of a new certification path may be checked. A stateful implementation 55 * <b>must</b> override the {@link #clone clone} method if necessary in 56 * order to allow a PKIX <code>CertPathBuilder</code> to efficiently 57 * backtrack and try other paths. In these situations, the 58 * <code>CertPathBuilder</code> is able to restore prior path validation 59 * states by restoring the cloned <code>PKIXCertPathChecker</code>s. 60 * 61 * <p>The order in which the certificates are presented to the 62 * <code>PKIXCertPathChecker</code> may be either in the forward direction 63 * (from target to most-trusted CA) or in the reverse direction (from 64 * most-trusted CA to target). A <code>PKIXCertPathChecker</code> implementation 65 * <b>must</b> support reverse checking (the ability to perform its checks when 66 * it is presented with certificates in the reverse direction) and <b>may</b> 67 * support forward checking (the ability to perform its checks when it is 68 * presented with certificates in the forward direction). The 69 * {@link #isForwardCheckingSupported isForwardCheckingSupported} method 70 * indicates whether forward checking is supported. 71 * <p> 72 * Additional input parameters required for executing the check may be 73 * specified through constructors of concrete implementations of this class. 74 * <p> 75 * <b>Concurrent Access</b> 76 * <p> 77 * Unless otherwise specified, the methods defined in this class are not 78 * thread-safe. Multiple threads that need to access a single 79 * object concurrently should synchronize amongst themselves and 80 * provide the necessary locking. Multiple threads each manipulating 81 * separate objects need not synchronize. 82 * 83 * @see PKIXParameters 84 * @see PKIXBuilderParameters 85 * 86 * @since 1.4 87 * @author Yassir Elley 88 * @author Sean Mullan 89 */ 90 public abstract class PKIXCertPathChecker 91 implements CertPathChecker, Cloneable { 92 93 /** 94 * Default constructor. 95 */ 96 protected PKIXCertPathChecker() {} 97 98 /** 99 * Initializes the internal state of this <code>PKIXCertPathChecker</code>. 100 * <p> 101 * The <code>forward</code> flag specifies the order that 102 * certificates will be passed to the {@link #check check} method 103 * (forward or reverse). A <code>PKIXCertPathChecker</code> <b>must</b> 104 * support reverse checking and <b>may</b> support forward checking. 105 * 106 * @param forward the order that certificates are presented to 107 * the <code>check</code> method. If <code>true</code>, certificates 108 * are presented from target to most-trusted CA (forward); if 109 * <code>false</code>, from most-trusted CA to target (reverse). 110 * @throws CertPathValidatorException if this 111 * <code>PKIXCertPathChecker</code> is unable to check certificates in 112 * the specified order; it should never be thrown if the forward flag 113 * is false since reverse checking must be supported 114 */ 115 @Override 116 public abstract void init(boolean forward) 117 throws CertPathValidatorException; 118 119 /** 120 * Indicates if forward checking is supported. Forward checking refers 121 * to the ability of the <code>PKIXCertPathChecker</code> to perform 122 * its checks when certificates are presented to the <code>check</code> 123 * method in the forward direction (from target to most-trusted CA). 124 * 125 * @return <code>true</code> if forward checking is supported, 126 * <code>false</code> otherwise 127 */ 128 @Override 129 public abstract boolean isForwardCheckingSupported(); 130 131 /** 132 * Returns an immutable <code>Set</code> of X.509 certificate extensions 133 * that this <code>PKIXCertPathChecker</code> supports (i.e. recognizes, is 134 * able to process), or <code>null</code> if no extensions are supported. 135 * <p> 136 * Each element of the set is a <code>String</code> representing the 137 * Object Identifier (OID) of the X.509 extension that is supported. 138 * The OID is represented by a set of nonnegative integers separated by 139 * periods. 140 * <p> 141 * All X.509 certificate extensions that a <code>PKIXCertPathChecker</code> 142 * might possibly be able to process should be included in the set. 143 * 144 * @return an immutable <code>Set</code> of X.509 extension OIDs (in 145 * <code>String</code> format) supported by this 146 * <code>PKIXCertPathChecker</code>, or <code>null</code> if no 147 * extensions are supported 148 */ 149 public abstract Set<String> getSupportedExtensions(); 150 151 /** 152 * Performs the check(s) on the specified certificate using its internal 153 * state and removes any critical extensions that it processes from the 154 * specified collection of OID strings that represent the unresolved 155 * critical extensions. The certificates are presented in the order 156 * specified by the <code>init</code> method. 157 * 158 * @param cert the <code>Certificate</code> to be checked 159 * @param unresolvedCritExts a <code>Collection</code> of OID strings 160 * representing the current set of unresolved critical extensions 161 * @exception CertPathValidatorException if the specified certificate does 162 * not pass the check 163 */ 164 public abstract void check(Certificate cert, 165 Collection<String> unresolvedCritExts) 166 throws CertPathValidatorException; 167 168 /** 169 * {@inheritDoc} 170 * 171 * <p>This implementation calls 172 * {@code check(cert, java.util.Collections.<String>emptySet())}. 173 */ 174 @Override 175 public void check(Certificate cert) throws CertPathValidatorException { 176 check(cert, java.util.Collections.<String>emptySet()); 177 } 178 179 /** 180 * Returns a clone of this object. Calls the <code>Object.clone()</code> 181 * method. 182 * All subclasses which maintain state must support and 183 * override this method, if necessary. 184 * 185 * @return a copy of this <code>PKIXCertPathChecker</code> 186 */ 187 @Override 188 public Object clone() { 189 try { 190 return super.clone(); 191 } catch (CloneNotSupportedException e) { 192 /* Cannot happen */ 193 throw new InternalError(e.toString(), e); 194 } 195 } 196 } | 1 /* 2 * Copyright (c) 2000, 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 26 package java.security.cert; 27 28 import java.util.Collection; 29 import java.util.Set; 30 31 /** 32 * An abstract class that performs one or more checks on an 33 * {@code X509Certificate}. 34 * 35 * <p>A concrete implementation of the {@code PKIXCertPathChecker} class 36 * can be created to extend the PKIX certification path validation algorithm. 37 * For example, an implementation may check for and process a critical private 38 * extension of each certificate in a certification path. 39 * 40 * <p>Instances of {@code PKIXCertPathChecker} are passed as parameters 41 * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers} 42 * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods 43 * of the {@code PKIXParameters} and {@code PKIXBuilderParameters} 44 * class. Each of the {@code PKIXCertPathChecker}s {@link #check check} 45 * methods will be called, in turn, for each certificate processed by a PKIX 46 * {@code CertPathValidator} or {@code CertPathBuilder} 47 * implementation. 48 * 49 * <p>A {@code PKIXCertPathChecker} may be called multiple times on 50 * successive certificates in a certification path. Concrete subclasses 51 * are expected to maintain any internal state that may be necessary to 52 * check successive certificates. The {@link #init init} method is used 53 * to initialize the internal state of the checker so that the certificates 54 * of a new certification path may be checked. A stateful implementation 55 * <b>must</b> override the {@link #clone clone} method if necessary in 56 * order to allow a PKIX {@code CertPathBuilder} to efficiently 57 * backtrack and try other paths. In these situations, the 58 * {@code CertPathBuilder} is able to restore prior path validation 59 * states by restoring the cloned {@code PKIXCertPathChecker}s. 60 * 61 * <p>The order in which the certificates are presented to the 62 * {@code PKIXCertPathChecker} may be either in the forward direction 63 * (from target to most-trusted CA) or in the reverse direction (from 64 * most-trusted CA to target). A {@code PKIXCertPathChecker} implementation 65 * <b>must</b> support reverse checking (the ability to perform its checks when 66 * it is presented with certificates in the reverse direction) and <b>may</b> 67 * support forward checking (the ability to perform its checks when it is 68 * presented with certificates in the forward direction). The 69 * {@link #isForwardCheckingSupported isForwardCheckingSupported} method 70 * indicates whether forward checking is supported. 71 * <p> 72 * Additional input parameters required for executing the check may be 73 * specified through constructors of concrete implementations of this class. 74 * <p> 75 * <b>Concurrent Access</b> 76 * <p> 77 * Unless otherwise specified, the methods defined in this class are not 78 * thread-safe. Multiple threads that need to access a single 79 * object concurrently should synchronize amongst themselves and 80 * provide the necessary locking. Multiple threads each manipulating 81 * separate objects need not synchronize. 82 * 83 * @see PKIXParameters 84 * @see PKIXBuilderParameters 85 * 86 * @since 1.4 87 * @author Yassir Elley 88 * @author Sean Mullan 89 */ 90 public abstract class PKIXCertPathChecker 91 implements CertPathChecker, Cloneable { 92 93 /** 94 * Default constructor. 95 */ 96 protected PKIXCertPathChecker() {} 97 98 /** 99 * Initializes the internal state of this {@code PKIXCertPathChecker}. 100 * <p> 101 * The {@code forward} flag specifies the order that 102 * certificates will be passed to the {@link #check check} method 103 * (forward or reverse). A {@code PKIXCertPathChecker} <b>must</b> 104 * support reverse checking and <b>may</b> support forward checking. 105 * 106 * @param forward the order that certificates are presented to 107 * the {@code check} method. If {@code true}, certificates 108 * are presented from target to most-trusted CA (forward); if 109 * {@code false}, from most-trusted CA to target (reverse). 110 * @throws CertPathValidatorException if this 111 * {@code PKIXCertPathChecker} is unable to check certificates in 112 * the specified order; it should never be thrown if the forward flag 113 * is false since reverse checking must be supported 114 */ 115 @Override 116 public abstract void init(boolean forward) 117 throws CertPathValidatorException; 118 119 /** 120 * Indicates if forward checking is supported. Forward checking refers 121 * to the ability of the {@code PKIXCertPathChecker} to perform 122 * its checks when certificates are presented to the {@code check} 123 * method in the forward direction (from target to most-trusted CA). 124 * 125 * @return {@code true} if forward checking is supported, 126 * {@code false} otherwise 127 */ 128 @Override 129 public abstract boolean isForwardCheckingSupported(); 130 131 /** 132 * Returns an immutable {@code Set} of X.509 certificate extensions 133 * that this {@code PKIXCertPathChecker} supports (i.e. recognizes, is 134 * able to process), or {@code null} if no extensions are supported. 135 * <p> 136 * Each element of the set is a {@code String} representing the 137 * Object Identifier (OID) of the X.509 extension that is supported. 138 * The OID is represented by a set of nonnegative integers separated by 139 * periods. 140 * <p> 141 * All X.509 certificate extensions that a {@code PKIXCertPathChecker} 142 * might possibly be able to process should be included in the set. 143 * 144 * @return an immutable {@code Set} of X.509 extension OIDs (in 145 * {@code String} format) supported by this 146 * {@code PKIXCertPathChecker}, or {@code null} if no 147 * extensions are supported 148 */ 149 public abstract Set<String> getSupportedExtensions(); 150 151 /** 152 * Performs the check(s) on the specified certificate using its internal 153 * state and removes any critical extensions that it processes from the 154 * specified collection of OID strings that represent the unresolved 155 * critical extensions. The certificates are presented in the order 156 * specified by the {@code init} method. 157 * 158 * @param cert the {@code Certificate} to be checked 159 * @param unresolvedCritExts a {@code Collection} of OID strings 160 * representing the current set of unresolved critical extensions 161 * @exception CertPathValidatorException if the specified certificate does 162 * not pass the check 163 */ 164 public abstract void check(Certificate cert, 165 Collection<String> unresolvedCritExts) 166 throws CertPathValidatorException; 167 168 /** 169 * {@inheritDoc} 170 * 171 * <p>This implementation calls 172 * {@code check(cert, java.util.Collections.<String>emptySet())}. 173 */ 174 @Override 175 public void check(Certificate cert) throws CertPathValidatorException { 176 check(cert, java.util.Collections.<String>emptySet()); 177 } 178 179 /** 180 * Returns a clone of this object. Calls the {@code Object.clone()} 181 * method. 182 * All subclasses which maintain state must support and 183 * override this method, if necessary. 184 * 185 * @return a copy of this {@code PKIXCertPathChecker} 186 */ 187 @Override 188 public Object clone() { 189 try { 190 return super.clone(); 191 } catch (CloneNotSupportedException e) { 192 /* Cannot happen */ 193 throw new InternalError(e.toString(), e); 194 } 195 } 196 } |