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 }
Save This Page