1 /*
   2  * Copyright (c) 2000, 2011, 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.security.PublicKey;
  29 
  30 /**
  31  * This class represents the successful result of the PKIX certification
  32  * path validation algorithm.
  33  *
  34  * <p>Instances of {@code PKIXCertPathValidatorResult} are returned by the
  35  * {@link CertPathValidator#validate validate} method of
  36  * {@code CertPathValidator} objects implementing the PKIX algorithm.
  37  *
  38  * <p> All {@code PKIXCertPathValidatorResult} objects contain the
  39  * valid policy tree and subject public key resulting from the
  40  * validation algorithm, as well as a {@code TrustAnchor} describing
  41  * the certification authority (CA) that served as a trust anchor for the
  42  * certification path.
  43  * <p>
  44  * <b>Concurrent Access</b>
  45  * <p>
  46  * Unless otherwise specified, the methods defined in this class are not
  47  * thread-safe. Multiple threads that need to access a single
  48  * object concurrently should synchronize amongst themselves and
  49  * provide the necessary locking. Multiple threads each manipulating
  50  * separate objects need not synchronize.
  51  *
  52  * @see CertPathValidatorResult
  53  *
  54  * @since       1.4
  55  * @author      Yassir Elley
  56  * @author      Sean Mullan
  57  */
  58 public class PKIXCertPathValidatorResult implements CertPathValidatorResult {
  59 
  60     private TrustAnchor trustAnchor;
  61     private PolicyNode policyTree;
  62     private PublicKey subjectPublicKey;
  63 
  64     /**
  65      * Creates an instance of {@code PKIXCertPathValidatorResult}
  66      * containing the specified parameters.
  67      *
  68      * @param trustAnchor a {@code TrustAnchor} describing the CA that
  69      * served as a trust anchor for the certification path
  70      * @param policyTree the immutable valid policy tree, or {@code null}
  71      * if there are no valid policies
  72      * @param subjectPublicKey the public key of the subject
  73      * @throws NullPointerException if the {@code subjectPublicKey} or
  74      * {@code trustAnchor} parameters are {@code null}
  75      */
  76     public PKIXCertPathValidatorResult(TrustAnchor trustAnchor,
  77         PolicyNode policyTree, PublicKey subjectPublicKey)
  78     {
  79         if (subjectPublicKey == null)
  80             throw new NullPointerException("subjectPublicKey must be non-null");
  81         if (trustAnchor == null)
  82             throw new NullPointerException("trustAnchor must be non-null");
  83         this.trustAnchor = trustAnchor;
  84         this.policyTree = policyTree;
  85         this.subjectPublicKey = subjectPublicKey;
  86     }
  87 
  88     /**
  89      * Returns the {@code TrustAnchor} describing the CA that served
  90      * as a trust anchor for the certification path.
  91      *
  92      * @return the {@code TrustAnchor} (never {@code null})
  93      */
  94     public TrustAnchor getTrustAnchor() {
  95         return trustAnchor;
  96     }
  97 
  98     /**
  99      * Returns the root node of the valid policy tree resulting from the
 100      * PKIX certification path validation algorithm. The
 101      * {@code PolicyNode} object that is returned and any objects that
 102      * it returns through public methods are immutable.
 103      *
 104      * <p>Most applications will not need to examine the valid policy tree.
 105      * They can achieve their policy processing goals by setting the
 106      * policy-related parameters in {@code PKIXParameters}. However, more
 107      * sophisticated applications, especially those that process policy
 108      * qualifiers, may need to traverse the valid policy tree using the
 109      * {@link PolicyNode#getParent PolicyNode.getParent} and
 110      * {@link PolicyNode#getChildren PolicyNode.getChildren} methods.
 111      *
 112      * @return the root node of the valid policy tree, or {@code null}
 113      * if there are no valid policies
 114      */
 115     public PolicyNode getPolicyTree() {
 116         return policyTree;
 117     }
 118 
 119     /**
 120      * Returns the public key of the subject (target) of the certification
 121      * path, including any inherited public key parameters if applicable.
 122      *
 123      * @return the public key of the subject (never {@code null})
 124      */
 125     public PublicKey getPublicKey() {
 126         return subjectPublicKey;
 127     }
 128 
 129     /**
 130      * Returns a copy of this object.
 131      *
 132      * @return the copy
 133      */
 134     public Object clone() {
 135         try {
 136             return super.clone();
 137         } catch (CloneNotSupportedException e) {
 138             /* Cannot happen */
 139             throw new InternalError(e.toString(), e);
 140         }
 141     }
 142 
 143     /**
 144      * Return a printable representation of this
 145      * {@code PKIXCertPathValidatorResult}.
 146      *
 147      * @return a {@code String} describing the contents of this
 148      *         {@code PKIXCertPathValidatorResult}
 149      */
 150     public String toString() {
 151         StringBuffer sb = new StringBuffer();
 152         sb.append("PKIXCertPathValidatorResult: [\n");
 153         sb.append("  Trust Anchor: " + trustAnchor.toString() + "\n");
 154         sb.append("  Policy Tree: " + String.valueOf(policyTree) + "\n");
 155         sb.append("  Subject Public Key: " + subjectPublicKey + "\n");
 156         sb.append("]");
 157         return sb.toString();
 158     }
 159 }