1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.security.cert;
19
20import java.io.ByteArrayInputStream;
21import java.math.BigInteger;
22import java.security.Principal;
23import java.util.Collection;
24import java.util.Date;
25import java.util.List;
26import javax.security.auth.x500.X500Principal;
27
28/**
29 * Abstract base class for X.509 certificates.
30 * <p>
31 * This represents a standard way for accessing the attributes of X.509
32 * certificates.
33 * <p>
34 * The basic X.509 v3 format described in ASN.1:
35 *
36 * <pre>
37 * Certificate  ::=  SEQUENCE  {
38 *     tbsCertificate       TBSCertificate,
39 *     signatureAlgorithm   AlgorithmIdentifier,
40 *     signature            BIT STRING  }
41 *
42 * TBSCertificate  ::=  SEQUENCE  {
43 *      version         [0]  EXPLICIT Version DEFAULT v1,
44 *      serialNumber         CertificateSerialNumber,
45 *      signature            AlgorithmIdentifier,
46 *      issuer               Name,
47 *      validity             Validity,
48 *      subject              Name,
49 *      subjectPublicKeyInfo SubjectPublicKeyInfo,
50 *      issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
51 *                           -- If present, version must be v2 or v3
52 *      subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
53 *                           -- If present, version must be v2 or v3
54 *      extensions      [3]  EXPLICIT Extensions OPTIONAL
55 *                           -- If present, version must be v3
56 *      }
57 * </pre>
58 * <p>
59 * For more information consult RFC 2459
60 * "Internet X.509 Public Key Infrastructure Certificate and CRL Profile" at <a
61 * href
62 * ="http://www.ietf.org/rfc/rfc2459.txt">http://www.ietf.org/rfc/rfc2459.txt
63 * </a> .
64 */
65public abstract class X509Certificate
66        extends Certificate implements X509Extension {
67
68    private static final long serialVersionUID = -2491127588187038216L;
69
70    /**
71     * Creates a new {@code X509Certificate}.
72     */
73    protected X509Certificate() {
74        super("X.509");
75    }
76
77    /**
78     * Checks whether the certificate is currently valid.
79     * <p>
80     * The validity defined in ASN.1:
81     *
82     * <pre>
83     * validity             Validity
84     *
85     * Validity ::= SEQUENCE {
86     *      notBefore       CertificateValidityDate,
87     *      notAfter        CertificateValidityDate }
88     *
89     * CertificateValidityDate ::= CHOICE {
90     *      utcTime         UTCTime,
91     *      generalTime     GeneralizedTime }
92     * </pre>
93     *
94     * @throws CertificateExpiredException
95     *             if the certificate has expired.
96     * @throws CertificateNotYetValidException
97     *             if the certificate is not yet valid.
98     */
99    public abstract void checkValidity()
100            throws CertificateExpiredException, CertificateNotYetValidException;
101
102    /**
103     * Checks whether the certificate is valid at the specified date.
104     *
105     * @param date
106     *            the date to check the validity against.
107     * @throws CertificateExpiredException
108     *             if the certificate has expired.
109     * @throws CertificateNotYetValidException
110     *             if the certificate is not yet valid.
111     * @see #checkValidity()
112     */
113    public abstract void checkValidity(Date date)
114            throws CertificateExpiredException, CertificateNotYetValidException;
115
116    /**
117     * Returns the certificates {@code version} (version number).
118     * <p>
119     * The version defined is ASN.1:
120     *
121     * <pre>
122     * Version ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
123     * </pre>
124     *
125     * @return the version number.
126     */
127    public abstract int getVersion();
128
129    /**
130     * Returns the {@code serialNumber} of the certificate.
131     * <p>
132     * The ASN.1 definition of {@code serialNumber}:
133     *
134     * <pre>
135     * CertificateSerialNumber  ::=  INTEGER
136     * </pre>
137     *
138     * @return the serial number.
139     */
140    public abstract BigInteger getSerialNumber();
141
142    /**
143     * Returns the {@code issuer} (issuer distinguished name) as an
144     * implementation specific {@code Principal} object.
145     * <p>
146     * The ASN.1 definition of {@code issuer}:
147     *
148     * <pre>
149     *  issuer      Name
150     *
151     *  Name ::= CHOICE {
152     *      RDNSequence }
153     *
154     *    RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
155     *
156     *    RelativeDistinguishedName ::= SET OF AttributeTypeAndValue
157     *
158     *    AttributeTypeAndValue ::= SEQUENCE {
159     *      type     AttributeType,
160     *      value    AttributeValue }
161     *
162     *    AttributeType ::= OBJECT IDENTIFIER
163     *
164     *    AttributeValue ::= ANY DEFINED BY AttributeType
165     * </pre>
166     *
167     * <b>replaced by:</b> {@link #getIssuerX500Principal()}.
168     *
169     * @return the {@code issuer} as an implementation specific {@code
170     *         Principal}.
171     */
172    public abstract Principal getIssuerDN() ;
173
174    /**
175     * Returns the {@code issuer} (issuer distinguished name) as an {@code
176     * X500Principal}.
177     *
178     * @return the {@code issuer} (issuer distinguished name).
179     */
180    public X500Principal getIssuerX500Principal() {
181
182        try {
183            // TODO if there is no X.509 certificate provider installed
184            // should we try to access Harmony X509CertImpl via classForName?
185            CertificateFactory factory = CertificateFactory
186                    .getInstance("X.509");
187
188            X509Certificate cert = (X509Certificate) factory
189                    .generateCertificate(new ByteArrayInputStream(getEncoded()));
190
191            return cert.getIssuerX500Principal();
192
193        } catch (Exception e) {
194            throw new RuntimeException("Failed to get X500Principal issuer", e);
195        }
196    }
197
198    /**
199     * Returns the {@code subject} (subject distinguished name) as an
200     * implementation specific {@code Principal} object.
201     * <p>
202     * The ASN.1 definition of {@code subject}:
203     *
204     * <pre>
205     * subject      Name
206     *
207     *  Name ::= CHOICE {
208     *      RDNSequence }
209     *
210     *    RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
211     *
212     *    RelativeDistinguishedName ::= SET OF AttributeTypeAndValue
213     *
214     *    AttributeTypeAndValue ::= SEQUENCE {
215     *      type     AttributeType,
216     *      value    AttributeValue }
217     *
218     *    AttributeType ::= OBJECT IDENTIFIER
219     *
220     *    AttributeValue ::= ANY DEFINED BY AttributeType
221     * </pre>
222     *
223     * <p>
224     * <b>replaced by:</b> {@link #getSubjectX500Principal()}.
225     *
226     * @return the {@code subject} (subject distinguished name).
227     */
228    public abstract Principal getSubjectDN();
229
230    /**
231     * Returns the {@code subject} (subject distinguished name) as an {@code
232     * X500Principal}.
233     *
234     * @return the {@code subject} (subject distinguished name)
235     */
236    public X500Principal getSubjectX500Principal() {
237
238        try {
239            // TODO if there is no X.509 certificate provider installed
240            // should we try to access Harmony X509CertImpl via classForName?
241            CertificateFactory factory = CertificateFactory
242                    .getInstance("X.509");
243
244            X509Certificate cert = (X509Certificate) factory
245                    .generateCertificate(new ByteArrayInputStream(getEncoded()));
246
247            return cert.getSubjectX500Principal();
248        } catch (Exception e) {
249            throw new RuntimeException("Failed to get X500Principal subject", e);
250        }
251    }
252
253    /**
254     * Returns the {@code notBefore} date from the validity period of the
255     * certificate.
256     *
257     * @return the start of the validity period.
258     */
259    public abstract Date getNotBefore();
260
261    /**
262     * Returns the {@code notAfter} date of the validity period of the
263     * certificate.
264     *
265     * @return the end of the validity period.
266     */
267    public abstract Date getNotAfter();
268
269    /**
270     * Returns the {@code tbsCertificate} information from this certificate in
271     * DER-encoded format.
272     *
273     * @return the DER-encoded certificate information.
274     * @throws CertificateEncodingException
275     *             if an error occurs in encoding
276     */
277    public abstract byte[] getTBSCertificate()
278                                    throws CertificateEncodingException;
279
280    /**
281     * Returns the raw signature bits from the certificate.
282     *
283     * @return the raw signature bits from the certificate.
284     */
285    public abstract byte[] getSignature();
286
287    /**
288     * Returns the name of the algorithm for the certificate signature.
289     *
290     * @return the signature algorithm name.
291     */
292    public abstract String getSigAlgName();
293
294    /**
295     * Returns the OID of the signature algorithm from the certificate.
296     *
297     * @return the OID of the signature algorithm.
298     */
299    public abstract String getSigAlgOID();
300
301    /**
302     * Returns the parameters of the signature algorithm in DER-encoded format.
303     *
304     * @return the parameters of the signature algorithm, or {@code null} if
305     *         none are used.
306     */
307    public abstract byte[] getSigAlgParams();
308
309    /**
310     * Returns the {@code issuerUniqueID} from the certificate.
311     *
312     * @return the {@code issuerUniqueID} or {@code null} if there's none in the
313     *         certificate.
314     */
315    public abstract boolean[] getIssuerUniqueID();
316
317    /**
318     * Returns the {@code subjectUniqueID} from the certificate.
319     *
320     * @return the {@code subjectUniqueID} or null if there's none in the
321     *         certificate.
322     */
323    public abstract boolean[] getSubjectUniqueID();
324
325    /**
326     * Returns the {@code KeyUsage} extension as a {@code boolean} array.
327     * <p>
328     * The ASN.1 definition of {@code KeyUsage}:
329     *
330     * <pre>
331     * KeyUsage ::= BIT STRING {
332     *      digitalSignature        (0),
333     *      nonRepudiation          (1),
334     *      keyEncipherment         (2),
335     *      dataEncipherment        (3),
336     *      keyAgreement            (4),
337     *      keyCertSign             (5),
338     *      cRLSign                 (6),
339     *      encipherOnly            (7),
340     *      decipherOnly            (8) }
341     *
342     * </pre>
343     *
344     * @return the {@code KeyUsage} extension or {@code null} if there's none in
345     *         the certificate.
346     */
347    public abstract boolean[] getKeyUsage();
348
349    /**
350     * Returns a read-only list of OID strings representing the {@code
351     * ExtKeyUsageSyntax} field of the extended key usage extension.
352     *
353     * @return the extended key usage extension, or {@code null} if there's none
354     *         in the certificate.
355     * @throws CertificateParsingException
356     *             if the extension decoding fails.
357     */
358    public List<String> getExtendedKeyUsage()
359                        throws CertificateParsingException {
360        return null;
361    }
362
363    /**
364     * Returns the path length of the certificate constraints from the {@code
365     * BasicContraints} extension.
366     *
367     * @return the path length of the certificate constraints if the extension
368     *         is present or {@code -1} if the extension is not present. {@code
369     *         Integer.MAX_VALUE} if there's not limit.
370     */
371    public abstract int getBasicConstraints();
372
373    /**
374     * Returns a read-only list of the subject alternative names from the
375     * {@code SubjectAltName} extension.
376     * <p>
377     * The ASN.1 definition of {@code SubjectAltName}:
378     *
379     * <pre>
380     * SubjectAltName ::= GeneralNames
381     *
382     * GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName
383     *
384     * GeneralName ::= CHOICE {
385     *      otherName                       [0]     AnotherName,
386     *      rfc822Name                      [1]     IA5String,
387     *      dNSName                         [2]     IA5String,
388     *      x400Address                     [3]     ORAddress,
389     *      directoryName                   [4]     Name,
390     *      ediPartyName                    [5]     EDIPartyName,
391     *      uniformResourceIdentifier       [6]     IA5String,
392     *      iPAddress                       [7]     OCTET STRING,
393     *      registeredID                    [8]     OBJECT IDENTIFIER }
394     *
395     * </pre>
396     *
397     * @return the subject alternative names or {@code null} if there are none
398     *         in the certificate.
399     * @throws CertificateParsingException
400     *             if decoding of the extension fails.
401     */
402    public Collection<List<?>> getSubjectAlternativeNames()
403                                    throws CertificateParsingException {
404        return null;
405    }
406
407    /**
408     * Returns a read-only list of the issuer alternative names from the {@code
409     * IssuerAltName} extension.
410     * <p>
411     * The ASN.1 definition of {@code IssuerAltName}:
412     *
413     * <pre>
414     * IssuerAltName ::= GeneralNames
415     *
416     * GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName
417     *
418     * GeneralName ::= CHOICE {
419     *      otherName                       [0]     AnotherName,
420     *      rfc822Name                      [1]     IA5String,
421     *      dNSName                         [2]     IA5String,
422     *      x400Address                     [3]     ORAddress,
423     *      directoryName                   [4]     Name,
424     *      ediPartyName                    [5]     EDIPartyName,
425     *      uniformResourceIdentifier       [6]     IA5String,
426     *      iPAddress                       [7]     OCTET STRING,
427     *      registeredID                    [8]     OBJECT IDENTIFIER }
428     *
429     * </pre>
430     *
431     * @return the issuer alternative names of {@code null} if there are none in
432     *         the certificate.
433     * @throws CertificateParsingException
434     *             if decoding of the extension fails.
435     */
436    public Collection<List<?>> getIssuerAlternativeNames()
437                                    throws CertificateParsingException {
438        return null;
439    }
440}
441