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