1 /*
2  * Copyright (c) 2000, 2013, 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      */
PKIXCertPathValidatorResult(TrustAnchor trustAnchor, PolicyNode policyTree, PublicKey subjectPublicKey)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      */
getTrustAnchor()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      */
getPolicyTree()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      */
getPublicKey()125     public PublicKey getPublicKey() {
126         return subjectPublicKey;
127     }
128 
129     /**
130      * Returns a copy of this object.
131      *
132      * @return the copy
133      */
clone()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      */
toString()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 }
160