001    /* X509Certificate.java --- X.509 Certificate class
002       Copyright (C) 1999,2003, 2006 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.security.cert;
040    
041    import java.math.BigInteger;
042    import java.security.Principal;
043    import java.util.Date;
044    import java.util.List;
045    
046    /**
047     * X509Certificate is the abstract class for X.509 certificates.
048     * This provides a stanard class interface for accessing all
049     * the attributes of X.509 certificates.
050     *
051     * <p>In June 1996, the basic X.509 v3 format was finished by
052     * ISO/IEC and ANSI X.9. The ASN.1 DER format is below:
053     *
054     * <blockquote><pre>
055     * Certificate  ::=  SEQUENCE  {
056     *   tbsCertificate       TBSCertificate,
057     *   signatureAlgorithm   AlgorithmIdentifier,
058     *   signatureValue       BIT STRING  }
059     * </pre></blockquote>
060     *
061     * <p>These certificates are widely used in various Internet
062     * protocols to support authentication. It is used in
063     * Privacy Enhanced Mail (PEM), Transport Layer Security (TLS),
064     * Secure Sockets Layer (SSL), code signing for trusted software
065     * distribution, and Secure Electronic Transactions (SET).
066     *
067     * <p>The certificates are managed and vouched for by
068     * <I>Certificate Authorities</I> (CAs). CAs are companies or
069     * groups that create certificates by placing the data in the
070     * X.509 certificate format and signing it with their private
071     * key. CAs serve as trusted third parties by certifying that
072     * the person or group specified in the certificate is who
073     * they say they are.
074     *
075     * <p>The ASN.1 defintion for <I>tbsCertificate</I> is
076     *
077     * <blockquote><pre>
078     * TBSCertificate  ::=  SEQUENCE  {
079     *   version         [0]  EXPLICIT Version DEFAULT v1,
080     *   serialNumber         CertificateSerialNumber,
081     *   signature            AlgorithmIdentifier,
082     *   issuer               Name,
083     *   validity             Validity,
084     *   subject              Name,
085     *   subjectPublicKeyInfo SubjectPublicKeyInfo,
086     *   issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
087     *                        -- If present, version shall be v2 or v3
088     *   subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
089     *                        -- If present, version shall be v2 or v3
090     *   extensions      [3]  EXPLICIT Extensions OPTIONAL
091     *                        -- If present, version shall be v3
092     * }
093     *
094     * Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
095     *
096     * CertificateSerialNumber  ::=  INTEGER
097     *
098     * Validity ::= SEQUENCE {
099     *   notBefore      Time,
100     *   notAfter       Time }
101     *
102     * Time ::= CHOICE {
103     *   utcTime        UTCTime,
104     *   generalTime    GeneralizedTime }
105     *
106     * UniqueIdentifier  ::=  BIT STRING
107     *
108     * SubjectPublicKeyInfo  ::=  SEQUENCE  {
109     *   algorithm            AlgorithmIdentifier,
110     *   subjectPublicKey     BIT STRING  }
111     *
112     * Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
113     *
114     * Extension  ::=  SEQUENCE  {
115     *   extnID      OBJECT IDENTIFIER,
116     *   critical    BOOLEAN DEFAULT FALSE,
117     *   extnValue   OCTET STRING  }
118     * </pre></blockquote>
119     *
120     * Certificates are created with the CertificateFactory.
121     *
122     * <p>References:
123     *
124     * <ol>
125     * <li>Olivier Dubuisson, Philippe Fouquart (Translator) <i>ASN.1 -
126     * Communication between heterogeneous systems</i>, (C) September 2000,
127     * Morgan Kaufmann Publishers, ISBN 0-12-6333361-0. Available on-line at
128     * <a
129     * href="http://www.oss.com/asn1/dubuisson.html">http://www.oss.com/asn1/dubuisson.html</a></li>
130     * <li>R. Housley et al, <i><a href="http://www.ietf.org/rfc/rfc3280.txt">RFC
131     * 3280: Internet X.509 Public Key Infrastructure Certificate and CRL
132     * Profile</a></i>.</li>
133     * </ol>
134     *
135     * @since 1.2
136     * @author Mark Benvenuto
137     * @author Casey Marshall (rsdio@metastatic.org)
138     */
139    public abstract class X509Certificate
140      extends Certificate
141      implements X509Extension
142    {
143      private static final long serialVersionUID = -2491127588187038216L;
144    
145      /**
146       * Constructs a new certificate of the specified type.
147       */
148      protected X509Certificate()
149      {
150        super( "X.509" );
151      }
152    
153      /**
154         Checks the validity of the X.509 certificate. It is valid
155         if the current date and time are within the period specified
156         by the certificate.
157    
158         The ASN.1 DER encoding is:
159    
160         validity             Validity,
161    
162         Validity ::= SEQUENCE {
163         notBefore      Time,
164         notAfter       Time }
165    
166         Time ::= CHOICE {
167         utcTime        UTCTime,
168         generalTime    GeneralizedTime }
169    
170         Consult rfc2459 for more information.
171    
172         @throws CertificateExpiredException if the certificate expired
173         @throws CertificateNotYetValidException if the certificate is
174         not yet valid
175      */
176      public abstract void checkValidity()
177        throws CertificateExpiredException,
178        CertificateNotYetValidException;
179    
180      /**
181         Checks the validity of the X.509 certificate for the
182         specified time and date. It is valid if the specified
183         date and time are within the period specified by
184         the certificate.
185    
186         @throws CertificateExpiredException if the certificate expired
187         based on the date
188         @throws CertificateNotYetValidException if the certificate is
189         not yet valid based on the date
190      */
191      public abstract void checkValidity(Date date)
192        throws CertificateExpiredException,
193        CertificateNotYetValidException;
194    
195      /**
196         Returns the version of this certificate.
197    
198         The ASN.1 DER encoding is:
199    
200         version         [0]  EXPLICIT Version DEFAULT v1,
201    
202         Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
203    
204         Consult rfc2459 for more information.
205    
206         @return version number of certificate
207      */
208      public abstract int getVersion();
209    
210      /**
211         Gets the serial number for serial Number in
212         this Certifcate. It must be a unique number
213         unique other serial numbers from the granting CA.
214    
215         The ASN.1 DER encoding is:
216    
217         serialNumber         CertificateSerialNumber,
218    
219         CertificateSerialNumber  ::=  INTEGER
220    
221         Consult rfc2459 for more information.
222    
223         @return the serial number for this X509CRLEntry.
224      */
225      public abstract BigInteger getSerialNumber();
226    
227      /**
228         Returns the issuer (issuer distinguished name) of the
229         Certificate. The issuer is the entity who signed
230         and issued the Certificate.
231    
232         The ASN.1 DER encoding is:
233    
234         issuer                  Name,
235    
236         Name ::= CHOICE {
237         RDNSequence }
238    
239         RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
240    
241         RelativeDistinguishedName ::=
242         SET OF AttributeTypeAndValue
243    
244         AttributeTypeAndValue ::= SEQUENCE {
245         type     AttributeType,
246         value    AttributeValue }
247    
248         AttributeType ::= OBJECT IDENTIFIER
249    
250         AttributeValue ::= ANY DEFINED BY AttributeType
251    
252         DirectoryString ::= CHOICE {
253         teletexString           TeletexString (SIZE (1..MAX)),
254         printableString         PrintableString (SIZE (1..MAX)),
255         universalString         UniversalString (SIZE (1..MAX)),
256         utf8String              UTF8String (SIZE (1.. MAX)),
257         bmpString               BMPString (SIZE (1..MAX)) }
258    
259         Consult rfc2459 for more information.
260    
261         @return the issuer in the Principal class
262      */
263      public abstract Principal getIssuerDN();
264    
265      /**
266         Returns the subject (subject distinguished name) of the
267         Certificate. The subject is the entity who the Certificate
268         identifies.
269    
270         The ASN.1 DER encoding is:
271    
272         subject              Name,
273    
274         Consult rfc2459 for more information.
275    
276         @return the issuer in the Principal class
277      */
278      public abstract Principal getSubjectDN();
279    
280      /**
281         Returns the date that this certificate is not to be used
282         before, <I>notBefore</I>.
283    
284         The ASN.1 DER encoding is:
285    
286         validity             Validity,
287    
288         Validity ::= SEQUENCE {
289         notBefore      Time,
290         notAfter       Time }
291    
292         Time ::= CHOICE {
293         utcTime        UTCTime,
294         generalTime    GeneralizedTime }
295    
296         Consult rfc2459 for more information.
297    
298         @return the date <I>notBefore</I>
299      */
300      public abstract Date getNotBefore();
301    
302      /**
303         Returns the date that this certificate is not to be used
304         after, <I>notAfter</I>.
305    
306         @return the date <I>notAfter</I>
307      */
308      public abstract Date getNotAfter();
309    
310    
311      /**
312         Returns the <I>tbsCertificate</I> from the certificate.
313    
314         @return the DER encoded tbsCertificate
315    
316         @throws CertificateEncodingException if encoding error occurred
317      */
318      public abstract byte[] getTBSCertificate() throws CertificateEncodingException;
319    
320      /**
321         Returns the signature in its raw DER encoded format.
322    
323         The ASN.1 DER encoding is:
324    
325         signatureValue       BIT STRING
326    
327         Consult rfc2459 for more information.
328    
329         @return byte array representing signature
330      */
331      public abstract byte[] getSignature();
332    
333      /**
334         Returns the signature algorithm used to sign the CRL.
335         An examples is "SHA-1/DSA".
336    
337         The ASN.1 DER encoding is:
338    
339         signatureAlgorithm   AlgorithmIdentifier,
340    
341         AlgorithmIdentifier  ::=  SEQUENCE  {
342         algorithm               OBJECT IDENTIFIER,
343         parameters              ANY DEFINED BY algorithm OPTIONAL  }
344    
345         Consult rfc2459 for more information.
346    
347         The algorithm name is determined from the OID.
348    
349         @return a string with the signature algorithm name
350      */
351      public abstract String getSigAlgName();
352    
353    
354      /**
355         Returns the OID for the signature algorithm used.
356         Example "1.2.840.10040.4.3" is return for SHA-1 with DSA.\
357    
358         The ASN.1 DER encoding for the example is:
359    
360         id-dsa-with-sha1 ID  ::=  {
361         iso(1) member-body(2) us(840) x9-57 (10040)
362         x9cm(4) 3 }
363    
364         Consult rfc2459 for more information.
365    
366         @return a string containing the OID.
367      */
368      public abstract String getSigAlgOID();
369    
370    
371      /**
372         Returns the AlgorithmParameters in the encoded form
373         for the signature algorithm used.
374    
375         If access to the parameters is need, create an
376         instance of AlgorithmParameters.
377    
378         @return byte array containing algorithm parameters, null
379         if no parameters are present in certificate
380      */
381      public abstract byte[] getSigAlgParams();
382    
383    
384      /**
385         Returns the issuer unique ID for this certificate.
386    
387         The ASN.1 DER encoding is:
388    
389         issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
390         -- If present, version shall be v2 or v3
391    
392         UniqueIdentifier  ::=  BIT STRING
393    
394         Consult rfc2459 for more information.
395    
396         @return bit representation of <I>issuerUniqueID</I>
397      */
398      public abstract boolean[] getIssuerUniqueID();
399    
400      /**
401         Returns the subject unique ID for this certificate.
402    
403         The ASN.1 DER encoding is:
404    
405         subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
406         -- If present, version shall be v2 or v3
407    
408         UniqueIdentifier  ::=  BIT STRING
409    
410         Consult rfc2459 for more information.
411    
412         @return bit representation of <I>subjectUniqueID</I>
413      */
414      public abstract boolean[] getSubjectUniqueID();
415    
416      /**
417         Returns a boolean array representing the <I>KeyUsage</I>
418         extension for the certificate. The KeyUsage (OID = 2.5.29.15)
419         defines the purpose of the key in the certificate.
420    
421         The ASN.1 DER encoding is:
422    
423         id-ce-keyUsage OBJECT IDENTIFIER ::=  { id-ce 15 }
424    
425         KeyUsage ::= BIT STRING {
426         digitalSignature        (0),
427         nonRepudiation          (1),
428         keyEncipherment         (2),
429         dataEncipherment        (3),
430         keyAgreement            (4),
431         keyCertSign             (5),
432         cRLSign                 (6),
433         encipherOnly            (7),
434         decipherOnly            (8) }
435    
436         Consult rfc2459 for more information.
437    
438         @return bit representation of <I>KeyUsage</I>
439      */
440      public abstract boolean[] getKeyUsage();
441    
442      /**
443         Returns the certificate constraints path length from the
444         critical BasicConstraints extension, (OID = 2.5.29.19).
445    
446         The basic constraints extensions is used to determine if
447         the subject of the certificate is a Certificate Authority (CA)
448         and how deep the certification path may exist. The
449         <I>pathLenConstraint</I> only takes affect if <I>cA</I>
450         is set to true. "A value of zero indicates that only an
451         end-entity certificate may follow in the path." (rfc2459)
452    
453         The ASN.1 DER encoding is:
454    
455         id-ce-basicConstraints OBJECT IDENTIFIER ::=  { id-ce 19 }
456    
457         BasicConstraints ::= SEQUENCE {
458         cA                      BOOLEAN DEFAULT FALSE,
459         pathLenConstraint       INTEGER (0..MAX) OPTIONAL }
460    
461         Consult rfc2459 for more information.
462    
463         @return the length of the path constraint if BasicConstraints
464         is present and cA is TRUE. Otherwise returns -1.
465      */
466      public abstract int getBasicConstraints();
467    
468      // 1.4 instance methods.
469      // ------------------------------------------------------------------------
470    
471      /**
472       * Returns the <code>ExtendedKeyUsage</code> extension of this
473       * certificate, or null if there is no extension present. The returned
474       * value is a {@link java.util.List} strings representing the object
475       * identifiers of the extended key usages. This extension has the OID
476       * 2.5.29.37.
477       *
478       * <p>The ASN.1 definition for this extension is:
479       *
480       * <blockquote><pre>
481       * ExtendedKeyUsage ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId
482       *
483       * KeyPurposeId ::= OBJECT IDENTIFIER
484       * </pre></blockquote>
485       *
486       * @return The list of extension OIDs, or null if there are none
487       * present in this certificate.
488       * @throws CertificateParsingException If this extension cannot be
489       * parsed from its encoded form.
490       */
491      public java.util.List<String> getExtendedKeyUsage()
492        throws CertificateParsingException
493      {
494        throw new UnsupportedOperationException();
495      }
496    
497      /**
498       * Returns the alternative names for this certificate's subject (the
499       * owner), or null if there are none.
500       *
501       * <p>This is an X.509 extension with OID 2.5.29.17 and is defined by
502       * the ASN.1 construction:
503       *
504       * <blockquote><pre>
505       * SubjectAltNames ::= GeneralNames
506       *
507       * GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName
508       *
509       * GeneralName ::= CHOICE {
510       *   otherName                 [0]   OtherName,
511       *   rfc822Name                [1]   IA5String,
512       *   dNSName                   [2]   IA5String,
513       *   x400Address               [3]   ORAddress,
514       *   directoryName             [4]   Name,
515       *   ediPartyName              [5]   EDIPartyName,
516       *   uniformResourceIdentifier [6]   IA5String,
517       *   iPAddress                 [7]   OCTET STRING,
518       *   registeredID              [8]   OBJECT IDENTIFIER
519       * }
520       * </pre></blockquote>
521       *
522       * <p>The returned collection contains one or more two-element Lists,
523       * with the first object being an Integer representing the choice
524       * above (with value 0 through 8) and the second being an (a) String
525       * if the <code>GeneralName</code> is a rfc822Name, dNSName,
526       * uniformResourceIdentifier, iPAddress, or registeredID, or (b) a
527       * byte array of the DER encoded form for any others.
528       *
529       * @return The collection of alternative names, or null if there are
530       * none.
531       * @throws CertificateParsingException If the encoded extension cannot
532       * be parsed.
533       * @since JDK 1.4
534       */
535      public java.util.Collection<List<?>> getSubjectAlternativeNames()
536        throws CertificateParsingException
537      {
538        throw new UnsupportedOperationException();
539      }
540    
541      /**
542       * Returns the alternative names for this certificate's issuer, or
543       * null if there are none.
544       *
545       * <p>This is an X.509 extension with OID 2.5.29.18, and is defined by
546       * the ASN.1 construction:
547       *
548       * <blockquote><pre>
549       * IssuerAltNames ::= GeneralNames
550       * </pre></blockquote>
551       *
552       * <p>The <code>GeneralNames</code> construct and the form of the
553       * returned collection are the same as with {@link
554       * #getSubjectAlternativeNames()}.
555       *
556       * @return The collection of alternative names, or null if there are
557       * none.
558       * @throws CertificateParsingException If the encoded extension cannot
559       * be parsed.
560       * @since JDK 1.4
561       */
562      public java.util.Collection<List<?>> getIssuerAlternativeNames()
563        throws CertificateParsingException
564      {
565        throw new UnsupportedOperationException();
566      }
567    
568      /**
569       * Returns the X.500 distinguished name of this certificate's subject.
570       *
571       * @return The subject's X.500 distinguished name.
572       * @since JDK 1.4
573       */
574      public javax.security.auth.x500.X500Principal getSubjectX500Principal()
575      {
576        throw new UnsupportedOperationException();
577      }
578    
579      /**
580       * Returns the X.500 distinguished name of this certificate's issuer.
581       *
582       * @return The issuer's X.500 distinguished name.
583       * @since JDK 1.4
584       */
585      public javax.security.auth.x500.X500Principal getIssuerX500Principal()
586      {
587        throw new UnsupportedOperationException();
588      }
589    }