33 import java.security.NoSuchAlgorithmException; |
33 import java.security.NoSuchAlgorithmException; |
34 import java.security.NoSuchProviderException; |
34 import java.security.NoSuchProviderException; |
35 |
35 |
36 /** |
36 /** |
37 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) |
37 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) |
38 * for the <code>CertificateFactory</code> class. |
38 * for the {@code CertificateFactory} class. |
39 * All the abstract methods in this class must be implemented by each |
39 * All the abstract methods in this class must be implemented by each |
40 * cryptographic service provider who wishes to supply the implementation |
40 * cryptographic service provider who wishes to supply the implementation |
41 * of a certificate factory for a particular certificate type, e.g., X.509. |
41 * of a certificate factory for a particular certificate type, e.g., X.509. |
42 * |
42 * |
43 * <p>Certificate factories are used to generate certificate, certification path |
43 * <p>Certificate factories are used to generate certificate, certification path |
44 * (<code>CertPath</code>) and certificate revocation list (CRL) objects from |
44 * ({@code CertPath}) and certificate revocation list (CRL) objects from |
45 * their encodings. |
45 * their encodings. |
46 * |
46 * |
47 * <p>A certificate factory for X.509 must return certificates that are an |
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 |
48 * instance of {@code java.security.cert.X509Certificate}, and CRLs |
49 * that are an instance of <code>java.security.cert.X509CRL</code>. |
49 * that are an instance of {@code java.security.cert.X509CRL}. |
50 * |
50 * |
51 * @author Hemma Prafullchandra |
51 * @author Hemma Prafullchandra |
52 * @author Jan Luehe |
52 * @author Jan Luehe |
53 * @author Sean Mullan |
53 * @author Sean Mullan |
54 * |
54 * |
65 |
65 |
66 public abstract class CertificateFactorySpi { |
66 public abstract class CertificateFactorySpi { |
67 |
67 |
68 /** |
68 /** |
69 * Generates a certificate object and initializes it with |
69 * Generates a certificate object and initializes it with |
70 * the data read from the input stream <code>inStream</code>. |
70 * the data read from the input stream {@code inStream}. |
71 * |
71 * |
72 * <p>In order to take advantage of the specialized certificate format |
72 * <p>In order to take advantage of the specialized certificate format |
73 * supported by this certificate factory, |
73 * supported by this certificate factory, |
74 * the returned certificate object can be typecast to the corresponding |
74 * the returned certificate object can be typecast to the corresponding |
75 * certificate class. For example, if this certificate |
75 * certificate class. For example, if this certificate |
76 * factory implements X.509 certificates, the returned certificate object |
76 * factory implements X.509 certificates, the returned certificate object |
77 * can be typecast to the <code>X509Certificate</code> class. |
77 * can be typecast to the {@code X509Certificate} class. |
78 * |
78 * |
79 * <p>In the case of a certificate factory for X.509 certificates, the |
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 |
80 * certificate provided in {@code inStream} must be DER-encoded and |
81 * may be supplied in binary or printable (Base64) encoding. If the |
81 * may be supplied in binary or printable (Base64) encoding. If the |
82 * certificate is provided in Base64 encoding, it must be bounded at |
82 * certificate is provided in Base64 encoding, it must be bounded at |
83 * the beginning by -----BEGIN CERTIFICATE-----, and must be bounded at |
83 * the beginning by -----BEGIN CERTIFICATE-----, and must be bounded at |
84 * the end by -----END CERTIFICATE-----. |
84 * the end by -----END CERTIFICATE-----. |
85 * |
85 * |
90 * method consumes one certificate and the read position of the input stream |
90 * method consumes one certificate and the read position of the input stream |
91 * is positioned to the next available byte after the inherent |
91 * is positioned to the next available byte after the inherent |
92 * end-of-certificate marker. If the data in the |
92 * end-of-certificate marker. If the data in the |
93 * input stream does not contain an inherent end-of-certificate marker (other |
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 |
94 * than EOF) and there is trailing data after the certificate is parsed, a |
95 * <code>CertificateException</code> is thrown. |
95 * {@code CertificateException} is thrown. |
96 * |
96 * |
97 * @param inStream an input stream with the certificate data. |
97 * @param inStream an input stream with the certificate data. |
98 * |
98 * |
99 * @return a certificate object initialized with the data |
99 * @return a certificate object initialized with the data |
100 * from the input stream. |
100 * from the input stream. |
103 */ |
103 */ |
104 public abstract Certificate engineGenerateCertificate(InputStream inStream) |
104 public abstract Certificate engineGenerateCertificate(InputStream inStream) |
105 throws CertificateException; |
105 throws CertificateException; |
106 |
106 |
107 /** |
107 /** |
108 * Generates a <code>CertPath</code> object and initializes it with |
108 * Generates a {@code CertPath} object and initializes it with |
109 * the data read from the <code>InputStream</code> inStream. The data |
109 * the data read from the {@code InputStream} inStream. The data |
110 * is assumed to be in the default encoding. |
110 * is assumed to be in the default encoding. |
111 * |
111 * |
112 * <p> This method was added to version 1.4 of the Java 2 Platform |
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 |
113 * Standard Edition. In order to maintain backwards compatibility with |
114 * existing service providers, this method cannot be <code>abstract</code> |
114 * existing service providers, this method cannot be {@code abstract} |
115 * and by default throws an <code>UnsupportedOperationException</code>. |
115 * and by default throws an {@code UnsupportedOperationException}. |
116 * |
116 * |
117 * @param inStream an <code>InputStream</code> containing the data |
117 * @param inStream an {@code InputStream} containing the data |
118 * @return a <code>CertPath</code> initialized with the data from the |
118 * @return a {@code CertPath} initialized with the data from the |
119 * <code>InputStream</code> |
119 * {@code InputStream} |
120 * @exception CertificateException if an exception occurs while decoding |
120 * @exception CertificateException if an exception occurs while decoding |
121 * @exception UnsupportedOperationException if the method is not supported |
121 * @exception UnsupportedOperationException if the method is not supported |
122 * @since 1.4 |
122 * @since 1.4 |
123 */ |
123 */ |
124 public CertPath engineGenerateCertPath(InputStream inStream) |
124 public CertPath engineGenerateCertPath(InputStream inStream) |
126 { |
126 { |
127 throw new UnsupportedOperationException(); |
127 throw new UnsupportedOperationException(); |
128 } |
128 } |
129 |
129 |
130 /** |
130 /** |
131 * Generates a <code>CertPath</code> object and initializes it with |
131 * Generates a {@code CertPath} object and initializes it with |
132 * the data read from the <code>InputStream</code> inStream. The data |
132 * the data read from the {@code InputStream} inStream. The data |
133 * is assumed to be in the specified encoding. |
133 * is assumed to be in the specified encoding. |
134 * |
134 * |
135 * <p> This method was added to version 1.4 of the Java 2 Platform |
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 |
136 * Standard Edition. In order to maintain backwards compatibility with |
137 * existing service providers, this method cannot be <code>abstract</code> |
137 * existing service providers, this method cannot be {@code abstract} |
138 * and by default throws an <code>UnsupportedOperationException</code>. |
138 * and by default throws an {@code UnsupportedOperationException}. |
139 * |
139 * |
140 * @param inStream an <code>InputStream</code> containing the data |
140 * @param inStream an {@code InputStream} containing the data |
141 * @param encoding the encoding used for the data |
141 * @param encoding the encoding used for the data |
142 * @return a <code>CertPath</code> initialized with the data from the |
142 * @return a {@code CertPath} initialized with the data from the |
143 * <code>InputStream</code> |
143 * {@code InputStream} |
144 * @exception CertificateException if an exception occurs while decoding or |
144 * @exception CertificateException if an exception occurs while decoding or |
145 * the encoding requested is not supported |
145 * the encoding requested is not supported |
146 * @exception UnsupportedOperationException if the method is not supported |
146 * @exception UnsupportedOperationException if the method is not supported |
147 * @since 1.4 |
147 * @since 1.4 |
148 */ |
148 */ |
151 { |
151 { |
152 throw new UnsupportedOperationException(); |
152 throw new UnsupportedOperationException(); |
153 } |
153 } |
154 |
154 |
155 /** |
155 /** |
156 * Generates a <code>CertPath</code> object and initializes it with |
156 * Generates a {@code CertPath} object and initializes it with |
157 * a <code>List</code> of <code>Certificate</code>s. |
157 * a {@code List} of {@code Certificate}s. |
158 * <p> |
158 * <p> |
159 * The certificates supplied must be of a type supported by the |
159 * The certificates supplied must be of a type supported by the |
160 * <code>CertificateFactory</code>. They will be copied out of the supplied |
160 * {@code CertificateFactory}. They will be copied out of the supplied |
161 * <code>List</code> object. |
161 * {@code List} object. |
162 * |
162 * |
163 * <p> This method was added to version 1.4 of the Java 2 Platform |
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 |
164 * Standard Edition. In order to maintain backwards compatibility with |
165 * existing service providers, this method cannot be <code>abstract</code> |
165 * existing service providers, this method cannot be {@code abstract} |
166 * and by default throws an <code>UnsupportedOperationException</code>. |
166 * and by default throws an {@code UnsupportedOperationException}. |
167 * |
167 * |
168 * @param certificates a <code>List</code> of <code>Certificate</code>s |
168 * @param certificates a {@code List} of {@code Certificate}s |
169 * @return a <code>CertPath</code> initialized with the supplied list of |
169 * @return a {@code CertPath} initialized with the supplied list of |
170 * certificates |
170 * certificates |
171 * @exception CertificateException if an exception occurs |
171 * @exception CertificateException if an exception occurs |
172 * @exception UnsupportedOperationException if the method is not supported |
172 * @exception UnsupportedOperationException if the method is not supported |
173 * @since 1.4 |
173 * @since 1.4 |
174 */ |
174 */ |
178 { |
178 { |
179 throw new UnsupportedOperationException(); |
179 throw new UnsupportedOperationException(); |
180 } |
180 } |
181 |
181 |
182 /** |
182 /** |
183 * Returns an iteration of the <code>CertPath</code> encodings supported |
183 * Returns an iteration of the {@code CertPath} encodings supported |
184 * by this certificate factory, with the default encoding first. See |
184 * by this certificate factory, with the default encoding first. See |
185 * the CertPath Encodings section in the <a href= |
185 * the CertPath Encodings section in the <a href= |
186 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathEncodings"> |
186 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathEncodings"> |
187 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> |
187 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> |
188 * for information about standard encoding names. |
188 * for information about standard encoding names. |
189 * <p> |
189 * <p> |
190 * Attempts to modify the returned <code>Iterator</code> via its |
190 * Attempts to modify the returned {@code Iterator} via its |
191 * <code>remove</code> method result in an |
191 * {@code remove} method result in an |
192 * <code>UnsupportedOperationException</code>. |
192 * {@code UnsupportedOperationException}. |
193 * |
193 * |
194 * <p> This method was added to version 1.4 of the Java 2 Platform |
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 |
195 * Standard Edition. In order to maintain backwards compatibility with |
196 * existing service providers, this method cannot be <code>abstract</code> |
196 * existing service providers, this method cannot be {@code abstract} |
197 * and by default throws an <code>UnsupportedOperationException</code>. |
197 * and by default throws an {@code UnsupportedOperationException}. |
198 * |
198 * |
199 * @return an <code>Iterator</code> over the names of the supported |
199 * @return an {@code Iterator} over the names of the supported |
200 * <code>CertPath</code> encodings (as <code>String</code>s) |
200 * {@code CertPath} encodings (as {@code String}s) |
201 * @exception UnsupportedOperationException if the method is not supported |
201 * @exception UnsupportedOperationException if the method is not supported |
202 * @since 1.4 |
202 * @since 1.4 |
203 */ |
203 */ |
204 public Iterator<String> engineGetCertPathEncodings() { |
204 public Iterator<String> engineGetCertPathEncodings() { |
205 throw new UnsupportedOperationException(); |
205 throw new UnsupportedOperationException(); |
206 } |
206 } |
207 |
207 |
208 /** |
208 /** |
209 * Returns a (possibly empty) collection view of the certificates read |
209 * Returns a (possibly empty) collection view of the certificates read |
210 * from the given input stream <code>inStream</code>. |
210 * from the given input stream {@code inStream}. |
211 * |
211 * |
212 * <p>In order to take advantage of the specialized certificate format |
212 * <p>In order to take advantage of the specialized certificate format |
213 * supported by this certificate factory, each element in |
213 * supported by this certificate factory, each element in |
214 * the returned collection view can be typecast to the corresponding |
214 * the returned collection view can be typecast to the corresponding |
215 * certificate class. For example, if this certificate |
215 * certificate class. For example, if this certificate |
216 * factory implements X.509 certificates, the elements in the returned |
216 * factory implements X.509 certificates, the elements in the returned |
217 * collection can be typecast to the <code>X509Certificate</code> class. |
217 * collection can be typecast to the {@code X509Certificate} class. |
218 * |
218 * |
219 * <p>In the case of a certificate factory for X.509 certificates, |
219 * <p>In the case of a certificate factory for X.509 certificates, |
220 * <code>inStream</code> may contain a single DER-encoded certificate |
220 * {@code inStream} may contain a single DER-encoded certificate |
221 * in the formats described for |
221 * in the formats described for |
222 * {@link CertificateFactory#generateCertificate(java.io.InputStream) |
222 * {@link CertificateFactory#generateCertificate(java.io.InputStream) |
223 * generateCertificate}. |
223 * generateCertificate}. |
224 * In addition, <code>inStream</code> may contain a PKCS#7 certificate |
224 * In addition, {@code inStream} may contain a PKCS#7 certificate |
225 * chain. This is a PKCS#7 <i>SignedData</i> object, with the only |
225 * chain. This is a PKCS#7 <i>SignedData</i> object, with the only |
226 * significant field being <i>certificates</i>. In particular, the |
226 * significant field being <i>certificates</i>. In particular, the |
227 * signature and the contents are ignored. This format allows multiple |
227 * signature and the contents are ignored. This format allows multiple |
228 * certificates to be downloaded at once. If no certificates are present, |
228 * certificates to be downloaded at once. If no certificates are present, |
229 * an empty collection is returned. |
229 * an empty collection is returned. |
245 engineGenerateCertificates(InputStream inStream) |
245 engineGenerateCertificates(InputStream inStream) |
246 throws CertificateException; |
246 throws CertificateException; |
247 |
247 |
248 /** |
248 /** |
249 * Generates a certificate revocation list (CRL) object and initializes it |
249 * Generates a certificate revocation list (CRL) object and initializes it |
250 * with the data read from the input stream <code>inStream</code>. |
250 * with the data read from the input stream {@code inStream}. |
251 * |
251 * |
252 * <p>In order to take advantage of the specialized CRL format |
252 * <p>In order to take advantage of the specialized CRL format |
253 * supported by this certificate factory, |
253 * supported by this certificate factory, |
254 * the returned CRL object can be typecast to the corresponding |
254 * the returned CRL object can be typecast to the corresponding |
255 * CRL class. For example, if this certificate |
255 * CRL class. For example, if this certificate |
256 * factory implements X.509 CRLs, the returned CRL object |
256 * factory implements X.509 CRLs, the returned CRL object |
257 * can be typecast to the <code>X509CRL</code> class. |
257 * can be typecast to the {@code X509CRL} class. |
258 * |
258 * |
259 * <p>Note that if the given input stream does not support |
259 * <p>Note that if the given input stream does not support |
260 * {@link java.io.InputStream#mark(int) mark} and |
260 * {@link java.io.InputStream#mark(int) mark} and |
261 * {@link java.io.InputStream#reset() reset}, this method will |
261 * {@link java.io.InputStream#reset() reset}, this method will |
262 * consume the entire input stream. Otherwise, each call to this |
262 * consume the entire input stream. Otherwise, each call to this |
263 * method consumes one CRL and the read position of the input stream |
263 * method consumes one CRL and the read position of the input stream |
264 * is positioned to the next available byte after the inherent |
264 * is positioned to the next available byte after the inherent |
265 * end-of-CRL marker. If the data in the |
265 * end-of-CRL marker. If the data in the |
266 * input stream does not contain an inherent end-of-CRL marker (other |
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 |
267 * than EOF) and there is trailing data after the CRL is parsed, a |
268 * <code>CRLException</code> is thrown. |
268 * {@code CRLException} is thrown. |
269 * |
269 * |
270 * @param inStream an input stream with the CRL data. |
270 * @param inStream an input stream with the CRL data. |
271 * |
271 * |
272 * @return a CRL object initialized with the data |
272 * @return a CRL object initialized with the data |
273 * from the input stream. |
273 * from the input stream. |
277 public abstract CRL engineGenerateCRL(InputStream inStream) |
277 public abstract CRL engineGenerateCRL(InputStream inStream) |
278 throws CRLException; |
278 throws CRLException; |
279 |
279 |
280 /** |
280 /** |
281 * Returns a (possibly empty) collection view of the CRLs read |
281 * Returns a (possibly empty) collection view of the CRLs read |
282 * from the given input stream <code>inStream</code>. |
282 * from the given input stream {@code inStream}. |
283 * |
283 * |
284 * <p>In order to take advantage of the specialized CRL format |
284 * <p>In order to take advantage of the specialized CRL format |
285 * supported by this certificate factory, each element in |
285 * supported by this certificate factory, each element in |
286 * the returned collection view can be typecast to the corresponding |
286 * the returned collection view can be typecast to the corresponding |
287 * CRL class. For example, if this certificate |
287 * CRL class. For example, if this certificate |
288 * factory implements X.509 CRLs, the elements in the returned |
288 * factory implements X.509 CRLs, the elements in the returned |
289 * collection can be typecast to the <code>X509CRL</code> class. |
289 * collection can be typecast to the {@code X509CRL} class. |
290 * |
290 * |
291 * <p>In the case of a certificate factory for X.509 CRLs, |
291 * <p>In the case of a certificate factory for X.509 CRLs, |
292 * <code>inStream</code> may contain a single DER-encoded CRL. |
292 * {@code inStream} may contain a single DER-encoded CRL. |
293 * In addition, <code>inStream</code> may contain a PKCS#7 CRL |
293 * In addition, {@code inStream} may contain a PKCS#7 CRL |
294 * set. This is a PKCS#7 <i>SignedData</i> object, with the only |
294 * set. This is a PKCS#7 <i>SignedData</i> object, with the only |
295 * significant field being <i>crls</i>. In particular, the |
295 * significant field being <i>crls</i>. In particular, the |
296 * signature and the contents are ignored. This format allows multiple |
296 * signature and the contents are ignored. This format allows multiple |
297 * CRLs to be downloaded at once. If no CRLs are present, |
297 * CRLs to be downloaded at once. If no CRLs are present, |
298 * an empty collection is returned. |
298 * an empty collection is returned. |