1 module hunt.security.cert.CertificateFactorySpi; 2 3 import hunt.security.cert.Certificate; 4 import hunt.security.cert.CertPath; 5 import hunt.security.cert.CRL; 6 7 import hunt.collection; 8 import hunt.Exceptions; 9 import hunt.stream.Common; 10 11 12 /** 13 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) 14 * for the {@code CertificateFactory} class. 15 * All the abstract methods in this class must be implemented by each 16 * cryptographic service provider who wishes to supply the implementation 17 * of a certificate factory for a particular certificate type, e.g., X.509. 18 * 19 * <p>Certificate factories are used to generate certificate, certification path 20 * ({@code CertPath}) and certificate revocation list (CRL) objects from 21 * their encodings. 22 * 23 * <p>A certificate factory for X.509 must return certificates that are an 24 * instance of {@code java.security.cert.X509Certificate}, and CRLs 25 * that are an instance of {@code java.security.cert.X509CRL}. 26 * 27 * @author Hemma Prafullchandra 28 * @author Jan Luehe 29 * @author Sean Mullan 30 * 31 * 32 * @see CertificateFactory 33 * @see Certificate 34 * @see X509Certificate 35 * @see CertPath 36 * @see CRL 37 * @see X509CRL 38 * 39 * @since 1.2 40 */ 41 42 abstract class CertificateFactorySpi { 43 44 /** 45 * Generates a certificate object and initializes it with 46 * the data read from the input stream {@code inStream}. 47 * 48 * <p>In order to take advantage of the specialized certificate format 49 * supported by this certificate factory, 50 * the returned certificate object can be typecast to the corresponding 51 * certificate class. For example, if this certificate 52 * factory implements X.509 certificates, the returned certificate object 53 * can be typecast to the {@code X509Certificate} class. 54 * 55 * <p>In the case of a certificate factory for X.509 certificates, the 56 * certificate provided in {@code inStream} must be DER-encoded and 57 * may be supplied in binary or printable (Base64) encoding. If the 58 * certificate is provided in Base64 encoding, it must be bounded at 59 * the beginning by -----BEGIN CERTIFICATE-----, and must be bounded at 60 * the end by -----END CERTIFICATE-----. 61 * 62 * <p>Note that if the given input stream does not support 63 * {@link java.io.InputStream#mark(int) mark} and 64 * {@link java.io.InputStream#reset() reset}, this method will 65 * consume the entire input stream. Otherwise, each call to this 66 * method consumes one certificate and the read position of the input stream 67 * is positioned to the next available byte after the inherent 68 * end-of-certificate marker. If the data in the 69 * input stream does not contain an inherent end-of-certificate marker (other 70 * than EOF) and there is trailing data after the certificate is parsed, a 71 * {@code CertificateException} is thrown. 72 * 73 * @param inStream an input stream with the certificate data. 74 * 75 * @return a certificate object initialized with the data 76 * from the input stream. 77 * 78 * @exception CertificateException on parsing errors. 79 */ 80 abstract Certificate engineGenerateCertificate(InputStream inStream); 81 82 /** 83 * Generates a {@code CertPath} object and initializes it with 84 * the data read from the {@code InputStream} inStream. The data 85 * is assumed to be in the default encoding. 86 * 87 * <p> This method was added to version 1.4 of the Java 2 Platform 88 * Standard Edition. In order to maintain backwards compatibility with 89 * existing service providers, this method cannot be {@code abstract} 90 * and by default throws an {@code UnsupportedOperationException}. 91 * 92 * @param inStream an {@code InputStream} containing the data 93 * @return a {@code CertPath} initialized with the data from the 94 * {@code InputStream} 95 * @exception CertificateException if an exception occurs while decoding 96 * @exception UnsupportedOperationException if the method is not supported 97 * @since 1.4 98 */ 99 CertPath engineGenerateCertPath(InputStream inStream) 100 { 101 throw new UnsupportedOperationException(""); 102 } 103 104 /** 105 * Generates a {@code CertPath} object and initializes it with 106 * the data read from the {@code InputStream} inStream. The data 107 * is assumed to be in the specified encoding. 108 * 109 * <p> This method was added to version 1.4 of the Java 2 Platform 110 * Standard Edition. In order to maintain backwards compatibility with 111 * existing service providers, this method cannot be {@code abstract} 112 * and by default throws an {@code UnsupportedOperationException}. 113 * 114 * @param inStream an {@code InputStream} containing the data 115 * @param encoding the encoding used for the data 116 * @return a {@code CertPath} initialized with the data from the 117 * {@code InputStream} 118 * @exception CertificateException if an exception occurs while decoding or 119 * the encoding requested is not supported 120 * @exception UnsupportedOperationException if the method is not supported 121 * @since 1.4 122 */ 123 CertPath engineGenerateCertPath(InputStream inStream, string encoding) 124 { 125 throw new UnsupportedOperationException(""); 126 } 127 128 /** 129 * Generates a {@code CertPath} object and initializes it with 130 * a {@code List} of {@code Certificate}s. 131 * <p> 132 * The certificates supplied must be of a type supported by the 133 * {@code CertificateFactory}. They will be copied out of the supplied 134 * {@code List} object. 135 * 136 * <p> This method was added to version 1.4 of the Java 2 Platform 137 * Standard Edition. In order to maintain backwards compatibility with 138 * existing service providers, this method cannot be {@code abstract} 139 * and by default throws an {@code UnsupportedOperationException}. 140 * 141 * @param certificates a {@code List} of {@code Certificate}s 142 * @return a {@code CertPath} initialized with the supplied list of 143 * certificates 144 * @exception CertificateException if an exception occurs 145 * @exception UnsupportedOperationException if the method is not supported 146 * @since 1.4 147 */ 148 CertPath engineGenerateCertPath(List!(Certificate) certificates) 149 { 150 throw new UnsupportedOperationException(""); 151 } 152 153 /** 154 * Returns an iteration of the {@code CertPath} encodings supported 155 * by this certificate factory, with the default encoding first. See 156 * the CertPath Encodings section in the <a href= 157 * "{@docRoot}/../technotes/guides/security/StandardNames.html#CertPathEncodings"> 158 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 159 * for information about standard encoding names. 160 * <p> 161 * Attempts to modify the returned {@code Iterator} via its 162 * {@code remove} method result in an 163 * {@code UnsupportedOperationException}. 164 * 165 * <p> This method was added to version 1.4 of the Java 2 Platform 166 * Standard Edition. In order to maintain backwards compatibility with 167 * existing service providers, this method cannot be {@code abstract} 168 * and by default throws an {@code UnsupportedOperationException}. 169 * 170 * @return an {@code Iterator} over the names of the supported 171 * {@code CertPath} encodings (as {@code string}s) 172 * @exception UnsupportedOperationException if the method is not supported 173 * @since 1.4 174 */ 175 Iterator!string engineGetCertPathEncodings() { 176 throw new UnsupportedOperationException(""); 177 } 178 179 /** 180 * Returns a (possibly empty) collection view of the certificates read 181 * from the given input stream {@code inStream}. 182 * 183 * <p>In order to take advantage of the specialized certificate format 184 * supported by this certificate factory, each element in 185 * the returned collection view can be typecast to the corresponding 186 * certificate class. For example, if this certificate 187 * factory implements X.509 certificates, the elements in the returned 188 * collection can be typecast to the {@code X509Certificate} class. 189 * 190 * <p>In the case of a certificate factory for X.509 certificates, 191 * {@code inStream} may contain a single DER-encoded certificate 192 * in the formats described for 193 * {@link CertificateFactory#generateCertificate(java.io.InputStream) 194 * generateCertificate}. 195 * In addition, {@code inStream} may contain a PKCS#7 certificate 196 * chain. This is a PKCS#7 <i>SignedData</i> object, with the only 197 * significant field being <i>certificates</i>. In particular, the 198 * signature and the contents are ignored. This format allows multiple 199 * certificates to be downloaded at once. If no certificates are present, 200 * an empty collection is returned. 201 * 202 * <p>Note that if the given input stream does not support 203 * {@link java.io.InputStream#mark(int) mark} and 204 * {@link java.io.InputStream#reset() reset}, this method will 205 * consume the entire input stream. 206 * 207 * @param inStream the input stream with the certificates. 208 * 209 * @return a (possibly empty) collection view of 210 * java.security.cert.Certificate objects 211 * initialized with the data from the input stream. 212 * 213 * @exception CertificateException on parsing errors. 214 */ 215 abstract Collection!Certificate 216 engineGenerateCertificates(InputStream inStream); 217 218 /** 219 * Generates a certificate revocation list (CRL) object and initializes it 220 * with the data read from the input stream {@code inStream}. 221 * 222 * <p>In order to take advantage of the specialized CRL format 223 * supported by this certificate factory, 224 * the returned CRL object can be typecast to the corresponding 225 * CRL class. For example, if this certificate 226 * factory implements X.509 CRLs, the returned CRL object 227 * can be typecast to the {@code X509CRL} class. 228 * 229 * <p>Note that if the given input stream does not support 230 * {@link java.io.InputStream#mark(int) mark} and 231 * {@link java.io.InputStream#reset() reset}, this method will 232 * consume the entire input stream. Otherwise, each call to this 233 * method consumes one CRL and the read position of the input stream 234 * is positioned to the next available byte after the inherent 235 * end-of-CRL marker. If the data in the 236 * input stream does not contain an inherent end-of-CRL marker (other 237 * than EOF) and there is trailing data after the CRL is parsed, a 238 * {@code CRLException} is thrown. 239 * 240 * @param inStream an input stream with the CRL data. 241 * 242 * @return a CRL object initialized with the data 243 * from the input stream. 244 * 245 * @exception CRLException on parsing errors. 246 */ 247 abstract CRL engineGenerateCRL(InputStream inStream); 248 249 /** 250 * Returns a (possibly empty) collection view of the CRLs read 251 * from the given input stream {@code inStream}. 252 * 253 * <p>In order to take advantage of the specialized CRL format 254 * supported by this certificate factory, each element in 255 * the returned collection view can be typecast to the corresponding 256 * CRL class. For example, if this certificate 257 * factory implements X.509 CRLs, the elements in the returned 258 * collection can be typecast to the {@code X509CRL} class. 259 * 260 * <p>In the case of a certificate factory for X.509 CRLs, 261 * {@code inStream} may contain a single DER-encoded CRL. 262 * In addition, {@code inStream} may contain a PKCS#7 CRL 263 * set. This is a PKCS#7 <i>SignedData</i> object, with the only 264 * significant field being <i>crls</i>. In particular, the 265 * signature and the contents are ignored. This format allows multiple 266 * CRLs to be downloaded at once. If no CRLs are present, 267 * an empty collection is returned. 268 * 269 * <p>Note that if the given input stream does not support 270 * {@link java.io.InputStream#mark(int) mark} and 271 * {@link java.io.InputStream#reset() reset}, this method will 272 * consume the entire input stream. 273 * 274 * @param inStream the input stream with the CRLs. 275 * 276 * @return a (possibly empty) collection view of 277 * java.security.cert.CRL objects initialized with the data from the input 278 * stream. 279 * 280 * @exception CRLException on parsing errors. 281 */ 282 abstract Collection!CRL engineGenerateCRLs(InputStream inStream); 283 }