X509Certificate


1   /*
2    * @(#)X509Certificate.java 1.9 04/02/16
3    *
4    * Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL.  Use is subject to license terms.
6    */
7     
8   /*
9    * NOTE:
10   * Because of various external restrictions (i.e. US export
11   * regulations, etc.), the actual source code can not be provided
12   * at this time. This file represents the skeleton of the source
13   * file, so that javadocs of the API can be created.
14   */
15  
16  package javax.security.cert;
17  
18  import java.io.InputStream;
19  import java.lang.Class;
20  import java.lang.reflect.Constructor;
21  import java.lang.reflect.InvocationTargetException;
22  import java.security.Security;
23  import java.math.BigInteger;
24  import java.security.AccessController;
25  import java.security.Principal;
26  import java.security.PrivilegedAction;
27  import java.security.PublicKey;
28  import java.util.BitSet;
29  import java.util.Date;
30  
31  /** 
32   * Abstract class for X.509 v1 certificates. This provides a standard
33   * way to access all the version 1 attributes of an X.509 certificate.
34   * Attributes that are specific to X.509 v2 or v3 are not available
35   * through this interface. Future API evolution will provide full access to
36   * complete X.509 v3 attributes.
37   * <p>
38   * The basic X.509 format was defined by
39   * ISO/IEC and ANSI X9 and is described below in ASN.1:
40   * <pre>
41   * Certificate  ::=  SEQUENCE  {
42   *     tbsCertificate       TBSCertificate,
43   *     signatureAlgorithm   AlgorithmIdentifier,
44   *     signature            BIT STRING  }
45   * </pre>
46   * <p>
47   * These certificates are widely used to support authentication and
48   * other functionality in Internet security systems. Common applications
49   * include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL),
50   * code signing for trusted software distribution, and Secure Electronic
51   * Transactions (SET).
52   * <p>
53   * These certificates are managed and vouched for by <em>Certificate
54   * Authorities</em> (CAs). CAs are services which create certificates by
55   * placing data in the X.509 standard format and then digitally signing
56   * that data. CAs act as trusted third parties, making introductions
57   * between principals who have no direct knowledge of each other.
58   * CA certificates are either signed by themselves, or by some other
59   * CA such as a "root" CA.
60   * <p>
61   * The ASN.1 definition of <code>tbsCertificate</code> is:
62   * <pre>
63   * TBSCertificate  ::=  SEQUENCE  {
64   *     version         [0]  EXPLICIT Version DEFAULT v1,
65   *     serialNumber         CertificateSerialNumber,
66   *     signature            AlgorithmIdentifier,
67   *     issuer               Name,
68   *     validity             Validity,
69   *     subject              Name,
70   *     subjectPublicKeyInfo SubjectPublicKeyInfo,
71   *     }
72   * </pre>
73   * <p>
74   * Here is sample code to instantiate an X.509 certificate:
75   * <pre> 
76   * InputStream inStream = new FileInputStream("fileName-of-cert");
77   * X509Certificate cert = X509Certificate.getInstance(inStream);
78   * inStream.close();
79   * </pre>
80   * OR
81   * <pre>
82   * byte[] certData = &lt;certificate read from a file, say&gt;
83   * X509Certificate cert = X509Certificate.getInstance(certData);
84   * </pre>
85   * <p>
86   * In either case, the code that instantiates an X.509 certificate
87   * consults the Java security properties file to locate the actual
88   * implementation or instantiates a default implementation.
89   * <p>
90   * The Java security properties file is located in the file named
91   * &lt;JAVA_HOME&gt;/lib/security/java.security, where &lt;JAVA_HOME&gt;
92   * refers to the directory where the JDK was installed.
93   * In the Security properties file, a default implementation
94   * for X.509 v1 may be given such as:
95   * <pre>
96   * cert.provider.x509v1=com.sun.security.cert.internal.x509.X509V1CertImpl
97   * </pre>
98   * <p>
99   * The value of this <code>cert.provider.x509v1</code> property has to be 
100  * changed to instatiate another implementation. If this security
101  * property is not set, a default implementation will be used.
102  * Currently, due to possible security restrictions on access to
103  * Security properties, this value is looked up and cached at class
104  * initialization time and will fallback on a default implementation if
105  * the Security property is not accessible.
106  *
107  * <p><em>Note: The classes in the package <code>javax.security.cert</code>
108  * exist for compatibility with earlier versions of the
109  * Java Secure Sockets Extension (JSSE). New applications should instead
110  * use the standard J2SE certificate classes located in
111  * <code>java.security.cert</code>.</em></p>
112  *
113  * @author Hemma Prafullchandra
114  * @version 1.29
115  * @since 1.4
116  * @see Certificate
117  * @see java.security.cert.X509Extension
118  */
119 public abstract class X509Certificate extends Certificate
120 {
121 
122     public X509Certificate() { }
123 
124     /** 
125      * Instantiates an X509Certificate object, and initializes it with
126      * the data read from the input stream <code>inStream</code>.
127      * The implementation (X509Certificate is an abstract class) is
128      * provided by the class specified as the value of the 
129      * <code>cert.provider.x509v1</code>
130      * property in the security properties file.
131      *
132      * <p>Note: Only one DER-encoded
133      * certificate is expected to be in the input stream.
134      * Also, all X509Certificate
135      * subclasses must provide a constructor of the form:
136      * <code><pre>
137      * public &lt;subClass&gt;(InputStream inStream) ...
138      * </pre></code>
139      *   
140      * @param inStream an input stream with the data to be read to
141      *        initialize the certificate.
142      * @return an X509Certificate object initialized with the data
143      *         from the input stream.
144      * @exception CertificateException if a class initialization
145      *            or certificate parsing error occurs.
146      */
147     public static final X509Certificate getInstance(InputStream inStream)
148         throws CertificateException
149     {
150         return null;
151     }
152 
153     /** 
154      * Instantiates an X509Certificate object, and initializes it with
155      * the specified byte array.
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: All X509Certificate
162      * subclasses must provide a constructor of the form:
163      * <code><pre>
164      * public &lt;subClass&gt;(InputStream inStream) ...
165      * </pre></code>
166      *   
167      * @param certData a byte array containing the DER-encoded
168      *        certificate.
169      * @return an X509Certificate object initialized with the data
170      *         from <code>certData</code>.
171      * @exception CertificateException if a class initialization
172      *            or certificate parsing error occurs.
173      */
174     public static final X509Certificate getInstance(byte[] certData)
175         throws CertificateException
176     {
177         return null;
178     }
179 
180     /** 
181      * Checks that the certificate is currently valid. It is if
182      * the current date and time are within the validity period given in the
183      * certificate.
184      * <p>
185      * The validity period consists of two date/time values: 
186      * the first and last dates (and times) on which the certificate 
187      * is valid. It is defined in
188      * ASN.1 as:
189      * <pre>
190      * validity             Validity<p>
191      * Validity ::= SEQUENCE {
192      *     notBefore      CertificateValidityDate,
193      *     notAfter       CertificateValidityDate }<p>
194      * CertificateValidityDate ::= CHOICE {
195      *     utcTime        UTCTime,
196      *     generalTime    GeneralizedTime }
197      * </pre>
198      * 
199      * @exception CertificateExpiredException if the certificate has expired.
200      * @exception CertificateNotYetValidException if the certificate is not
201      *            yet valid.
202      */
203     public abstract void checkValidity()
204         throws CertificateExpiredException, CertificateNotYetValidException;
205 
206     /** 
207      * Checks that the specified date is within the certificate's
208      * validity period. In other words, this determines whether the 
209      * certificate would be valid at the specified date/time.
210      *
211      * @param date the Date to check against to see if this certificate
212      *        is valid at that date/time.
213      * @exception CertificateExpiredException if the certificate has expired
214      *            with respect to the <code>date</code> supplied.
215      * @exception CertificateNotYetValidException if the certificate is not
216      *            yet valid with respect to the <code>date</code> supplied.
217      * @see #checkValidity()
218      */
219     public abstract void checkValidity(Date date)
220         throws CertificateExpiredException, CertificateNotYetValidException;
221 
222     /** 
223      * Gets the <code>version</code> (version number) value from the
224      * certificate. The ASN.1 definition for this is:
225      * <pre>
226      * version         [0]  EXPLICIT Version DEFAULT v1<p>
227      * Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
228      * </pre>
229      *
230      * @return the version number from the ASN.1 encoding, i.e. 0, 1 or 2.
231      */
232     public abstract int getVersion();
233 
234     /** 
235      * Gets the <code>serialNumber</code> value from the certificate.
236      * The serial number is an integer assigned by the certification
237      * authority to each certificate. It must be unique for each
238      * certificate issued by a given CA (i.e., the issuer name and
239      * serial number identify a unique certificate).
240      * The ASN.1 definition for this is:
241      * <pre>
242      * serialNumber     CertificateSerialNumber<p>
243      * 
244      * CertificateSerialNumber  ::=  INTEGER
245      * </pre>
246      *
247      * @return the serial number.
248      */
249     public abstract BigInteger getSerialNumber();
250 
251     /** 
252      * Gets the <code>issuer</code> (issuer distinguished name) value from 
253      * the certificate. The issuer name identifies the entity that signed (and
254      * issued) the certificate. 
255      * 
256      * <p>The issuer name field contains an
257      * X.500 distinguished name (DN).
258      * The ASN.1 definition for this is:
259      * <pre>
260      * issuer    Name<p>
261      *
262      * Name ::= CHOICE { RDNSequence }
263      * RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
264      * RelativeDistinguishedName ::=
265      *     SET OF AttributeValueAssertion
266      *
267      * AttributeValueAssertion ::= SEQUENCE {
268      *                               AttributeType,
269      *                               AttributeValue }
270      * AttributeType ::= OBJECT IDENTIFIER
271      * AttributeValue ::= ANY
272      * </pre>
273      * The <code>Name</code> describes a hierarchical name composed of
274      * attributes, such as country name, and corresponding values, such as US.
275      * The type of the <code>AttributeValue</code> component is determined by
276      * the <code>AttributeType</code>; in general it will be a 
277      * <code>directoryString</code>. A <code>directoryString</code> is usually 
278      * one of <code>PrintableString</code>,
279      * <code>TeletexString</code> or <code>UniversalString</code>.
280      * 
281      * @return a Principal whose name is the issuer distinguished name.
282      */
283     public abstract Principal getIssuerDN();
284 
285     /** 
286      * Gets the <code>subject</code> (subject distinguished name) value 
287      * from the certificate.
288      * The ASN.1 definition for this is:
289      * <pre>
290      * subject    Name
291      * </pre>
292      * 
293      * <p>See <a href = "#getIssuerDN">getIssuerDN</a> for <code>Name</code> 
294      * and other relevant definitions.
295      * 
296      * @return a Principal whose name is the subject name.
297      * @see #getIssuerDN()
298      */
299     public abstract Principal getSubjectDN();
300 
301     /** 
302      * Gets the <code>notBefore</code> date from the validity period of 
303      * the certificate.
304      * The relevant ASN.1 definitions are:
305      * <pre>
306      * validity             Validity<p>
307      * 
308      * Validity ::= SEQUENCE {
309      *     notBefore      CertificateValidityDate,
310      *     notAfter       CertificateValidityDate }<p>
311      * CertificateValidityDate ::= CHOICE {
312      *     utcTime        UTCTime,
313      *     generalTime    GeneralizedTime }
314      * </pre>
315      *
316      * @return the start date of the validity period.
317      * @see #checkValidity()
318      */
319     public abstract Date getNotBefore();
320 
321     /** 
322      * Gets the <code>notAfter</code> date from the validity period of 
323      * the certificate. See <a href = "#getNotBefore">getNotBefore</a>
324      * for relevant ASN.1 definitions.
325      *
326      * @return the end date of the validity period.
327      * @see #checkValidity()
328      */
329     public abstract Date getNotAfter();
330 
331     /** 
332      * Gets the signature algorithm name for the certificate
333      * signature algorithm. An example is the string "SHA-1/DSA".
334      * The ASN.1 definition for this is:
335      * <pre>
336      * signatureAlgorithm   AlgorithmIdentifier<p>
337      * AlgorithmIdentifier  ::=  SEQUENCE  {
338      *     algorithm               OBJECT IDENTIFIER,
339      *     parameters              ANY DEFINED BY algorithm OPTIONAL  }
340      *                             -- contains a value of the type
341      *                             -- registered for use with the
342      *                             -- algorithm object identifier value
343      * </pre>
344      * 
345      * <p>The algorithm name is determined from the <code>algorithm</code>
346      * OID string.
347      *
348      * @return the signature algorithm name.
349      */
350     public abstract String getSigAlgName();
351 
352     /** 
353      * Gets the signature algorithm OID string from the certificate.
354      * An OID is represented by a set of positive whole numbers separated
355      * by periods.
356      * For example, the string "1.2.840.10040.4.3" identifies the SHA-1
357      * with DSA signature algorithm, as per the PKIX part I.
358      * 
359      * <p>See <a href = "#getSigAlgName">getSigAlgName</a> for 
360      * relevant ASN.1 definitions.
361      *
362      * @return the signature algorithm OID string.
363      */
364     public abstract String getSigAlgOID();
365 
366     /** 
367      * Gets the DER-encoded signature algorithm parameters from this
368      * certificate's signature algorithm. In most cases, the signature
369      * algorithm parameters are null; the parameters are usually
370      * supplied with the certificate's public key.
371      * 
372      * <p>See <a href = "#getSigAlgName">getSigAlgName</a> for 
373      * relevant ASN.1 definitions.
374      *
375      * @return the DER-encoded signature algorithm parameters, or
376      *         null if no parameters are present.
377      */
378     public abstract byte[] getSigAlgParams();
379 }
380
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags