1 /*
2 * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26
27 package javax.security.cert;
28
29 import java.io.InputStream;
30 import java.lang.Class;
31 import java.lang.reflect.Constructor;
32 import java.lang.reflect.InvocationTargetException;
33 import java.security.Security;
34
35 import java.math.BigInteger;
36 import java.security.AccessController;
37 import java.security.Principal;
38 import java.security.PrivilegedAction;
39 import java.security.PublicKey;
40 import java.util.BitSet;
41 import java.util.Date;
42
43 /**
44 * Abstract class for X.509 v1 certificates. This provides a standard
45 * way to access all the version 1 attributes of an X.509 certificate.
46 * Attributes that are specific to X.509 v2 or v3 are not available
47 * through this interface. Future API evolution will provide full access to
48 * complete X.509 v3 attributes.
49 * <p>
50 * The basic X.509 format was defined by
51 * ISO/IEC and ANSI X9 and is described below in ASN.1:
52 * <pre>
53 * Certificate ::= SEQUENCE {
54 * tbsCertificate TBSCertificate,
55 * signatureAlgorithm AlgorithmIdentifier,
56 * signature BIT STRING }
57 * </pre>
58 * <p>
59 * These certificates are widely used to support authentication and
60 * other functionality in Internet security systems. Common applications
61 * include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL),
62 * code signing for trusted software distribution, and Secure Electronic
63 * Transactions (SET).
64 * <p>
65 * These certificates are managed and vouched for by <em>Certificate
66 * Authorities</em> (CAs). CAs are services which create certificates by
67 * placing data in the X.509 standard format and then digitally signing
68 * that data. CAs act as trusted third parties, making introductions
69 * between principals who have no direct knowledge of each other.
70 * CA certificates are either signed by themselves, or by some other
71 * CA such as a "root" CA.
72 * <p>
73 * The ASN.1 definition of {@code tbsCertificate} is:
74 * <pre>
75 * TBSCertificate ::= SEQUENCE {
76 * version [0] EXPLICIT Version DEFAULT v1,
77 * serialNumber CertificateSerialNumber,
78 * signature AlgorithmIdentifier,
79 * issuer Name,
80 * validity Validity,
81 * subject Name,
82 * subjectPublicKeyInfo SubjectPublicKeyInfo,
83 * }
84 * </pre>
85 * <p>
86 * Here is sample code to instantiate an X.509 certificate:
87 * <pre>
88 * InputStream inStream = new FileInputStream("fileName-of-cert");
89 * X509Certificate cert = X509Certificate.getInstance(inStream);
90 * inStream.close();
91 * </pre>
92 * OR
93 * <pre>
94 * byte[] certData = <certificate read from a file, say>
95 * X509Certificate cert = X509Certificate.getInstance(certData);
96 * </pre>
97 * <p>
98 * In either case, the code that instantiates an X.509 certificate
99 * consults the value of the {@code cert.provider.x509v1} security property
100 * to locate the actual implementation or instantiates a default implementation.
101 * <p>
102 * The {@code cert.provider.x509v1} property is set to a default
103 * implementation for X.509 such as:
104 * <pre>
105 * cert.provider.x509v1=com.sun.security.cert.internal.x509.X509V1CertImpl
106 * </pre>
107 * <p>
108 * The value of this {@code cert.provider.x509v1} property has to be
109 * changed to instantiate another implementation. If this security
110 * property is not set, a default implementation will be used.
111 * Currently, due to possible security restrictions on access to
112 * Security properties, this value is looked up and cached at class
113 * initialization time and will fallback on a default implementation if
114 * the Security property is not accessible.
115 *
116 * <p><em>Note: The classes in the package {@code javax.security.cert}
117 * exist for compatibility with earlier versions of the
118 * Java Secure Sockets Extension (JSSE). New applications should instead
119 * use the standard Java SE certificate classes located in
120 * {@code java.security.cert}.</em></p>
121 *
122 * @author Hemma Prafullchandra
123 * @since 1.4
124 * @see Certificate
125 * @see java.security.cert.X509Extension
126 * @see java.security.Security security properties
127 * @deprecated Use the classes in {@code java.security.cert} instead.
128 */
129 @Deprecated(since="9")
130 public abstract class X509Certificate extends Certificate {
131
132 /*
133 * Constant to lookup in the Security properties file.
134 * In the Security properties file the default implementation
135 * for X.509 v3 is given as:
136 * <pre>
137 * cert.provider.x509v1=com.sun.security.cert.internal.x509.X509V1CertImpl
138 * </pre>
139 */
140 private static final String X509_PROVIDER = "cert.provider.x509v1";
141 private static String X509Provider;
142
143 static {
144 X509Provider = AccessController.doPrivileged(
145 new PrivilegedAction<>() {
146 public String run() {
147 return Security.getProperty(X509_PROVIDER);
148 }
149 }
150 );
151 }
152
153 /**
154 * Instantiates an X509Certificate object, and initializes it with
155 * the data read from the input stream {@code inStream}.
156 * The implementation (X509Certificate is an abstract class) is
157 * provided by the class specified as the value of the
158 * {@code cert.provider.x509v1} security property.
159 *
160 * <p>Note: Only one DER-encoded
161 * certificate is expected to be in the input stream.
162 * Also, all X509Certificate
163 * subclasses must provide a constructor of the form:
164 * <pre>{@code
165 * public <subClass>(InputStream inStream) ...
166 * }</pre>
167 *
168 * @param inStream an input stream with the data to be read to
169 * initialize the certificate.
170 * @return an X509Certificate object initialized with the data
171 * from the input stream.
172 * @exception CertificateException if a class initialization
173 * or certificate parsing error occurs.
174 */
175 public static final X509Certificate getInstance(InputStream inStream)
176 throws CertificateException {
177 return getInst((Object)inStream);
178 }
179
180 /**
181 * Instantiates an X509Certificate object, and initializes it with
182 * the specified byte array.
183 * The implementation (X509Certificate is an abstract class) is
184 * provided by the class specified as the value of the
185 * {@code cert.provider.x509v1} security property.
186 *
187 * <p>Note: All X509Certificate
188 * subclasses must provide a constructor of the form:
189 * <pre>{@code
190 * public <subClass>(InputStream inStream) ...
191 * }</pre>
192 *
193 * @param certData a byte array containing the DER-encoded
194 * certificate.
195 * @return an X509Certificate object initialized with the data
196 * from {@code certData}.
197 * @exception CertificateException if a class initialization
198 * or certificate parsing error occurs.
199 */
200 public static final X509Certificate getInstance(byte[] certData)
201 throws CertificateException {
202 return getInst((Object)certData);
203 }
204
205 private static final X509Certificate getInst(Object value)
206 throws CertificateException {
207 /*
208 * This turns out not to work for now. To run under JDK1.2 we would
209 * need to call beginPrivileged() but we can't do that and run
210 * under JDK1.1.
211 */
212 String className = X509Provider;
213 if (className == null || className.isEmpty()) {
214 // shouldn't happen, but assume corrupted properties file
215 // provide access to sun implementation
216 className = "com.sun.security.cert.internal.x509.X509V1CertImpl";
217 }
218 try {
219 Class<?>[] params = null;
220 if (value instanceof InputStream) {
221 params = new Class<?>[] { InputStream.class };
222 } else if (value instanceof byte[]) {
223 params = new Class<?>[] { value.getClass() };
224 } else
225 throw new CertificateException("Unsupported argument type");
226 Class<?> certClass = Class.forName(className);
227
228 // get the appropriate constructor and instantiate it
229 Constructor<?> cons = certClass.getConstructor(params);
230
231 // get a new instance
232 Object obj = cons.newInstance(new Object[] {value});
233 return (X509Certificate)obj;
234
235 } catch (ClassNotFoundException e) {
236 throw new CertificateException("Could not find class: " + e);
237 } catch (IllegalAccessException e) {
238 throw new CertificateException("Could not access class: " + e);
239 } catch (InstantiationException e) {
240 throw new CertificateException("Problems instantiating: " + e);
241 } catch (InvocationTargetException e) {
242 throw new CertificateException("InvocationTargetException: "
243 + e.getTargetException());
244 } catch (NoSuchMethodException e) {
245 throw new CertificateException("Could not find class method: "
246 + e.getMessage());
247 }
248 }
249
250 /**
251 * Checks that the certificate is currently valid. It is if
252 * the current date and time are within the validity period given in the
253 * certificate.
254 * <p>
255 * The validity period consists of two date/time values:
256 * the first and last dates (and times) on which the certificate
257 * is valid. It is defined in
258 * ASN.1 as:
259 * <pre>
260 * validity Validity
261 *
262 * Validity ::= SEQUENCE {
263 * notBefore CertificateValidityDate,
264 * notAfter CertificateValidityDate }
265 *
266 * CertificateValidityDate ::= CHOICE {
267 * utcTime UTCTime,
268 * generalTime GeneralizedTime }
269 * </pre>
270 *
271 * @exception CertificateExpiredException if the certificate has expired.
272 * @exception CertificateNotYetValidException if the certificate is not
273 * yet valid.
274 */
275 public abstract void checkValidity()
276 throws CertificateExpiredException, CertificateNotYetValidException;
277
278 /**
279 * Checks that the specified date is within the certificate's
280 * validity period. In other words, this determines whether the
281 * certificate would be valid at the specified date/time.
282 *
283 * @param date the Date to check against to see if this certificate
284 * is valid at that date/time.
285 * @exception CertificateExpiredException if the certificate has expired
286 * with respect to the {@code date} supplied.
287 * @exception CertificateNotYetValidException if the certificate is not
288 * yet valid with respect to the {@code date} supplied.
289 * @see #checkValidity()
290 */
291 public abstract void checkValidity(Date date)
292 throws CertificateExpiredException, CertificateNotYetValidException;
293
294 /**
295 * Gets the {@code version} (version number) value from the
296 * certificate. The ASN.1 definition for this is:
297 * <pre>
298 * version [0] EXPLICIT Version DEFAULT v1
299 *
300 * Version ::= INTEGER { v1(0), v2(1), v3(2) }
301 * </pre>
302 *
303 * @return the version number from the ASN.1 encoding, i.e. 0, 1 or 2.
304 */
305 public abstract int getVersion();
306
307 /**
308 * Gets the {@code serialNumber} value from the certificate.
309 * The serial number is an integer assigned by the certification
310 * authority to each certificate. It must be unique for each
311 * certificate issued by a given CA (i.e., the issuer name and
312 * serial number identify a unique certificate).
313 * The ASN.1 definition for this is:
314 * <pre>
315 * serialNumber CertificateSerialNumber
316 *
317 * CertificateSerialNumber ::= INTEGER
318 * </pre>
319 *
320 * @return the serial number.
321 */
322 public abstract BigInteger getSerialNumber();
323
324 /**
325 * Gets the {@code issuer} (issuer distinguished name) value from
326 * the certificate. The issuer name identifies the entity that signed (and
327 * issued) the certificate.
328 *
329 * <p>The issuer name field contains an
330 * X.500 distinguished name (DN).
331 * The ASN.1 definition for this is:
332 * <pre>
333 * issuer Name
334 *
335 * Name ::= CHOICE { RDNSequence }
336 * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
337 * RelativeDistinguishedName ::=
338 * SET OF AttributeValueAssertion
339 *
340 * AttributeValueAssertion ::= SEQUENCE {
341 * AttributeType,
342 * AttributeValue }
343 * AttributeType ::= OBJECT IDENTIFIER
344 * AttributeValue ::= ANY
345 * </pre>
346 * The {@code Name} describes a hierarchical name composed of
347 * attributes, such as country name, and corresponding values, such as US.
348 * The type of the {@code AttributeValue} component is determined by
349 * the {@code AttributeType}; in general it will be a
350 * {@code directoryString}. A {@code directoryString} is usually
351 * one of {@code PrintableString},
352 * {@code TeletexString} or {@code UniversalString}.
353 *
354 * @return a Principal whose name is the issuer distinguished name.
355 */
356 public abstract Principal getIssuerDN();
357
358 /**
359 * Gets the {@code subject} (subject distinguished name) value
360 * from the certificate.
361 * The ASN.1 definition for this is:
362 * <pre>
363 * subject Name
364 * </pre>
365 *
366 * <p>See {@link #getIssuerDN() getIssuerDN} for {@code Name}
367 * and other relevant definitions.
368 *
369 * @return a Principal whose name is the subject name.
370 * @see #getIssuerDN()
371 */
372 public abstract Principal getSubjectDN();
373
374 /**
375 * Gets the {@code notBefore} date from the validity period of
376 * the certificate.
377 * The relevant ASN.1 definitions are:
378 * <pre>
379 * validity Validity
380 *
381 * Validity ::= SEQUENCE {
382 * notBefore CertificateValidityDate,
383 * notAfter CertificateValidityDate }
384 *
385 * CertificateValidityDate ::= CHOICE {
386 * utcTime UTCTime,
387 * generalTime GeneralizedTime }
388 * </pre>
389 *
390 * @return the start date of the validity period.
391 * @see #checkValidity()
392 */
393 public abstract Date getNotBefore();
394
395 /**
396 * Gets the {@code notAfter} date from the validity period of
397 * the certificate. See {@link #getNotBefore() getNotBefore}
398 * for relevant ASN.1 definitions.
399 *
400 * @return the end date of the validity period.
401 * @see #checkValidity()
402 */
403 public abstract Date getNotAfter();
404
405 /**
406 * Gets the signature algorithm name for the certificate
407 * signature algorithm. An example is the string "SHA-1/DSA".
408 * The ASN.1 definition for this is:
409 * <pre>
410 * signatureAlgorithm AlgorithmIdentifier
411 *
412 * AlgorithmIdentifier ::= SEQUENCE {
413 * algorithm OBJECT IDENTIFIER,
414 * parameters ANY DEFINED BY algorithm OPTIONAL }
415 * -- contains a value of the type
416 * -- registered for use with the
417 * -- algorithm object identifier value
418 * </pre>
419 *
420 * <p>The algorithm name is determined from the {@code algorithm}
421 * OID string.
422 *
423 * @return the signature algorithm name.
424 */
425 public abstract String getSigAlgName();
426
427 /**
428 * Gets the signature algorithm OID string from the certificate.
429 * An OID is represented by a set of positive whole numbers separated
430 * by periods.
431 * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
432 * with DSA signature algorithm, as per the PKIX part I.
433 *
434 * <p>See {@link #getSigAlgName() getSigAlgName} for
435 * relevant ASN.1 definitions.
436 *
437 * @return the signature algorithm OID string.
438 */
439 public abstract String getSigAlgOID();
440
441 /**
442 * Gets the DER-encoded signature algorithm parameters from this
443 * certificate's signature algorithm. In most cases, the signature
444 * algorithm parameters are null; the parameters are usually
445 * supplied with the certificate's public key.
446 *
447 * <p>See {@link #getSigAlgName() getSigAlgName} for
448 * relevant ASN.1 definitions.
449 *
450 * @return the DER-encoded signature algorithm parameters, or
451 * null if no parameters are present.
452 */
453 public abstract byte[] getSigAlgParams();
454 }