CertificateFactorySpi


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