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. package java.security.cert;
  11. import java.io.InputStream;
  12. import java.util.Collection;
  13. import java.security.Provider;
  14. import java.security.NoSuchAlgorithmException;
  15. import java.security.NoSuchProviderException;
  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.9, 02/02/00
  34. *
  35. * @see CertificateFactory
  36. * @see Certificate
  37. * @see X509Certificate
  38. * @see CRL
  39. * @see X509CRL
  40. *
  41. * @since 1.2
  42. */
  43. public abstract class CertificateFactorySpi {
  44. /**
  45. * Generates a certificate object and initializes it with
  46. * the data read from the input stream <code>inStream</code>.
  47. *
  48. * <p>The given input stream <code>inStream</code> must contain a single
  49. * certificate.
  50. *
  51. * <p>In order to take advantage of the specialized certificate format
  52. * supported by this certificate factory,
  53. * the returned certificate object can be typecast to the corresponding
  54. * certificate class. For example, if this certificate
  55. * factory implements X.509 certificates, the returned certificate object
  56. * can be typecast to the <code>X509Certificate</code> class.
  57. *
  58. * <p>In the case of a certificate factory for X.509 certificates, the
  59. * certificate provided in <code>inStream</code> must be DER-encoded and
  60. * may be supplied in binary or printable (Base64) encoding. If the
  61. * certificate is provided in Base64 encoding, it must be bounded at
  62. * the beginning by -----BEGIN CERTIFICATE-----, and must be bounded at
  63. * the end by -----END CERTIFICATE-----.
  64. *
  65. * <p>Note that if the given input stream does not support
  66. * {@link java.io.InputStream#mark(int) mark} and
  67. * {@link java.io.InputStream#reset() reset}, this method will
  68. * consume the entire input stream.
  69. *
  70. * @param inStream an input stream with the certificate data.
  71. *
  72. * @return a certificate object initialized with the data
  73. * from the input stream.
  74. *
  75. * @exception CertificateException on parsing errors.
  76. */
  77. public abstract Certificate engineGenerateCertificate(InputStream inStream)
  78. throws CertificateException;
  79. /**
  80. * Returns a (possibly empty) collection view of the certificates read
  81. * from the given input stream <code>inStream</code>.
  82. *
  83. * <p>In order to take advantage of the specialized certificate format
  84. * supported by this certificate factory, each element in
  85. * the returned collection view can be typecast to the corresponding
  86. * certificate class. For example, if this certificate
  87. * factory implements X.509 certificates, the elements in the returned
  88. * collection can be typecast to the <code>X509Certificate</code> class.
  89. *
  90. * <p>In the case of a certificate factory for X.509 certificates,
  91. * <code>inStream</code> may contain a single DER-encoded certificate
  92. * in the formats described for
  93. * {@link CertificateFactory#generateCertificate(java.io.InputStream)
  94. * generateCertificate}.
  95. * In addition, <code>inStream</code> may contain a PKCS#7 certificate
  96. * chain. This is a PKCS#7 <i>SignedData</i> object, with the only
  97. * significant field being <i>certificates</i>. In particular, the
  98. * signature and the contents are ignored. This format allows multiple
  99. * certificates to be downloaded at once. If no certificates are present,
  100. * an empty collection is returned.
  101. *
  102. * <p>Note that if the given input stream does not support
  103. * {@link java.io.InputStream#mark(int) mark} and
  104. * {@link java.io.InputStream#reset() reset}, this method will
  105. * consume the entire input stream.
  106. *
  107. * @param inStream the input stream with the certificates.
  108. *
  109. * @return a (possibly empty) collection view of
  110. * java.security.cert.Certificate objects
  111. * initialized with the data from the input stream.
  112. *
  113. * @exception CertificateException on parsing errors.
  114. */
  115. public abstract Collection engineGenerateCertificates(InputStream inStream)
  116. throws CertificateException;
  117. /**
  118. * Generates a certificate revocation list (CRL) object and initializes it
  119. * with the data read from the input stream <code>inStream</code>.
  120. *
  121. * <p>In order to take advantage of the specialized CRL format
  122. * supported by this certificate factory,
  123. * the returned CRL object can be typecast to the corresponding
  124. * CRL class. For example, if this certificate
  125. * factory implements X.509 CRLs, the returned CRL object
  126. * can be typecast to the <code>X509CRL</code> class.
  127. *
  128. * <p>Note that if the given input stream does not support
  129. * {@link java.io.InputStream#mark(int) mark} and
  130. * {@link java.io.InputStream#reset() reset}, this method will
  131. * consume the entire input stream.
  132. *
  133. * @param inStream an input stream with the CRL data.
  134. *
  135. * @return a CRL object initialized with the data
  136. * from the input stream.
  137. *
  138. * @exception CRLException on parsing errors.
  139. */
  140. public abstract CRL engineGenerateCRL(InputStream inStream)
  141. throws CRLException;
  142. /**
  143. * Returns a (possibly empty) collection view of the CRLs read
  144. * from the given input stream <code>inStream</code>.
  145. *
  146. * <p>In order to take advantage of the specialized CRL format
  147. * supported by this certificate factory, each element in
  148. * the returned collection view can be typecast to the corresponding
  149. * CRL class. For example, if this certificate
  150. * factory implements X.509 CRLs, the elements in the returned
  151. * collection can be typecast to the <code>X509CRL</code> class.
  152. *
  153. * <p>In the case of a certificate factory for X.509 CRLs,
  154. * <code>inStream</code> may contain a single DER-encoded CRL.
  155. * In addition, <code>inStream</code> may contain a PKCS#7 CRL
  156. * set. This is a PKCS#7 <i>SignedData</i> object, with the only
  157. * significant field being <i>crls</i>. In particular, the
  158. * signature and the contents are ignored. This format allows multiple
  159. * CRLs to be downloaded at once. If no CRLs are present,
  160. * an empty collection is returned.
  161. *
  162. * <p>Note that if the given input stream does not support
  163. * {@link java.io.InputStream#mark(int) mark} and
  164. * {@link java.io.InputStream#reset() reset}, this method will
  165. * consume the entire input stream.
  166. *
  167. * @param inStream the input stream with the CRLs.
  168. *
  169. * @return a (possibly empty) collection view of
  170. * java.security.cert.CRL objects initialized with the data from the input
  171. * stream.
  172. *
  173. * @exception CRLException on parsing errors.
  174. */
  175. public abstract Collection engineGenerateCRLs(InputStream inStream)
  176. throws CRLException;
  177. }