      1 /*
      2  * Copyright (c) 2000, 2021, Oracle and/or its affiliates. All rights reserved.
      3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
      4  *
      5  * This code is free software; you can redistribute it and/or modify it
      6  * under the terms of the GNU General Public License version 2 only, as
      7  * published by the Free Software Foundation.  Oracle designates this
      8  * particular file as subject to the "Classpath" exception as provided
      9  * by Oracle in the LICENSE file that accompanied this code.
     10  *
     11  * This code is distributed in the hope that it will be useful, but WITHOUT
     12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
     13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
     14  * version 2 for more details (a copy is included in the LICENSE file that
     15  * accompanied this code).
     16  *
     17  * You should have received a copy of the GNU General Public License version
     18  * 2 along with this work; if not, write to the Free Software Foundation,
     19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
     20  *
     21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
     22  * or visit www.oracle.com if you need additional information or have any
     23  * questions.
     24  */
     25
     26 package java.security.cert;
     27
     28 import java.io.ByteArrayInputStream;
     29 import java.io.NotSerializableException;
     30 import java.io.ObjectStreamException;
     31 import java.io.Serializable;
     32 import java.util.Iterator;
     33 import java.util.List;
     34
     35 /**
     36  * An immutable sequence of certificates (a certification path).
     37  * <p>
     38  * This is an abstract class that defines the methods common to all
     39  * {@code CertPath}s. Subclasses can handle different kinds of
     40  * certificates (X.509, PGP, etc.).
     41  * <p>
     42  * All {@code CertPath} objects have a type, a list of
     43  * {@code Certificate}s, and one or more supported encodings. Because the
     44  * {@code CertPath} class is immutable, a {@code CertPath} cannot
     45  * change in any externally visible way after being constructed. This
     46  * stipulation applies to all public fields and methods of this class and any
     47  * added or overridden by subclasses.
     48  * <p>
     49  * The type is a {@code String} that identifies the type of
     50  * {@code Certificate}s in the certification path. For each
     51  * certificate {@code cert} in a certification path {@code certPath},
     52  * {@code cert.getType().equals(certPath.getType())} must be
     53  * {@code true}.
     54  * <p>
     55  * The list of {@code Certificate}s is an ordered {@code List} of
     56  * zero or more {@code Certificate}s. This {@code List} and all
     57  * of the {@code Certificate}s contained in it must be immutable.
     58  * <p>
     59  * Each {@code CertPath} object must support one or more encodings
     60  * so that the object can be translated into a byte array for storage or
     61  * transmission to other parties. Preferably, these encodings should be
     62  * well-documented standards (such as PKCS#7). One of the encodings supported
     63  * by a {@code CertPath} is considered the default encoding. This
     64  * encoding is used if no encoding is explicitly requested (for the
     65  * {@link #getEncoded() getEncoded()} method, for instance).
     66  * <p>
     67  * All {@code CertPath} objects are also {@code Serializable}.
     68  * {@code CertPath} objects are resolved into an alternate
     69  * {@link CertPathRep CertPathRep} object during serialization. This allows
     70  * a {@code CertPath} object to be serialized into an equivalent
     71  * representation regardless of its underlying implementation.
     72  * <p>
     73  * {@code CertPath} objects can be created with a
     74  * {@code CertificateFactory} or they can be returned by other classes,
     75  * such as a {@code CertPathBuilder}.
     76  * <p>
     77  * By convention, X.509 {@code CertPath}s (consisting of
     78  * {@code X509Certificate}s), are ordered starting with the target
     79  * certificate and ending with a certificate issued by the trust anchor. That
     80  * is, the issuer of one certificate is the subject of the following one. The
     81  * certificate representing the {@link TrustAnchor TrustAnchor} should not be
     82  * included in the certification path. Unvalidated X.509 {@code CertPath}s
     83  * may not follow these conventions. PKIX {@code CertPathValidator}s will
     84  * detect any departure from these conventions that cause the certification
     85  * path to be invalid and throw a {@code CertPathValidatorException}.
     86  *
     87  * <p> Every implementation of the Java platform is required to support the
     88  * following standard {@code CertPath} encodings:
     89  * <ul>
     90  * <li>{@code PKCS7}</li>
     91  * <li>{@code PkiPath}</li>
     92  * </ul>
     93  * These encodings are described in the <a href=
     94  * "{@docRoot}/../specs/security/standard-names.html#certpath-encodings">
     95  * CertPath Encodings section</a> of the
     96  * Java Security Standard Algorithm Names Specification.
     97  * Consult the release documentation for your implementation to see if any
     98  * other encodings are supported.
     99  * <p>
    100  * <b>Concurrent Access</b>
    101  * <p>
    102  * All {@code CertPath} objects must be thread-safe. That is, multiple
    103  * threads may concurrently invoke the methods defined in this class on a
    104  * single {@code CertPath} object (or more than one) with no
    105  * ill effects. This is also true for the {@code List} returned by
    106  * {@code CertPath.getCertificates}.
    107  * <p>
    108  * Requiring {@code CertPath} objects to be immutable and thread-safe
    109  * allows them to be passed around to various pieces of code without worrying
    110  * about coordinating access.  Providing this thread-safety is
    111  * generally not difficult, since the {@code CertPath} and
    112  * {@code List} objects in question are immutable.
    113  *
    114  * @see CertificateFactory
    115  * @see CertPathBuilder
    116  *
    117  * @author      Yassir Elley
    118  * @since       1.4
    119  */
    120 public abstract class CertPath implements Serializable {
    121
    122     @java.io.Serial
    123     private static final long serialVersionUID = 6068470306649138683L;
    124
    125     /** The type of certificates in this chain. */
    126     private String type;
    127
    128     /**
    129      * Creates a {@code CertPath} of the specified type.
    130      * <p>
    131      * This constructor is protected because most users should use a
    132      * {@code CertificateFactory} to create {@code CertPath}s.
    133      *
    134      * @param type the standard name of the type of
    135      * {@code Certificate}s in this path
    136      */
    137     protected CertPath(String type) {
    138         this.type = type;
    139     }
    140
    141     /**
    142      * Returns the type of {@code Certificate}s in this certification
    143      * path. This is the same string that would be returned by
    144      * {@link java.security.cert.Certificate#getType() cert.getType()}
    145      * for all {@code Certificate}s in the certification path.
    146      *
    147      * @return the type of {@code Certificate}s in this certification
    148      * path (never null)
    149      */
    150     public String getType() {
    151         return type;
    152     }
    153
    154     /**
    155      * Returns an iteration of the encodings supported by this certification
    156      * path, with the default encoding first. Attempts to modify the returned
    157      * {@code Iterator} via its {@code remove} method result in an
    158      * {@code UnsupportedOperationException}.
    159      *
    160      * @return an {@code Iterator} over the names of the supported
    161      *         encodings (as Strings)
    162      */
    163     public abstract Iterator<String> getEncodings();
    164
    165     /**
    166      * Compares this certification path for equality with the specified
    167      * object. Two {@code CertPath}s are equal if and only if their
    168      * types are equal and their certificate {@code List}s (and by
    169      * implication the {@code Certificate}s in those {@code List}s)
    170      * are equal. A {@code CertPath} is never equal to an object that is
    171      * not a {@code CertPath}.
    172      * <p>
    173      * This algorithm is implemented by this method. If it is overridden,
    174      * the behavior specified here must be maintained.
    175      *
    176      * @param other the object to test for equality with this certification path
    177      * @return true if the specified object is equal to this certification path,
    178      * false otherwise
    179      */
    180     public boolean equals(Object other) {
    181         if (this == other)
    182             return true;
    183
    184         if (! (other instanceof CertPath))
    185             return false;
    186
    187         CertPath otherCP = (CertPath) other;
    188         if (! otherCP.getType().equals(type))
    189             return false;
    190
    191         List<? extends Certificate> thisCertList = this.getCertificates();
    192         List<? extends Certificate> otherCertList = otherCP.getCertificates();
    193         return(thisCertList.equals(otherCertList));
    194     }
    195
    196     /**
    197      * Returns the hashcode for this certification path. The hash code of
    198      * a certification path is defined to be the result of the following
    199      * calculation:
    200      * <pre>{@code
    201      *  hashCode = path.getType().hashCode();
    202      *  hashCode = 31*hashCode + path.getCertificates().hashCode();
    203      * }</pre>
    204      * This ensures that {@code path1.equals(path2)} implies that
    205      * {@code path1.hashCode()==path2.hashCode()} for any two certification
    206      * paths, {@code path1} and {@code path2}, as required by the
    207      * general contract of {@code Object.hashCode}.
    208      *
    209      * @return the hashcode value for this certification path
    210      */
    211     public int hashCode() {
    212         int hashCode = type.hashCode();
    213         hashCode = 31*hashCode + getCertificates().hashCode();
    214         return hashCode;
    215     }
    216
    217     /**
    218      * Returns a string representation of this certification path.
    219      * This calls the {@code toString} method on each of the
    220      * {@code Certificate}s in the path.
    221      *
    222      * @return a string representation of this certification path
    223      */
    224     public String toString() {
    225         StringBuilder sb = new StringBuilder();
    226         Iterator<? extends Certificate> stringIterator =
    227                                         getCertificates().iterator();
    228
    229         sb.append("\n" + type + " Cert Path: length = "
    230             + getCertificates().size() + ".\n");
    231         sb.append("[\n");
    232         int i = 1;
    233         while (stringIterator.hasNext()) {
    234             sb.append("=========================================="
    235                 + "===============Certificate " + i + " start.\n");
    236             Certificate stringCert = stringIterator.next();
    237             sb.append(stringCert.toString());
    238             sb.append("\n========================================"
    239                 + "=================Certificate " + i + " end.\n\n\n");
    240             i++;
    241         }
    242
    243         sb.append("\n]");
    244         return sb.toString();
    245     }
    246
    247     /**
    248      * Returns the encoded form of this certification path, using the default
    249      * encoding.
    250      *
    251      * @return the encoded bytes
    252      * @throws    CertificateEncodingException if an encoding error occurs
    253      */
    254     public abstract byte[] getEncoded()
    255         throws CertificateEncodingException;
    256
    257     /**
    258      * Returns the encoded form of this certification path, using the
    259      * specified encoding.
    260      *
    261      * @param encoding the name of the encoding to use
    262      * @return the encoded bytes
    263      * @throws    CertificateEncodingException if an encoding error occurs or
    264      *   the encoding requested is not supported
    265      */
    266     public abstract byte[] getEncoded(String encoding)
    267         throws CertificateEncodingException;
    268
    269     /**
    270      * Returns the list of certificates in this certification path.
    271      * The {@code List} returned must be immutable and thread-safe.
    272      *
    273      * @return an immutable {@code List} of {@code Certificate}s
    274      *         (may be empty, but not null)
    275      */
    276     public abstract List<? extends Certificate> getCertificates();
    277
    278     /**
    279      * Replaces the {@code CertPath} to be serialized with a
    280      * {@code CertPathRep} object.
    281      *
    282      * @return the {@code CertPathRep} to be serialized
    283      *
    284      * @throws ObjectStreamException if a {@code CertPathRep} object
    285      * representing this certification path could not be created
    286      */
    287     @java.io.Serial
    288     protected Object writeReplace() throws ObjectStreamException {
    289         try {
    290             return new CertPathRep(type, getEncoded());
    291         } catch (CertificateException ce) {
    292             NotSerializableException nse =
    293                 new NotSerializableException
    294                     ("java.security.cert.CertPath: " + type);
    295             nse.initCause(ce);
    296             throw nse;
    297         }
    298     }
    299
    300     /**
    301      * Alternate {@code CertPath} class for serialization.
    302      * @since 1.4
    303      */
    304     protected static class CertPathRep implements Serializable {
    305
    306         @java.io.Serial
    307         private static final long serialVersionUID = 3015633072427920915L;
    308
    309         /** The Certificate type */
    310         private String type;
    311         /** The encoded form of the cert path */
    312         private byte[] data;
    313
    314         /**
    315          * Creates a {@code CertPathRep} with the specified
    316          * type and encoded form of a certification path.
    317          *
    318          * @param type the standard name of a {@code CertPath} type
    319          * @param data the encoded form of the certification path
    320          */
    321         protected CertPathRep(String type, byte[] data) {
    322             this.type = type;
    323             this.data = data;
    324         }
    325
    326         /**
    327          * Returns a {@code CertPath} constructed from the type and data.
    328          *
    329          * @return the resolved {@code CertPath} object
    330          *
    331          * @throws ObjectStreamException if a {@code CertPath} could not
    332          * be constructed
    333          */
    334         @java.io.Serial
    335         protected Object readResolve() throws ObjectStreamException {
    336             try {
    337                 CertificateFactory cf = CertificateFactory.getInstance(type);
    338                 return cf.generateCertPath(new ByteArrayInputStream(data));
    339             } catch (CertificateException ce) {
    340                 NotSerializableException nse =
    341                     new NotSerializableException
    342                         ("java.security.cert.CertPath: " + type);
    343                 nse.initCause(ce);
    344                 throw nse;
    345             }
    346         }
    347     }
    348 }