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
26package java.security.cert;
27
28import 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 */
58public 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        StringBuilder sb = new StringBuilder();
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