J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 1998-2006 Sun Microsystems, Inc. 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. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | |
| 26 | package java.security.cert; |
| 27 | |
| 28 | import java.io.InputStream; |
| 29 | import java.util.Collection; |
| 30 | import java.util.Iterator; |
| 31 | import java.util.List; |
| 32 | import java.security.Provider; |
| 33 | import java.security.NoSuchAlgorithmException; |
| 34 | import java.security.NoSuchProviderException; |
| 35 | |
| 36 | /** |
| 37 | * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) |
| 38 | * for the <code>CertificateFactory</code> class. |
| 39 | * All the abstract methods in this class must be implemented by each |
| 40 | * cryptographic service provider who wishes to supply the implementation |
| 41 | * of a certificate factory for a particular certificate type, e.g., X.509. |
| 42 | * |
| 43 | * <p>Certificate factories are used to generate certificate, certification path |
| 44 | * (<code>CertPath</code>) and certificate revocation list (CRL) objects from |
| 45 | * their encodings. |
| 46 | * |
| 47 | * <p>A certificate factory for X.509 must return certificates that are an |
| 48 | * instance of <code>java.security.cert.X509Certificate</code>, and CRLs |
| 49 | * that are an instance of <code>java.security.cert.X509CRL</code>. |
| 50 | * |
| 51 | * @author Hemma Prafullchandra |
| 52 | * @author Jan Luehe |
| 53 | * @author Sean Mullan |
| 54 | * |
| 55 | * |
| 56 | * @see CertificateFactory |
| 57 | * @see Certificate |
| 58 | * @see X509Certificate |
| 59 | * @see CertPath |
| 60 | * @see CRL |
| 61 | * @see X509CRL |
| 62 | * |
| 63 | * @since 1.2 |
| 64 | */ |
| 65 | |
| 66 | public abstract class CertificateFactorySpi { |
| 67 | |
| 68 | /** |
| 69 | * Generates a certificate object and initializes it with |
| 70 | * the data read from the input stream <code>inStream</code>. |
| 71 | * |
| 72 | * <p>In order to take advantage of the specialized certificate format |
| 73 | * supported by this certificate factory, |
| 74 | * the returned certificate object can be typecast to the corresponding |
| 75 | * certificate class. For example, if this certificate |
| 76 | * factory implements X.509 certificates, the returned certificate object |
| 77 | * can be typecast to the <code>X509Certificate</code> class. |
| 78 | * |
| 79 | * <p>In the case of a certificate factory for X.509 certificates, the |
| 80 | * certificate provided in <code>inStream</code> must be DER-encoded and |
| 81 | * may be supplied in binary or printable (Base64) encoding. If the |
| 82 | * certificate is provided in Base64 encoding, it must be bounded at |
| 83 | * the beginning by -----BEGIN CERTIFICATE-----, and must be bounded at |
| 84 | * the end by -----END CERTIFICATE-----. |
| 85 | * |
| 86 | * <p>Note that if the given input stream does not support |
| 87 | * {@link java.io.InputStream#mark(int) mark} and |
| 88 | * {@link java.io.InputStream#reset() reset}, this method will |
| 89 | * consume the entire input stream. Otherwise, each call to this |
| 90 | * method consumes one certificate and the read position of the input stream |
| 91 | * is positioned to the next available byte after the the inherent |
| 92 | * end-of-certificate marker. If the data in the |
| 93 | * input stream does not contain an inherent end-of-certificate marker (other |
| 94 | * than EOF) and there is trailing data after the certificate is parsed, a |
| 95 | * <code>CertificateException</code> is thrown. |
| 96 | * |
| 97 | * @param inStream an input stream with the certificate data. |
| 98 | * |
| 99 | * @return a certificate object initialized with the data |
| 100 | * from the input stream. |
| 101 | * |
| 102 | * @exception CertificateException on parsing errors. |
| 103 | */ |
| 104 | public abstract Certificate engineGenerateCertificate(InputStream inStream) |
| 105 | throws CertificateException; |
| 106 | |
| 107 | /** |
| 108 | * Generates a <code>CertPath</code> object and initializes it with |
| 109 | * the data read from the <code>InputStream</code> inStream. The data |
| 110 | * is assumed to be in the default encoding. |
| 111 | * |
| 112 | * <p> This method was added to version 1.4 of the Java 2 Platform |
| 113 | * Standard Edition. In order to maintain backwards compatibility with |
| 114 | * existing service providers, this method cannot be <code>abstract</code> |
| 115 | * and by default throws an <code>UnsupportedOperationException</code>. |
| 116 | * |
| 117 | * @param inStream an <code>InputStream</code> containing the data |
| 118 | * @return a <code>CertPath</code> initialized with the data from the |
| 119 | * <code>InputStream</code> |
| 120 | * @exception CertificateException if an exception occurs while decoding |
| 121 | * @exception UnsupportedOperationException if the method is not supported |
| 122 | * @since 1.4 |
| 123 | */ |
| 124 | public CertPath engineGenerateCertPath(InputStream inStream) |
| 125 | throws CertificateException |
| 126 | { |
| 127 | throw new UnsupportedOperationException(); |
| 128 | } |
| 129 | |
| 130 | /** |
| 131 | * Generates a <code>CertPath</code> object and initializes it with |
| 132 | * the data read from the <code>InputStream</code> inStream. The data |
| 133 | * is assumed to be in the specified encoding. |
| 134 | * |
| 135 | * <p> This method was added to version 1.4 of the Java 2 Platform |
| 136 | * Standard Edition. In order to maintain backwards compatibility with |
| 137 | * existing service providers, this method cannot be <code>abstract</code> |
| 138 | * and by default throws an <code>UnsupportedOperationException</code>. |
| 139 | * |
| 140 | * @param inStream an <code>InputStream</code> containing the data |
| 141 | * @param encoding the encoding used for the data |
| 142 | * @return a <code>CertPath</code> initialized with the data from the |
| 143 | * <code>InputStream</code> |
| 144 | * @exception CertificateException if an exception occurs while decoding or |
| 145 | * the encoding requested is not supported |
| 146 | * @exception UnsupportedOperationException if the method is not supported |
| 147 | * @since 1.4 |
| 148 | */ |
| 149 | public CertPath engineGenerateCertPath(InputStream inStream, |
| 150 | String encoding) throws CertificateException |
| 151 | { |
| 152 | throw new UnsupportedOperationException(); |
| 153 | } |
| 154 | |
| 155 | /** |
| 156 | * Generates a <code>CertPath</code> object and initializes it with |
| 157 | * a <code>List</code> of <code>Certificate</code>s. |
| 158 | * <p> |
| 159 | * The certificates supplied must be of a type supported by the |
| 160 | * <code>CertificateFactory</code>. They will be copied out of the supplied |
| 161 | * <code>List</code> object. |
| 162 | * |
| 163 | * <p> This method was added to version 1.4 of the Java 2 Platform |
| 164 | * Standard Edition. In order to maintain backwards compatibility with |
| 165 | * existing service providers, this method cannot be <code>abstract</code> |
| 166 | * and by default throws an <code>UnsupportedOperationException</code>. |
| 167 | * |
| 168 | * @param certificates a <code>List</code> of <code>Certificate</code>s |
| 169 | * @return a <code>CertPath</code> initialized with the supplied list of |
| 170 | * certificates |
| 171 | * @exception CertificateException if an exception occurs |
| 172 | * @exception UnsupportedOperationException if the method is not supported |
| 173 | * @since 1.4 |
| 174 | */ |
| 175 | public CertPath |
| 176 | engineGenerateCertPath(List<? extends Certificate> certificates) |
| 177 | throws CertificateException |
| 178 | { |
| 179 | throw new UnsupportedOperationException(); |
| 180 | } |
| 181 | |
| 182 | /** |
| 183 | * Returns an iteration of the <code>CertPath</code> encodings supported |
| 184 | * by this certificate factory, with the default encoding first. See |
| 185 | * Appendix A in the |
| 186 | * <a href="../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA"> |
| 187 | * Java Certification Path API Programmer's Guide</a> |
| 188 | * for information about standard encoding names. |
| 189 | * <p> |
| 190 | * Attempts to modify the returned <code>Iterator</code> via its |
| 191 | * <code>remove</code> method result in an |
| 192 | * <code>UnsupportedOperationException</code>. |
| 193 | * |
| 194 | * <p> This method was added to version 1.4 of the Java 2 Platform |
| 195 | * Standard Edition. In order to maintain backwards compatibility with |
| 196 | * existing service providers, this method cannot be <code>abstract</code> |
| 197 | * and by default throws an <code>UnsupportedOperationException</code>. |
| 198 | * |
| 199 | * @return an <code>Iterator</code> over the names of the supported |
| 200 | * <code>CertPath</code> encodings (as <code>String</code>s) |
| 201 | * @exception UnsupportedOperationException if the method is not supported |
| 202 | * @since 1.4 |
| 203 | */ |
| 204 | public Iterator<String> engineGetCertPathEncodings() { |
| 205 | throw new UnsupportedOperationException(); |
| 206 | } |
| 207 | |
| 208 | /** |
| 209 | * Returns a (possibly empty) collection view of the certificates read |
| 210 | * from the given input stream <code>inStream</code>. |
| 211 | * |
| 212 | * <p>In order to take advantage of the specialized certificate format |
| 213 | * supported by this certificate factory, each element in |
| 214 | * the returned collection view can be typecast to the corresponding |
| 215 | * certificate class. For example, if this certificate |
| 216 | * factory implements X.509 certificates, the elements in the returned |
| 217 | * collection can be typecast to the <code>X509Certificate</code> class. |
| 218 | * |
| 219 | * <p>In the case of a certificate factory for X.509 certificates, |
| 220 | * <code>inStream</code> may contain a single DER-encoded certificate |
| 221 | * in the formats described for |
| 222 | * {@link CertificateFactory#generateCertificate(java.io.InputStream) |
| 223 | * generateCertificate}. |
| 224 | * In addition, <code>inStream</code> may contain a PKCS#7 certificate |
| 225 | * chain. This is a PKCS#7 <i>SignedData</i> object, with the only |
| 226 | * significant field being <i>certificates</i>. In particular, the |
| 227 | * signature and the contents are ignored. This format allows multiple |
| 228 | * certificates to be downloaded at once. If no certificates are present, |
| 229 | * an empty collection is returned. |
| 230 | * |
| 231 | * <p>Note that if the given input stream does not support |
| 232 | * {@link java.io.InputStream#mark(int) mark} and |
| 233 | * {@link java.io.InputStream#reset() reset}, this method will |
| 234 | * consume the entire input stream. |
| 235 | * |
| 236 | * @param inStream the input stream with the certificates. |
| 237 | * |
| 238 | * @return a (possibly empty) collection view of |
| 239 | * java.security.cert.Certificate objects |
| 240 | * initialized with the data from the input stream. |
| 241 | * |
| 242 | * @exception CertificateException on parsing errors. |
| 243 | */ |
| 244 | public abstract Collection<? extends Certificate> |
| 245 | engineGenerateCertificates(InputStream inStream) |
| 246 | throws CertificateException; |
| 247 | |
| 248 | /** |
| 249 | * Generates a certificate revocation list (CRL) object and initializes it |
| 250 | * with the data read from the input stream <code>inStream</code>. |
| 251 | * |
| 252 | * <p>In order to take advantage of the specialized CRL format |
| 253 | * supported by this certificate factory, |
| 254 | * the returned CRL object can be typecast to the corresponding |
| 255 | * CRL class. For example, if this certificate |
| 256 | * factory implements X.509 CRLs, the returned CRL object |
| 257 | * can be typecast to the <code>X509CRL</code> class. |
| 258 | * |
| 259 | * <p>Note that if the given input stream does not support |
| 260 | * {@link java.io.InputStream#mark(int) mark} and |
| 261 | * {@link java.io.InputStream#reset() reset}, this method will |
| 262 | * consume the entire input stream. Otherwise, each call to this |
| 263 | * method consumes one CRL and the read position of the input stream |
| 264 | * is positioned to the next available byte after the the inherent |
| 265 | * end-of-CRL marker. If the data in the |
| 266 | * input stream does not contain an inherent end-of-CRL marker (other |
| 267 | * than EOF) and there is trailing data after the CRL is parsed, a |
| 268 | * <code>CRLException</code> is thrown. |
| 269 | * |
| 270 | * @param inStream an input stream with the CRL data. |
| 271 | * |
| 272 | * @return a CRL object initialized with the data |
| 273 | * from the input stream. |
| 274 | * |
| 275 | * @exception CRLException on parsing errors. |
| 276 | */ |
| 277 | public abstract CRL engineGenerateCRL(InputStream inStream) |
| 278 | throws CRLException; |
| 279 | |
| 280 | /** |
| 281 | * Returns a (possibly empty) collection view of the CRLs read |
| 282 | * from the given input stream <code>inStream</code>. |
| 283 | * |
| 284 | * <p>In order to take advantage of the specialized CRL format |
| 285 | * supported by this certificate factory, each element in |
| 286 | * the returned collection view can be typecast to the corresponding |
| 287 | * CRL class. For example, if this certificate |
| 288 | * factory implements X.509 CRLs, the elements in the returned |
| 289 | * collection can be typecast to the <code>X509CRL</code> class. |
| 290 | * |
| 291 | * <p>In the case of a certificate factory for X.509 CRLs, |
| 292 | * <code>inStream</code> may contain a single DER-encoded CRL. |
| 293 | * In addition, <code>inStream</code> may contain a PKCS#7 CRL |
| 294 | * set. This is a PKCS#7 <i>SignedData</i> object, with the only |
| 295 | * significant field being <i>crls</i>. In particular, the |
| 296 | * signature and the contents are ignored. This format allows multiple |
| 297 | * CRLs to be downloaded at once. If no CRLs are present, |
| 298 | * an empty collection is returned. |
| 299 | * |
| 300 | * <p>Note that if the given input stream does not support |
| 301 | * {@link java.io.InputStream#mark(int) mark} and |
| 302 | * {@link java.io.InputStream#reset() reset}, this method will |
| 303 | * consume the entire input stream. |
| 304 | * |
| 305 | * @param inStream the input stream with the CRLs. |
| 306 | * |
| 307 | * @return a (possibly empty) collection view of |
| 308 | * java.security.cert.CRL objects initialized with the data from the input |
| 309 | * stream. |
| 310 | * |
| 311 | * @exception CRLException on parsing errors. |
| 312 | */ |
| 313 | public abstract Collection<? extends CRL> engineGenerateCRLs |
| 314 | (InputStream inStream) throws CRLException; |
| 315 | } |