/* * Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.security.cert; import java.io.InputStream; import java.util.Collection; import java.util.Iterator; import java.util.List; import java.security.Provider; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; /** * This class defines the Service Provider Interface (SPI) * for the CertificateFactory class. * All the abstract methods in this class must be implemented by each * cryptographic service provider who wishes to supply the implementation * of a certificate factory for a particular certificate type, e.g., X.509. * *

Certificate factories are used to generate certificate, certification path * (CertPath) and certificate revocation list (CRL) objects from * their encodings. * *

A certificate factory for X.509 must return certificates that are an * instance of java.security.cert.X509Certificate, and CRLs * that are an instance of java.security.cert.X509CRL. * * @author Hemma Prafullchandra * @author Jan Luehe * @author Sean Mullan * * * @see CertificateFactory * @see Certificate * @see X509Certificate * @see CertPath * @see CRL * @see X509CRL * * @since 1.2 */ public abstract class CertificateFactorySpi { /** * Generates a certificate object and initializes it with * the data read from the input stream inStream. * *

In order to take advantage of the specialized certificate format * supported by this certificate factory, * the returned certificate object can be typecast to the corresponding * certificate class. For example, if this certificate * factory implements X.509 certificates, the returned certificate object * can be typecast to the X509Certificate class. * *

In the case of a certificate factory for X.509 certificates, the * certificate provided in inStream must be DER-encoded and * may be supplied in binary or printable (Base64) encoding. If the * certificate is provided in Base64 encoding, it must be bounded at * the beginning by -----BEGIN CERTIFICATE-----, and must be bounded at * the end by -----END CERTIFICATE-----. * *

Note that if the given input stream does not support * {@link java.io.InputStream#mark(int) mark} and * {@link java.io.InputStream#reset() reset}, this method will * consume the entire input stream. Otherwise, each call to this * method consumes one certificate and the read position of the input stream * is positioned to the next available byte after the inherent * end-of-certificate marker. If the data in the * input stream does not contain an inherent end-of-certificate marker (other * than EOF) and there is trailing data after the certificate is parsed, a * CertificateException is thrown. * * @param inStream an input stream with the certificate data. * * @return a certificate object initialized with the data * from the input stream. * * @exception CertificateException on parsing errors. */ public abstract Certificate engineGenerateCertificate(InputStream inStream) throws CertificateException; /** * Generates a CertPath object and initializes it with * the data read from the InputStream inStream. The data * is assumed to be in the default encoding. * *

This method was added to version 1.4 of the Java 2 Platform * Standard Edition. In order to maintain backwards compatibility with * existing service providers, this method cannot be abstract * and by default throws an UnsupportedOperationException. * * @param inStream an InputStream containing the data * @return a CertPath initialized with the data from the * InputStream * @exception CertificateException if an exception occurs while decoding * @exception UnsupportedOperationException if the method is not supported * @since 1.4 */ public CertPath engineGenerateCertPath(InputStream inStream) throws CertificateException { throw new UnsupportedOperationException(); } /** * Generates a CertPath object and initializes it with * the data read from the InputStream inStream. The data * is assumed to be in the specified encoding. * *

This method was added to version 1.4 of the Java 2 Platform * Standard Edition. In order to maintain backwards compatibility with * existing service providers, this method cannot be abstract * and by default throws an UnsupportedOperationException. * * @param inStream an InputStream containing the data * @param encoding the encoding used for the data * @return a CertPath initialized with the data from the * InputStream * @exception CertificateException if an exception occurs while decoding or * the encoding requested is not supported * @exception UnsupportedOperationException if the method is not supported * @since 1.4 */ public CertPath engineGenerateCertPath(InputStream inStream, String encoding) throws CertificateException { throw new UnsupportedOperationException(); } /** * Generates a CertPath object and initializes it with * a List of Certificates. *

* The certificates supplied must be of a type supported by the * CertificateFactory. They will be copied out of the supplied * List object. * *

This method was added to version 1.4 of the Java 2 Platform * Standard Edition. In order to maintain backwards compatibility with * existing service providers, this method cannot be abstract * and by default throws an UnsupportedOperationException. * * @param certificates a List of Certificates * @return a CertPath initialized with the supplied list of * certificates * @exception CertificateException if an exception occurs * @exception UnsupportedOperationException if the method is not supported * @since 1.4 */ public CertPath engineGenerateCertPath(List certificates) throws CertificateException { throw new UnsupportedOperationException(); } /** * Returns an iteration of the CertPath encodings supported * by this certificate factory, with the default encoding first. See * the CertPath Encodings section in the * Java Cryptography Architecture Standard Algorithm Name Documentation * for information about standard encoding names. *

* Attempts to modify the returned Iterator via its * remove method result in an * UnsupportedOperationException. * *

This method was added to version 1.4 of the Java 2 Platform * Standard Edition. In order to maintain backwards compatibility with * existing service providers, this method cannot be abstract * and by default throws an UnsupportedOperationException. * * @return an Iterator over the names of the supported * CertPath encodings (as Strings) * @exception UnsupportedOperationException if the method is not supported * @since 1.4 */ public Iterator engineGetCertPathEncodings() { throw new UnsupportedOperationException(); } /** * Returns a (possibly empty) collection view of the certificates read * from the given input stream inStream. * *

In order to take advantage of the specialized certificate format * supported by this certificate factory, each element in * the returned collection view can be typecast to the corresponding * certificate class. For example, if this certificate * factory implements X.509 certificates, the elements in the returned * collection can be typecast to the X509Certificate class. * *

In the case of a certificate factory for X.509 certificates, * inStream may contain a single DER-encoded certificate * in the formats described for * {@link CertificateFactory#generateCertificate(java.io.InputStream) * generateCertificate}. * In addition, inStream may contain a PKCS#7 certificate * chain. This is a PKCS#7 SignedData object, with the only * significant field being certificates. In particular, the * signature and the contents are ignored. This format allows multiple * certificates to be downloaded at once. If no certificates are present, * an empty collection is returned. * *

Note that if the given input stream does not support * {@link java.io.InputStream#mark(int) mark} and * {@link java.io.InputStream#reset() reset}, this method will * consume the entire input stream. * * @param inStream the input stream with the certificates. * * @return a (possibly empty) collection view of * java.security.cert.Certificate objects * initialized with the data from the input stream. * * @exception CertificateException on parsing errors. */ public abstract Collection engineGenerateCertificates(InputStream inStream) throws CertificateException; /** * Generates a certificate revocation list (CRL) object and initializes it * with the data read from the input stream inStream. * *

In order to take advantage of the specialized CRL format * supported by this certificate factory, * the returned CRL object can be typecast to the corresponding * CRL class. For example, if this certificate * factory implements X.509 CRLs, the returned CRL object * can be typecast to the X509CRL class. * *

Note that if the given input stream does not support * {@link java.io.InputStream#mark(int) mark} and * {@link java.io.InputStream#reset() reset}, this method will * consume the entire input stream. Otherwise, each call to this * method consumes one CRL and the read position of the input stream * is positioned to the next available byte after the inherent * end-of-CRL marker. If the data in the * input stream does not contain an inherent end-of-CRL marker (other * than EOF) and there is trailing data after the CRL is parsed, a * CRLException is thrown. * * @param inStream an input stream with the CRL data. * * @return a CRL object initialized with the data * from the input stream. * * @exception CRLException on parsing errors. */ public abstract CRL engineGenerateCRL(InputStream inStream) throws CRLException; /** * Returns a (possibly empty) collection view of the CRLs read * from the given input stream inStream. * *

In order to take advantage of the specialized CRL format * supported by this certificate factory, each element in * the returned collection view can be typecast to the corresponding * CRL class. For example, if this certificate * factory implements X.509 CRLs, the elements in the returned * collection can be typecast to the X509CRL class. * *

In the case of a certificate factory for X.509 CRLs, * inStream may contain a single DER-encoded CRL. * In addition, inStream may contain a PKCS#7 CRL * set. This is a PKCS#7 SignedData object, with the only * significant field being crls. In particular, the * signature and the contents are ignored. This format allows multiple * CRLs to be downloaded at once. If no CRLs are present, * an empty collection is returned. * *

Note that if the given input stream does not support * {@link java.io.InputStream#mark(int) mark} and * {@link java.io.InputStream#reset() reset}, this method will * consume the entire input stream. * * @param inStream the input stream with the CRLs. * * @return a (possibly empty) collection view of * java.security.cert.CRL objects initialized with the data from the input * stream. * * @exception CRLException on parsing errors. */ public abstract Collection engineGenerateCRLs (InputStream inStream) throws CRLException; }