1 /*
2  * Copyright (c) 2000, 2012, 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 sun.security.provider.certpath;
27 
28 import java.security.cert.X509Certificate;
29 
30 /**
31  * Describes one step of a certification path build, consisting of a
32  * <code>Vertex</code> state description, a certificate, a possible throwable,
33  * and a result code.
34  *
35  * @author      Anne Anderson
36  * @since       1.4
37  * @see sun.security.provider.certpath.Vertex
38  */
39 public class BuildStep {
40 
41     private Vertex          vertex;
42     private X509Certificate cert;
43     private Throwable       throwable;
44     private int             result;
45 
46     /**
47      * result code associated with a certificate that may continue a path from
48      * the current certificate.
49      */
50     public static final int POSSIBLE = 1;
51 
52     /**
53      * result code associated with a certificate that was tried, but that
54      * represents an unsuccessful path, so the certificate has been backed out
55      * to allow backtracking to the next possible path.
56      */
57     public static final int BACK = 2;
58 
59     /**
60      * result code associated with a certificate that successfully continues the
61      * current path, but does not yet reach the target.
62      */
63     public static final int FOLLOW = 3;
64 
65     /**
66      * result code associated with a certificate that represents the end of the
67      * last possible path, where no path successfully reached the target.
68      */
69     public static final int FAIL = 4;
70 
71     /**
72      * result code associated with a certificate that represents the end of a
73      * path that successfully reaches the target.
74      */
75     public static final int SUCCEED = 5;
76 
77     /**
78      * construct a BuildStep
79      *
80      * @param vtx description of the vertex at this step
81      * @param res result, where result is one of POSSIBLE, BACK,
82      *            FOLLOW, FAIL, SUCCEED
83      */
BuildStep(Vertex vtx, int res)84     public BuildStep(Vertex vtx, int res) {
85         vertex = vtx;
86         if (vertex != null) {
87             cert = vertex.getCertificate();
88             throwable = vertex.getThrowable();
89         }
90         result = res;
91     }
92 
93     /**
94      * return vertex description for this build step
95      *
96      * @returns Vertex
97      */
getVertex()98     public Vertex getVertex() {
99         return vertex;
100     }
101 
102     /**
103      * return the certificate associated with this build step
104      *
105      * @returns X509Certificate
106      */
getCertificate()107     public X509Certificate getCertificate() {
108         return cert;
109     }
110 
111     /**
112      * return string form of issuer name from certificate associated with this
113      * build step
114      *
115      * @returns String form of issuer name or null, if no certificate.
116      */
getIssuerName()117     public String getIssuerName() {
118         return getIssuerName(null);
119     }
120 
121     /**
122      * return string form of issuer name from certificate associated with this
123      * build step, or a default name if no certificate associated with this
124      * build step, or if issuer name could not be obtained from the certificate.
125      *
126      * @param defaultName name to use as default if unable to return an issuer
127      * name from the certificate, or if no certificate.
128      * @returns String form of issuer name or defaultName, if no certificate or
129      * exception received while trying to extract issuer name from certificate.
130      */
getIssuerName(String defaultName)131     public String getIssuerName(String defaultName) {
132         return (cert == null ? defaultName
133                              : cert.getIssuerX500Principal().toString());
134     }
135 
136     /**
137      * return string form of subject name from certificate associated with this
138      * build step.
139      *
140      * @returns String form of subject name or null, if no certificate.
141      */
getSubjectName()142     public String getSubjectName() {
143         return getSubjectName(null);
144     }
145 
146     /**
147      * return string form of subject name from certificate associated with this
148      * build step, or a default name if no certificate associated with this
149      * build step, or if subject name could not be obtained from the
150      * certificate.
151      *
152      * @param defaultName name to use as default if unable to return a subject
153      * name from the certificate, or if no certificate.
154      * @returns String form of subject name or defaultName, if no certificate or
155      * if an exception was received while attempting to extract the subject name
156      * from the certificate.
157      */
getSubjectName(String defaultName)158     public String getSubjectName(String defaultName) {
159         return (cert == null ? defaultName
160                              : cert.getSubjectX500Principal().toString());
161     }
162 
163     /**
164      * return the exception associated with this build step.
165      *
166      * @returns Throwable
167      */
getThrowable()168     public Throwable getThrowable() {
169         return throwable;
170     }
171 
172     /**
173      * return the result code associated with this build step.  The result codes
174      * are POSSIBLE, FOLLOW, BACK, FAIL, SUCCEED.
175      *
176      * @returns int result code
177      */
getResult()178     public int getResult() {
179         return result;
180     }
181 
182     /**
183      * return a string representing the meaning of the result code associated
184      * with this build step.
185      *
186      * @param   res    result code
187      * @returns String string representing meaning of the result code
188      */
resultToString(int res)189     public String resultToString(int res) {
190         String resultString = "";
191         switch (res) {
192             case POSSIBLE:
193                 resultString = "Certificate to be tried.\n";
194                 break;
195             case BACK:
196                 resultString = "Certificate backed out since path does not "
197                     + "satisfy build requirements.\n";
198                 break;
199             case FOLLOW:
200                 resultString = "Certificate satisfies conditions.\n";
201                 break;
202             case FAIL:
203                 resultString = "Certificate backed out since path does not "
204                     + "satisfy conditions.\n";
205                 break;
206             case SUCCEED:
207                 resultString = "Certificate satisfies conditions.\n";
208                 break;
209             default:
210                 resultString = "Internal error: Invalid step result value.\n";
211         }
212         return resultString;
213     }
214 
215     /**
216      * return a string representation of this build step, showing minimal
217      * detail.
218      *
219      * @returns String
220      */
221     @Override
toString()222     public String toString() {
223         String out = "Internal Error\n";
224         switch (result) {
225         case BACK:
226         case FAIL:
227             out = resultToString(result);
228             out = out + vertex.throwableToString();
229             break;
230         case FOLLOW:
231         case SUCCEED:
232         case POSSIBLE:
233             out = resultToString(result);
234             break;
235         default:
236             out = "Internal Error: Invalid step result\n";
237         }
238         return out;
239     }
240 
241     /**
242      * return a string representation of this build step, showing all detail of
243      * the vertex state appropriate to the result of this build step, and the
244      * certificate contents.
245      *
246      * @returns String
247      */
verboseToString()248     public String verboseToString() {
249         String out = resultToString(getResult());
250         switch (result) {
251         case BACK:
252         case FAIL:
253             out = out + vertex.throwableToString();
254             break;
255         case FOLLOW:
256         case SUCCEED:
257             out = out + vertex.moreToString();
258             break;
259         case POSSIBLE:
260             break;
261         default:
262             break;
263         }
264         out = out + "Certificate contains:\n" + vertex.certToString();
265         return out;
266     }
267 
268     /**
269      * return a string representation of this build step, including all possible
270      * detail of the vertex state, but not including the certificate contents.
271      *
272      * @returns String
273      */
fullToString()274     public String fullToString() {
275         return resultToString(getResult()) + vertex.toString();
276     }
277 }
278