001 /*
002 * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.security.cert;
027
028 import java.io.InputStream;
029 import java.util.Collection;
030 import java.util.Iterator;
031 import java.util.List;
032 import java.security.Provider;
033 import java.security.NoSuchAlgorithmException;
034 import java.security.NoSuchProviderException;
035
036 /**
037 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
038 * for the <code>CertificateFactory</code> class.
039 * All the abstract methods in this class must be implemented by each
040 * cryptographic service provider who wishes to supply the implementation
041 * of a certificate factory for a particular certificate type, e.g., X.509.
042 *
043 * <p>Certificate factories are used to generate certificate, certification path
044 * (<code>CertPath</code>) and certificate revocation list (CRL) objects from
045 * their encodings.
046 *
047 * <p>A certificate factory for X.509 must return certificates that are an
048 * instance of <code>java.security.cert.X509Certificate</code>, and CRLs
049 * that are an instance of <code>java.security.cert.X509CRL</code>.
050 *
051 * @author Hemma Prafullchandra
052 * @author Jan Luehe
053 * @author Sean Mullan
054 *
055 * @version 1.27, 05/05/07
056 *
057 * @see CertificateFactory
058 * @see Certificate
059 * @see X509Certificate
060 * @see CertPath
061 * @see CRL
062 * @see X509CRL
063 *
064 * @since 1.2
065 */
066
067 public abstract class CertificateFactorySpi {
068
069 /**
070 * Generates a certificate object and initializes it with
071 * the data read from the input stream <code>inStream</code>.
072 *
073 * <p>In order to take advantage of the specialized certificate format
074 * supported by this certificate factory,
075 * the returned certificate object can be typecast to the corresponding
076 * certificate class. For example, if this certificate
077 * factory implements X.509 certificates, the returned certificate object
078 * can be typecast to the <code>X509Certificate</code> class.
079 *
080 * <p>In the case of a certificate factory for X.509 certificates, the
081 * certificate provided in <code>inStream</code> must be DER-encoded and
082 * may be supplied in binary or printable (Base64) encoding. If the
083 * certificate is provided in Base64 encoding, it must be bounded at
084 * the beginning by -----BEGIN CERTIFICATE-----, and must be bounded at
085 * the end by -----END CERTIFICATE-----.
086 *
087 * <p>Note that if the given input stream does not support
088 * {@link java.io.InputStream#mark(int) mark} and
089 * {@link java.io.InputStream#reset() reset}, this method will
090 * consume the entire input stream. Otherwise, each call to this
091 * method consumes one certificate and the read position of the input stream
092 * is positioned to the next available byte after the the inherent
093 * end-of-certificate marker. If the data in the
094 * input stream does not contain an inherent end-of-certificate marker (other
095 * than EOF) and there is trailing data after the certificate is parsed, a
096 * <code>CertificateException</code> is thrown.
097 *
098 * @param inStream an input stream with the certificate data.
099 *
100 * @return a certificate object initialized with the data
101 * from the input stream.
102 *
103 * @exception CertificateException on parsing errors.
104 */
105 public abstract Certificate engineGenerateCertificate(
106 InputStream inStream) throws CertificateException;
107
108 /**
109 * Generates a <code>CertPath</code> object and initializes it with
110 * the data read from the <code>InputStream</code> inStream. The data
111 * is assumed to be in the default encoding.
112 *
113 * <p> This method was added to version 1.4 of the Java 2 Platform
114 * Standard Edition. In order to maintain backwards compatibility with
115 * existing service providers, this method cannot be <code>abstract</code>
116 * and by default throws an <code>UnsupportedOperationException</code>.
117 *
118 * @param inStream an <code>InputStream</code> containing the data
119 * @return a <code>CertPath</code> initialized with the data from the
120 * <code>InputStream</code>
121 * @exception CertificateException if an exception occurs while decoding
122 * @exception UnsupportedOperationException if the method is not supported
123 * @since 1.4
124 */
125 public CertPath engineGenerateCertPath(InputStream inStream)
126 throws CertificateException {
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 throw new UnsupportedOperationException();
152 }
153
154 /**
155 * Generates a <code>CertPath</code> object and initializes it with
156 * a <code>List</code> of <code>Certificate</code>s.
157 * <p>
158 * The certificates supplied must be of a type supported by the
159 * <code>CertificateFactory</code>. They will be copied out of the supplied
160 * <code>List</code> object.
161 *
162 * <p> This method was added to version 1.4 of the Java 2 Platform
163 * Standard Edition. In order to maintain backwards compatibility with
164 * existing service providers, this method cannot be <code>abstract</code>
165 * and by default throws an <code>UnsupportedOperationException</code>.
166 *
167 * @param certificates a <code>List</code> of <code>Certificate</code>s
168 * @return a <code>CertPath</code> initialized with the supplied list of
169 * certificates
170 * @exception CertificateException if an exception occurs
171 * @exception UnsupportedOperationException if the method is not supported
172 * @since 1.4
173 */
174 public CertPath engineGenerateCertPath(
175 List<? extends Certificate> certificates)
176 throws CertificateException {
177 throw new UnsupportedOperationException();
178 }
179
180 /**
181 * Returns an iteration of the <code>CertPath</code> encodings supported
182 * by this certificate factory, with the default encoding first. See
183 * Appendix A in the
184 * <a href="../../../../technotes/guides/security/certpath/CertPathProgGuide.html#AppA">
185 * Java Certification Path API Programmer's Guide</a>
186 * for information about standard encoding names.
187 * <p>
188 * Attempts to modify the returned <code>Iterator</code> via its
189 * <code>remove</code> method result in an
190 * <code>UnsupportedOperationException</code>.
191 *
192 * <p> This method was added to version 1.4 of the Java 2 Platform
193 * Standard Edition. In order to maintain backwards compatibility with
194 * existing service providers, this method cannot be <code>abstract</code>
195 * and by default throws an <code>UnsupportedOperationException</code>.
196 *
197 * @return an <code>Iterator</code> over the names of the supported
198 * <code>CertPath</code> encodings (as <code>String</code>s)
199 * @exception UnsupportedOperationException if the method is not supported
200 * @since 1.4
201 */
202 public Iterator<String> engineGetCertPathEncodings() {
203 throw new UnsupportedOperationException();
204 }
205
206 /**
207 * Returns a (possibly empty) collection view of the certificates read
208 * from the given input stream <code>inStream</code>.
209 *
210 * <p>In order to take advantage of the specialized certificate format
211 * supported by this certificate factory, each element in
212 * the returned collection view can be typecast to the corresponding
213 * certificate class. For example, if this certificate
214 * factory implements X.509 certificates, the elements in the returned
215 * collection can be typecast to the <code>X509Certificate</code> class.
216 *
217 * <p>In the case of a certificate factory for X.509 certificates,
218 * <code>inStream</code> may contain a single DER-encoded certificate
219 * in the formats described for
220 * {@link CertificateFactory#generateCertificate(java.io.InputStream)
221 * generateCertificate}.
222 * In addition, <code>inStream</code> may contain a PKCS#7 certificate
223 * chain. This is a PKCS#7 <i>SignedData</i> object, with the only
224 * significant field being <i>certificates</i>. In particular, the
225 * signature and the contents are ignored. This format allows multiple
226 * certificates to be downloaded at once. If no certificates are present,
227 * an empty collection is returned.
228 *
229 * <p>Note that if the given input stream does not support
230 * {@link java.io.InputStream#mark(int) mark} and
231 * {@link java.io.InputStream#reset() reset}, this method will
232 * consume the entire input stream.
233 *
234 * @param inStream the input stream with the certificates.
235 *
236 * @return a (possibly empty) collection view of
237 * java.security.cert.Certificate objects
238 * initialized with the data from the input stream.
239 *
240 * @exception CertificateException on parsing errors.
241 */
242 public abstract Collection<? extends Certificate> engineGenerateCertificates(
243 InputStream inStream) throws CertificateException;
244
245 /**
246 * Generates a certificate revocation list (CRL) object and initializes it
247 * with the data read from the input stream <code>inStream</code>.
248 *
249 * <p>In order to take advantage of the specialized CRL format
250 * supported by this certificate factory,
251 * the returned CRL object can be typecast to the corresponding
252 * CRL class. For example, if this certificate
253 * factory implements X.509 CRLs, the returned CRL object
254 * can be typecast to the <code>X509CRL</code> class.
255 *
256 * <p>Note that if the given input stream does not support
257 * {@link java.io.InputStream#mark(int) mark} and
258 * {@link java.io.InputStream#reset() reset}, this method will
259 * consume the entire input stream. Otherwise, each call to this
260 * method consumes one CRL and the read position of the input stream
261 * is positioned to the next available byte after the the inherent
262 * end-of-CRL marker. If the data in the
263 * input stream does not contain an inherent end-of-CRL marker (other
264 * than EOF) and there is trailing data after the CRL is parsed, a
265 * <code>CRLException</code> is thrown.
266 *
267 * @param inStream an input stream with the CRL data.
268 *
269 * @return a CRL object initialized with the data
270 * from the input stream.
271 *
272 * @exception CRLException on parsing errors.
273 */
274 public abstract CRL engineGenerateCRL(InputStream inStream)
275 throws CRLException;
276
277 /**
278 * Returns a (possibly empty) collection view of the CRLs read
279 * from the given input stream <code>inStream</code>.
280 *
281 * <p>In order to take advantage of the specialized CRL format
282 * supported by this certificate factory, each element in
283 * the returned collection view can be typecast to the corresponding
284 * CRL class. For example, if this certificate
285 * factory implements X.509 CRLs, the elements in the returned
286 * collection can be typecast to the <code>X509CRL</code> class.
287 *
288 * <p>In the case of a certificate factory for X.509 CRLs,
289 * <code>inStream</code> may contain a single DER-encoded CRL.
290 * In addition, <code>inStream</code> may contain a PKCS#7 CRL
291 * set. This is a PKCS#7 <i>SignedData</i> object, with the only
292 * significant field being <i>crls</i>. In particular, the
293 * signature and the contents are ignored. This format allows multiple
294 * CRLs to be downloaded at once. If no CRLs are present,
295 * an empty collection is returned.
296 *
297 * <p>Note that if the given input stream does not support
298 * {@link java.io.InputStream#mark(int) mark} and
299 * {@link java.io.InputStream#reset() reset}, this method will
300 * consume the entire input stream.
301 *
302 * @param inStream the input stream with the CRLs.
303 *
304 * @return a (possibly empty) collection view of
305 * java.security.cert.CRL objects initialized with the data from the input
306 * stream.
307 *
308 * @exception CRLException on parsing errors.
309 */
310 public abstract Collection<? extends CRL> engineGenerateCRLs(
311 InputStream inStream) throws CRLException;
312 }
|