1. /*

  2.  * @(#)CertificateFactorySpi.java	1.9 00/02/02

  3.  *

  4.  * Copyright 1998-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.security.cert;

  12. 

  13. import java.io.InputStream;

  14. import java.util.Collection;

  15. import java.security.Provider;

  16. import java.security.NoSuchAlgorithmException;

  17. import java.security.NoSuchProviderException;

  18. 

  19. /**

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

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

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

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

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

  25.  *

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

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

  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.  *

  36.  * @version 1.9, 02/02/00

  37.  *

  38.  * @see CertificateFactory

  39.  * @see Certificate

  40.  * @see X509Certificate

  41.  * @see CRL

  42.  * @see X509CRL

  43.  *

  44.  * @since 1.2

  45.  */

  46. 

  47. public abstract class CertificateFactorySpi {

  48. 

  49.     /**

  50.      * Generates a certificate object and initializes it with

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

  52.      *

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

  54.      * certificate.

  55.      *

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

  57.      * supported by this certificate factory,

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

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

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

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

  62.      *

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

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

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

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

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

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

  69.      *

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

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

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

  73.      * consume the entire input stream.

  74.      *

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

  76.      *

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

  78.      * from the input stream.

  79.      *

  80.      * @exception CertificateException on parsing errors.

  81.      */

  82.     public abstract Certificate engineGenerateCertificate(InputStream inStream)

  83.         throws CertificateException;

  84. 

  85.     /**

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

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

  88.      *

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

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

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

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

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

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

  95.      *

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

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

  98.      * in the formats described for 

  99.      * {@link CertificateFactory#generateCertificate(java.io.InputStream) 

  100.      * generateCertificate}.

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

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

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

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

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

  106.      * an empty collection is returned.

  107.      *

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

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

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

  111.      * consume the entire input stream.

  112.      *

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

  114.      *

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

  116.      * java.security.cert.Certificate objects

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

  118.      *

  119.      * @exception CertificateException on parsing errors.

  120.      */

  121.     public abstract Collection engineGenerateCertificates(InputStream inStream)

  122.         throws CertificateException;

  123. 

  124.     /**

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

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

  127.      *

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

  129.      * supported by this certificate factory,

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

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

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

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

  134.      *

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

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

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

  138.      * consume the entire input stream.

  139.      *

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

  141.      *

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

  143.      * from the input stream.

  144.      *

  145.      * @exception CRLException on parsing errors.

  146.      */

  147.     public abstract CRL engineGenerateCRL(InputStream inStream)

  148.         throws CRLException;

  149. 

  150.     /**

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

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

  153.      *

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

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

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

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

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

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

  160.      *

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

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

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

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

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

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

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

  168.      * an empty collection is returned.

  169.      *

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

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

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

  173.      * consume the entire input stream.

  174.      *

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

  176.      *

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

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

  179.      * stream.

  180.      *

  181.      * @exception CRLException on parsing errors.

  182.      */

  183.     public abstract Collection engineGenerateCRLs(InputStream inStream)

  184.         throws CRLException;

  185. }