1. /*

  2.  * @(#)CertificateFactorySpi.java	1.5 01/11/29

  3.  *

  4.  * Copyright 2002 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.security.Provider;

  13. import java.security.NoSuchAlgorithmException;

  14. import java.security.NoSuchProviderException;

  15. 

  16. /**

  17.  * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)

  18.  * for the <code>CertificateFactory</code> class.

  19.  * All the abstract methods in this class must be implemented by each

  20.  * cryptographic service provider who wishes to supply the implementation

  21.  * of a certificate factory for a particular certificate type, e.g., X.509.

  22.  *

  23.  * <p>Certificate factories are used to generate certificate and certificate

  24.  * revocation list (CRL) objects from their encoding.

  25.  *

  26.  * <p>A certificate factory for X.509 must return certificates that are an

  27.  * instance of <code>java.security.cert.X509Certificate</code>, and CRLs

  28.  * that are an instance of <code>java.security.cert.X509CRL</code>.

  29.  *

  30.  * @author Hemma Prafullchandra

  31.  * @author Jan Luehe

  32.  *

  33.  * @version 1.5

  34.  *

  35.  * @see CertificateFactory

  36.  * @see Certificate

  37.  * @see X509Certificate

  38.  * @see CRL

  39.  * @see X509CRL

  40.  *

  41.  * @since JDK1.2

  42.  */

  43. 

  44. public abstract class CertificateFactorySpi {

  45. 

  46.     /**

  47.      * Generates a certificate object and initializes it with

  48.      * the data read from the input stream <code>inStream</code>.

  49.      *

  50.      * <p>The given input stream <code>inStream</code> must contain a single

  51.      * certificate.

  52.      *

  53.      * <p>In order to take advantage of the specialized certificate format

  54.      * supported by this certificate factory,

  55.      * the returned certificate object can be typecast to the corresponding

  56.      * certificate class. For example, if this certificate

  57.      * factory implements X.509 certificates, the returned certificate object

  58.      * can be typecast to the <code>X509Certificate</code> class.

  59.      *

  60.      * <p>In the case of a certificate factory for X.509 certificates, the

  61.      * certificate provided in <code>inStream</code> must be DER-encoded and

  62.      * may be supplied in binary or printable (Base64) encoding. If the

  63.      * certificate is provided in Base64 encoding, it must be bounded at

  64.      * the beginning by -----BEGIN CERTIFICATE-----, and must be bounded at

  65.      * the end by -----END CERTIFICATE-----.

  66.      *

  67.      * <p>Note that if the given input stream does not support

  68.      * {@link java.io.InputStream#mark(int) mark} and

  69.      * {@link java.io.InputStream#reset() reset}, this method will

  70.      * consume the entire input stream.

  71.      *

  72.      * @param inStream an input stream with the certificate data.

  73.      *

  74.      * @return a certificate object initialized with the data

  75.      * from the input stream.

  76.      *

  77.      * @exception CertificateException on parsing errors.

  78.      */

  79.     public abstract Certificate engineGenerateCertificate(InputStream inStream)

  80.         throws CertificateException;

  81. 

  82.     /**

  83.      * Returns a (possibly empty) collection view of the certificates read

  84.      * from the given input stream <code>inStream</code>.

  85.      *

  86.      * <p>In order to take advantage of the specialized certificate format

  87.      * supported by this certificate factory, each element in

  88.      * the returned collection view can be typecast to the corresponding

  89.      * certificate class. For example, if this certificate

  90.      * factory implements X.509 certificates, the elements in the returned

  91.      * collection can be typecast to the <code>X509Certificate</code> class.

  92.      *

  93.      * <p>In the case of a certificate factory for X.509 certificates,

  94.      * <code>inStream</code> may contain a single DER-encoded certificate

  95.      * in the formats described for 

  96.      * {@link #generateCertificate(java.io.InputStream) generateCertificate}.

  97.      * In addition, <code>inStream</code> may contain a PKCS#7 certificate

  98.      * chain. This is a PKCS#7 <i>SignedData</i> object, with the only

  99.      * significant field being <i>certificates</i>. In particular, the

  100.      * signature and the contents are ignored. This format allows multiple

  101.      * certificates to be downloaded at once. If no certificates are present,

  102.      * an empty collection is returned.

  103.      *

  104.      * <p>Note that if the given input stream does not support

  105.      * {@link java.io.InputStream#mark(int) mark} and

  106.      * {@link java.io.InputStream#reset() reset}, this method will

  107.      * consume the entire input stream.

  108.      *

  109.      * @param inStream the input stream with the certificates.

  110.      *

  111.      * @return a (possibly empty) collection view of

  112.      * java.security.cert.Certificate objects

  113.      * initialized with the data from the input stream.

  114.      *

  115.      * @exception CertificateException on parsing errors.

  116.      */

  117.     public abstract Collection engineGenerateCertificates(InputStream inStream)

  118.         throws CertificateException;

  119. 

  120.     /**

  121.      * Generates a certificate revocation list (CRL) object and initializes it

  122.      * with the data read from the input stream <code>inStream</code>.

  123.      *

  124.      * <p>In order to take advantage of the specialized CRL format

  125.      * supported by this certificate factory,

  126.      * the returned CRL object can be typecast to the corresponding

  127.      * CRL class. For example, if this certificate

  128.      * factory implements X.509 CRLs, the returned CRL object

  129.      * can be typecast to the <code>X509CRL</code> class.

  130.      *

  131.      * <p>Note that if the given input stream does not support

  132.      * {@link java.io.InputStream#mark(int) mark} and

  133.      * {@link java.io.InputStream#reset() reset}, this method will

  134.      * consume the entire input stream.

  135.      *

  136.      * @param inStream an input stream with the CRL data.

  137.      *

  138.      * @return a CRL object initialized with the data

  139.      * from the input stream.

  140.      *

  141.      * @exception CRLException on parsing errors.

  142.      */

  143.     public abstract CRL engineGenerateCRL(InputStream inStream)

  144.         throws CRLException;

  145. 

  146.     /**

  147.      * Returns a (possibly empty) collection view of the CRLs read

  148.      * from the given input stream <code>inStream</code>.

  149.      *

  150.      * <p>In order to take advantage of the specialized CRL format

  151.      * supported by this certificate factory, each element in

  152.      * the returned collection view can be typecast to the corresponding

  153.      * CRL class. For example, if this certificate

  154.      * factory implements X.509 CRLs, the elements in the returned

  155.      * collection can be typecast to the <code>X509CRL</code> class.

  156.      *

  157.      * <p>In the case of a certificate factory for X.509 CRLs,

  158.      * <code>inStream</code> may contain a single DER-encoded CRL.

  159.      * In addition, <code>inStream</code> may contain a PKCS#7 CRL

  160.      * set. This is a PKCS#7 <i>SignedData</i> object, with the only

  161.      * significant field being <i>crls</i>. In particular, the

  162.      * signature and the contents are ignored. This format allows multiple

  163.      * CRLs to be downloaded at once. If no CRLs are present,

  164.      * an empty collection is returned.

  165.      *

  166.      * <p>Note that if the given input stream does not support

  167.      * {@link java.io.InputStream#mark(int) mark} and

  168.      * {@link java.io.InputStream#reset() reset}, this method will

  169.      * consume the entire input stream.

  170.      *

  171.      * @param inStream the input stream with the CRLs.

  172.      *

  173.      * @return a (possibly empty) collection view of

  174.      * java.security.cert.CRL objects initialized with the data from the input

  175.      * stream.

  176.      *

  177.      * @exception CRLException on parsing errors.

  178.      */

  179.     public abstract Collection engineGenerateCRLs(InputStream inStream)

  180.         throws CRLException;

  181. }