src/share/classes/java/security/cert/CertificateFactorySpi.java

Print this page


   1 /*
   2  * Copyright (c) 1998, 2011, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * 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 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      * the CertPath Encodings section in the <a href=
 186      * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathEncodings">
 187      * Java Cryptography Architecture Standard Algorithm Name Documentation</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 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
   1 /*
   2  * Copyright (c) 1998, 2013, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * 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} 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}) 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}, and CRLs
  49  * that are an instance of {@code java.security.cert.X509CRL}.
  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}.
  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} class.
  78      *
  79      * <p>In the case of a certificate factory for X.509 certificates, the
  80      * certificate provided in {@code inStream} 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 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} 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} object and initializes it with
 109      * the data read from the {@code InputStream} 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}
 115      * and by default throws an {@code UnsupportedOperationException}.
 116      *
 117      * @param inStream an {@code InputStream} containing the data
 118      * @return a {@code CertPath} initialized with the data from the
 119      *   {@code InputStream}
 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} object and initializes it with
 132      * the data read from the {@code InputStream} 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}
 138      * and by default throws an {@code UnsupportedOperationException}.
 139      *
 140      * @param inStream an {@code InputStream} containing the data
 141      * @param encoding the encoding used for the data
 142      * @return a {@code CertPath} initialized with the data from the
 143      *   {@code InputStream}
 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} object and initializes it with
 157      * a {@code List} of {@code Certificate}s.
 158      * <p>
 159      * The certificates supplied must be of a type supported by the
 160      * {@code CertificateFactory}. They will be copied out of the supplied
 161      * {@code List} 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}
 166      * and by default throws an {@code UnsupportedOperationException}.
 167      *
 168      * @param certificates a {@code List} of {@code Certificate}s
 169      * @return a {@code CertPath} 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} encodings supported
 184      * by this certificate factory, with the default encoding first. See
 185      * the CertPath Encodings section in the <a href=
 186      * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathEncodings">
 187      * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
 188      * for information about standard encoding names.
 189      * <p>
 190      * Attempts to modify the returned {@code Iterator} via its
 191      * {@code remove} method result in an
 192      * {@code UnsupportedOperationException}.
 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}
 197      * and by default throws an {@code UnsupportedOperationException}.
 198      *
 199      * @return an {@code Iterator} over the names of the supported
 200      *         {@code CertPath} encodings (as {@code String}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}.
 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} class.
 218      *
 219      * <p>In the case of a certificate factory for X.509 certificates,
 220      * {@code inStream} 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} 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}.
 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} 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 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} 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}.
 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} class.
 290      *
 291      * <p>In the case of a certificate factory for X.509 CRLs,
 292      * {@code inStream} may contain a single DER-encoded 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
 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