001/* X509Certificate.java --- X.509 Certificate class
002   Copyright (C) 1999,2003, 2006 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.security.cert;
040
041import java.math.BigInteger;
042import java.security.Principal;
043import java.util.Date;
044import 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 */
139public 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}