001 /*
002 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.security.cert;
027
028 import java.io.InputStream;
029 import java.lang.Class;
030 import java.lang.reflect.Constructor;
031 import java.lang.reflect.InvocationTargetException;
032 import java.security.Security;
033
034 import java.math.BigInteger;
035 import java.security.AccessController;
036 import java.security.Principal;
037 import java.security.PrivilegedAction;
038 import java.security.PublicKey;
039 import java.util.BitSet;
040 import java.util.Date;
041
042 /**
043 * Abstract class for X.509 v1 certificates. This provides a standard
044 * way to access all the version 1 attributes of an X.509 certificate.
045 * Attributes that are specific to X.509 v2 or v3 are not available
046 * through this interface. Future API evolution will provide full access to
047 * complete X.509 v3 attributes.
048 * <p>
049 * The basic X.509 format was defined by
050 * ISO/IEC and ANSI X9 and is described below in ASN.1:
051 * <pre>
052 * Certificate ::= SEQUENCE {
053 * tbsCertificate TBSCertificate,
054 * signatureAlgorithm AlgorithmIdentifier,
055 * signature BIT STRING }
056 * </pre>
057 * <p>
058 * These certificates are widely used to support authentication and
059 * other functionality in Internet security systems. Common applications
060 * include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL),
061 * code signing for trusted software distribution, and Secure Electronic
062 * Transactions (SET).
063 * <p>
064 * These certificates are managed and vouched for by <em>Certificate
065 * Authorities</em> (CAs). CAs are services which create certificates by
066 * placing data in the X.509 standard format and then digitally signing
067 * that data. CAs act as trusted third parties, making introductions
068 * between principals who have no direct knowledge of each other.
069 * CA certificates are either signed by themselves, or by some other
070 * CA such as a "root" CA.
071 * <p>
072 * The ASN.1 definition of <code>tbsCertificate</code> is:
073 * <pre>
074 * TBSCertificate ::= SEQUENCE {
075 * version [0] EXPLICIT Version DEFAULT v1,
076 * serialNumber CertificateSerialNumber,
077 * signature AlgorithmIdentifier,
078 * issuer Name,
079 * validity Validity,
080 * subject Name,
081 * subjectPublicKeyInfo SubjectPublicKeyInfo,
082 * }
083 * </pre>
084 * <p>
085 * Here is sample code to instantiate an X.509 certificate:
086 * <pre>
087 * InputStream inStream = new FileInputStream("fileName-of-cert");
088 * X509Certificate cert = X509Certificate.getInstance(inStream);
089 * inStream.close();
090 * </pre>
091 * OR
092 * <pre>
093 * byte[] certData = <certificate read from a file, say>
094 * X509Certificate cert = X509Certificate.getInstance(certData);
095 * </pre>
096 * <p>
097 * In either case, the code that instantiates an X.509 certificate
098 * consults the Java security properties file to locate the actual
099 * implementation or instantiates a default implementation.
100 * <p>
101 * The Java security properties file is located in the file named
102 * <JAVA_HOME>/lib/security/java.security.
103 * <JAVA_HOME> refers to the value of the java.home system property,
104 * and specifies the directory where the JRE is installed.
105 * In the Security properties file, a default implementation
106 * for X.509 v1 may be given such as:
107 * <pre>
108 * cert.provider.x509v1=com.sun.security.cert.internal.x509.X509V1CertImpl
109 * </pre>
110 * <p>
111 * The value of this <code>cert.provider.x509v1</code> property has to be
112 * changed to instatiate another implementation. If this security
113 * property is not set, a default implementation will be used.
114 * Currently, due to possible security restrictions on access to
115 * Security properties, this value is looked up and cached at class
116 * initialization time and will fallback on a default implementation if
117 * the Security property is not accessible.
118 *
119 * <p><em>Note: The classes in the package <code>javax.security.cert</code>
120 * exist for compatibility with earlier versions of the
121 * Java Secure Sockets Extension (JSSE). New applications should instead
122 * use the standard Java SE certificate classes located in
123 * <code>java.security.cert</code>.</em></p>
124 *
125 * @author Hemma Prafullchandra
126 * @version 1.38
127 * @since 1.4
128 * @see Certificate
129 * @see java.security.cert.X509Extension
130 */
131 public abstract class X509Certificate extends Certificate {
132
133 /*
134 * Constant to lookup in the Security properties file.
135 * In the Security properties file the default implementation
136 * for X.509 v3 is given as:
137 * <pre>
138 * cert.provider.x509v1=com.sun.security.cert.internal.x509.X509V1CertImpl
139 * </pre>
140 */
141 private static final String X509_PROVIDER = "cert.provider.x509v1";
142 private static String X509Provider;
143
144 static {
145 X509Provider = AccessController
146 .doPrivileged(new PrivilegedAction<String>() {
147 public String run() {
148 return Security.getProperty(X509_PROVIDER);
149 }
150 });
151 }
152
153 /**
154 * Instantiates an X509Certificate object, and initializes it with
155 * the data read from the input stream <code>inStream</code>.
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</code>
159 * property in the security properties file.
160 *
161 * <p>Note: Only one DER-encoded
162 * certificate is expected to be in the input stream.
163 * Also, all X509Certificate
164 * subclasses must provide a constructor of the form:
165 * <code><pre>
166 * public <subClass>(InputStream inStream) ...
167 * </pre></code>
168 *
169 * @param inStream an input stream with the data to be read to
170 * initialize the certificate.
171 * @return an X509Certificate object initialized with the data
172 * from the input stream.
173 * @exception CertificateException if a class initialization
174 * or certificate parsing error occurs.
175 */
176 public static final X509Certificate getInstance(InputStream inStream)
177 throws CertificateException {
178 return getInst((Object) inStream);
179 }
180
181 /**
182 * Instantiates an X509Certificate object, and initializes it with
183 * the specified byte array.
184 * The implementation (X509Certificate is an abstract class) is
185 * provided by the class specified as the value of the
186 * <code>cert.provider.x509v1</code>
187 * property in the security properties file.
188 *
189 * <p>Note: All X509Certificate
190 * subclasses must provide a constructor of the form:
191 * <code><pre>
192 * public <subClass>(InputStream inStream) ...
193 * </pre></code>
194 *
195 * @param certData a byte array containing the DER-encoded
196 * certificate.
197 * @return an X509Certificate object initialized with the data
198 * from <code>certData</code>.
199 * @exception CertificateException if a class initialization
200 * or certificate parsing error occurs.
201 */
202 public static final X509Certificate getInstance(byte[] certData)
203 throws CertificateException {
204 return getInst((Object) certData);
205 }
206
207 private static final X509Certificate getInst(Object value)
208 throws CertificateException {
209 /*
210 * This turns out not to work for now. To run under JDK1.2 we would
211 * need to call beginPrivileged() but we can't do that and run
212 * under JDK1.1.
213 */
214 String className = X509Provider;
215 if (className == null || className.length() == 0) {
216 // shouldn't happen, but assume corrupted properties file
217 // provide access to sun implementation
218 className = "com.sun.security.cert.internal.x509.X509V1CertImpl";
219 }
220 try {
221 Class[] params = null;
222 if (value instanceof InputStream) {
223 params = new Class[] { InputStream.class };
224 } else if (value instanceof byte[]) {
225 params = new Class[] { value.getClass() };
226 } else
227 throw new CertificateException(
228 "Unsupported argument type");
229 Class<?> certClass = Class.forName(className);
230
231 // get the appropriate constructor and instantiate it
232 Constructor<?> cons = certClass.getConstructor(params);
233
234 // get a new instance
235 Object obj = cons.newInstance(new Object[] { value });
236 return (X509Certificate) obj;
237
238 } catch (ClassNotFoundException e) {
239 throw new CertificateException("Could not find class: " + e);
240 } catch (IllegalAccessException e) {
241 throw new CertificateException("Could not access class: "
242 + e);
243 } catch (InstantiationException e) {
244 throw new CertificateException("Problems instantiating: "
245 + e);
246 } catch (InvocationTargetException e) {
247 throw new CertificateException(
248 "InvocationTargetException: "
249 + e.getTargetException());
250 } catch (NoSuchMethodException e) {
251 throw new CertificateException(
252 "Could not find class method: " + e.getMessage());
253 }
254 }
255
256 /**
257 * Checks that the certificate is currently valid. It is if
258 * the current date and time are within the validity period given in the
259 * certificate.
260 * <p>
261 * The validity period consists of two date/time values:
262 * the first and last dates (and times) on which the certificate
263 * is valid. It is defined in
264 * ASN.1 as:
265 * <pre>
266 * validity Validity<p>
267 * Validity ::= SEQUENCE {
268 * notBefore CertificateValidityDate,
269 * notAfter CertificateValidityDate }<p>
270 * CertificateValidityDate ::= CHOICE {
271 * utcTime UTCTime,
272 * generalTime GeneralizedTime }
273 * </pre>
274 *
275 * @exception CertificateExpiredException if the certificate has expired.
276 * @exception CertificateNotYetValidException if the certificate is not
277 * yet valid.
278 */
279 public abstract void checkValidity()
280 throws CertificateExpiredException,
281 CertificateNotYetValidException;
282
283 /**
284 * Checks that the specified date is within the certificate's
285 * validity period. In other words, this determines whether the
286 * certificate would be valid at the specified date/time.
287 *
288 * @param date the Date to check against to see if this certificate
289 * is valid at that date/time.
290 * @exception CertificateExpiredException if the certificate has expired
291 * with respect to the <code>date</code> supplied.
292 * @exception CertificateNotYetValidException if the certificate is not
293 * yet valid with respect to the <code>date</code> supplied.
294 * @see #checkValidity()
295 */
296 public abstract void checkValidity(Date date)
297 throws CertificateExpiredException,
298 CertificateNotYetValidException;
299
300 /**
301 * Gets the <code>version</code> (version number) value from the
302 * certificate. The ASN.1 definition for this is:
303 * <pre>
304 * version [0] EXPLICIT Version DEFAULT v1<p>
305 * Version ::= INTEGER { v1(0), v2(1), v3(2) }
306 * </pre>
307 *
308 * @return the version number from the ASN.1 encoding, i.e. 0, 1 or 2.
309 */
310 public abstract int getVersion();
311
312 /**
313 * Gets the <code>serialNumber</code> value from the certificate.
314 * The serial number is an integer assigned by the certification
315 * authority to each certificate. It must be unique for each
316 * certificate issued by a given CA (i.e., the issuer name and
317 * serial number identify a unique certificate).
318 * The ASN.1 definition for this is:
319 * <pre>
320 * serialNumber CertificateSerialNumber<p>
321 *
322 * CertificateSerialNumber ::= INTEGER
323 * </pre>
324 *
325 * @return the serial number.
326 */
327 public abstract BigInteger getSerialNumber();
328
329 /**
330 * Gets the <code>issuer</code> (issuer distinguished name) value from
331 * the certificate. The issuer name identifies the entity that signed (and
332 * issued) the certificate.
333 *
334 * <p>The issuer name field contains an
335 * X.500 distinguished name (DN).
336 * The ASN.1 definition for this is:
337 * <pre>
338 * issuer Name<p>
339 *
340 * Name ::= CHOICE { RDNSequence }
341 * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
342 * RelativeDistinguishedName ::=
343 * SET OF AttributeValueAssertion
344 *
345 * AttributeValueAssertion ::= SEQUENCE {
346 * AttributeType,
347 * AttributeValue }
348 * AttributeType ::= OBJECT IDENTIFIER
349 * AttributeValue ::= ANY
350 * </pre>
351 * The <code>Name</code> describes a hierarchical name composed of
352 * attributes, such as country name, and corresponding values, such as US.
353 * The type of the <code>AttributeValue</code> component is determined by
354 * the <code>AttributeType</code>; in general it will be a
355 * <code>directoryString</code>. A <code>directoryString</code> is usually
356 * one of <code>PrintableString</code>,
357 * <code>TeletexString</code> or <code>UniversalString</code>.
358 *
359 * @return a Principal whose name is the issuer distinguished name.
360 */
361 public abstract Principal getIssuerDN();
362
363 /**
364 * Gets the <code>subject</code> (subject distinguished name) value
365 * from the certificate.
366 * The ASN.1 definition for this is:
367 * <pre>
368 * subject Name
369 * </pre>
370 *
371 * <p>See <a href = "#getIssuerDN">getIssuerDN</a> for <code>Name</code>
372 * and other relevant definitions.
373 *
374 * @return a Principal whose name is the subject name.
375 * @see #getIssuerDN()
376 */
377 public abstract Principal getSubjectDN();
378
379 /**
380 * Gets the <code>notBefore</code> date from the validity period of
381 * the certificate.
382 * The relevant ASN.1 definitions are:
383 * <pre>
384 * validity Validity<p>
385 *
386 * Validity ::= SEQUENCE {
387 * notBefore CertificateValidityDate,
388 * notAfter CertificateValidityDate }<p>
389 * CertificateValidityDate ::= CHOICE {
390 * utcTime UTCTime,
391 * generalTime GeneralizedTime }
392 * </pre>
393 *
394 * @return the start date of the validity period.
395 * @see #checkValidity()
396 */
397 public abstract Date getNotBefore();
398
399 /**
400 * Gets the <code>notAfter</code> date from the validity period of
401 * the certificate. See <a href = "#getNotBefore">getNotBefore</a>
402 * for relevant ASN.1 definitions.
403 *
404 * @return the end date of the validity period.
405 * @see #checkValidity()
406 */
407 public abstract Date getNotAfter();
408
409 /**
410 * Gets the signature algorithm name for the certificate
411 * signature algorithm. An example is the string "SHA-1/DSA".
412 * The ASN.1 definition for this is:
413 * <pre>
414 * signatureAlgorithm AlgorithmIdentifier<p>
415 * AlgorithmIdentifier ::= SEQUENCE {
416 * algorithm OBJECT IDENTIFIER,
417 * parameters ANY DEFINED BY algorithm OPTIONAL }
418 * -- contains a value of the type
419 * -- registered for use with the
420 * -- algorithm object identifier value
421 * </pre>
422 *
423 * <p>The algorithm name is determined from the <code>algorithm</code>
424 * OID string.
425 *
426 * @return the signature algorithm name.
427 */
428 public abstract String getSigAlgName();
429
430 /**
431 * Gets the signature algorithm OID string from the certificate.
432 * An OID is represented by a set of positive whole numbers separated
433 * by periods.
434 * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
435 * with DSA signature algorithm, as per the PKIX part I.
436 *
437 * <p>See <a href = "#getSigAlgName">getSigAlgName</a> for
438 * relevant ASN.1 definitions.
439 *
440 * @return the signature algorithm OID string.
441 */
442 public abstract String getSigAlgOID();
443
444 /**
445 * Gets the DER-encoded signature algorithm parameters from this
446 * certificate's signature algorithm. In most cases, the signature
447 * algorithm parameters are null; the parameters are usually
448 * supplied with the certificate's public key.
449 *
450 * <p>See <a href = "#getSigAlgName">getSigAlgName</a> for
451 * relevant ASN.1 definitions.
452 *
453 * @return the DER-encoded signature algorithm parameters, or
454 * null if no parameters are present.
455 */
456 public abstract byte[] getSigAlgParams();
457 }
|