1 /*
2 * Copyright (c) 1997, 2019, 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 javax.net.ssl;
27
28 import java.util.EventObject;
29 import java.security.cert.Certificate;
30 import java.security.Principal;
31 import java.security.cert.X509Certificate;
32
33 /**
34 * This event indicates that an SSL handshake completed on a given
35 * SSL connection. All of the core information about that handshake's
36 * result is captured through an "SSLSession" object. As a convenience,
37 * this event class provides direct access to some important session
38 * attributes.
39 *
40 * <P> The source of this event is the SSLSocket on which handshaking
41 * just completed.
42 *
43 * @see SSLSocket
44 * @see HandshakeCompletedListener
45 * @see SSLSession
46 *
47 * @since 1.4
48 * @author David Brownell
49 */
50 public class HandshakeCompletedEvent extends EventObject
51 {
52 @java.io.Serial
53 private static final long serialVersionUID = 7914963744257769778L;
54
55 private transient SSLSession session;
56
57 /**
58 * Constructs a new HandshakeCompletedEvent.
59 *
60 * @param sock the SSLSocket acting as the source of the event
61 * @param s the SSLSession this event is associated with
62 */
63 public HandshakeCompletedEvent(SSLSocket sock, SSLSession s)
64 {
65 super(sock);
66 session = s;
67 }
68
69
70 /**
71 * Returns the session that triggered this event.
72 *
73 * @return the <code>SSLSession</code> for this handshake
74 */
75 public SSLSession getSession()
76 {
77 return session;
78 }
79
80
81 /**
82 * Returns the cipher suite in use by the session which was produced
83 * by the handshake. (This is a convenience method for
84 * getting the ciphersuite from the SSLsession.)
85 *
86 * @return the name of the cipher suite negotiated during this session.
87 */
88 public String getCipherSuite()
89 {
90 return session.getCipherSuite();
91 }
92
93
94 /**
95 * Returns the certificate(s) that were sent to the peer during
96 * handshaking.
97 * Note: This method is useful only when using certificate-based
98 * cipher suites.
99 *
100 * When multiple certificates are available for use in a
101 * handshake, the implementation chooses what it considers the
102 * "best" certificate chain available, and transmits that to
103 * the other side. This method allows the caller to know
104 * which certificate chain was actually used.
105 *
106 * @return an ordered array of certificates, with the local
107 * certificate first followed by any
108 * certificate authorities. If no certificates were sent,
109 * then null is returned.
110 * @see #getLocalPrincipal()
111 */
112 public java.security.cert.Certificate [] getLocalCertificates()
113 {
114 return session.getLocalCertificates();
115 }
116
117
118 /**
119 * Returns the identity of the peer which was established as part
120 * of defining the session.
121 * Note: This method can be used only when using certificate-based
122 * cipher suites; using it with non-certificate-based cipher suites,
123 * such as Kerberos, will throw an SSLPeerUnverifiedException.
124 * <P>
125 * Note: The returned value may not be a valid certificate chain
126 * and should not be relied on for trust decisions.
127 *
128 * @return an ordered array of the peer certificates,
129 * with the peer's own certificate first followed by
130 * any certificate authorities.
131 * @exception SSLPeerUnverifiedException if the peer is not verified.
132 * @see #getPeerPrincipal()
133 */
134 public java.security.cert.Certificate [] getPeerCertificates()
135 throws SSLPeerUnverifiedException
136 {
137 return session.getPeerCertificates();
138 }
139
140
141 /**
142 * Returns the identity of the peer which was identified as part
143 * of defining the session.
144 * Note: This method can be used only when using certificate-based
145 * cipher suites; using it with non-certificate-based cipher suites,
146 * such as Kerberos, will throw an SSLPeerUnverifiedException.
147 * <P>
148 * Note: The returned value may not be a valid certificate chain
149 * and should not be relied on for trust decisions.
150 *
151 * <p><em>Note: this method exists for compatibility with previous
152 * releases. New applications should use
153 * {@link #getPeerCertificates} instead.</em></p>
154 *
155 * @return an ordered array of peer X.509 certificates,
156 * with the peer's own certificate first followed by any
157 * certificate authorities. (The certificates are in
158 * the original JSSE
159 * {@link javax.security.cert.X509Certificate} format).
160 * @exception SSLPeerUnverifiedException if the peer is not verified.
161 * @see #getPeerPrincipal()
162 * @deprecated The {@link #getPeerCertificates()} method that returns an
163 * array of {@code java.security.cert.Certificate} should
164 * be used instead.
165 */
166 @SuppressWarnings("removal")
167 @Deprecated(since="9", forRemoval=true)
168 public javax.security.cert.X509Certificate [] getPeerCertificateChain()
169 throws SSLPeerUnverifiedException
170 {
171 return session.getPeerCertificateChain();
172 }
173
174 /**
175 * Returns the identity of the peer which was established as part of
176 * defining the session.
177 *
178 * @return the peer's principal. Returns an X500Principal of the
179 * end-entity certiticate for X509-based cipher suites, and
180 * KerberosPrincipal for Kerberos cipher suites.
181 *
182 * @throws SSLPeerUnverifiedException if the peer's identity has not
183 * been verified
184 *
185 * @see #getPeerCertificates()
186 * @see #getLocalPrincipal()
187 *
188 * @since 1.5
189 */
190 public Principal getPeerPrincipal()
191 throws SSLPeerUnverifiedException
192 {
193 Principal principal;
194 try {
195 principal = session.getPeerPrincipal();
196 } catch (AbstractMethodError e) {
197 // if the provider does not support it, fallback to peer certs.
198 // return the X500Principal of the end-entity cert.
199 Certificate[] certs = getPeerCertificates();
200 principal = ((X509Certificate)certs[0]).getSubjectX500Principal();
201 }
202 return principal;
203 }
204
205 /**
206 * Returns the principal that was sent to the peer during handshaking.
207 *
208 * @return the principal sent to the peer. Returns an X500Principal
209 * of the end-entity certificate for X509-based cipher suites, and
210 * KerberosPrincipal for Kerberos cipher suites. If no principal was
211 * sent, then null is returned.
212 *
213 * @see #getLocalCertificates()
214 * @see #getPeerPrincipal()
215 *
216 * @since 1.5
217 */
218 public Principal getLocalPrincipal()
219 {
220 Principal principal;
221 try {
222 principal = session.getLocalPrincipal();
223 } catch (AbstractMethodError e) {
224 principal = null;
225 // if the provider does not support it, fallback to local certs.
226 // return the X500Principal of the end-entity cert.
227 Certificate[] certs = getLocalCertificates();
228 if (certs != null) {
229 principal =
230 ((X509Certificate)certs[0]).getSubjectX500Principal();
231 }
232 }
233 return principal;
234 }
235
236 /**
237 * Returns the socket which is the source of this event.
238 * (This is a convenience function, to let applications
239 * write code without type casts.)
240 *
241 * @return the socket on which the connection was made.
242 */
243 public SSLSocket getSocket()
244 {
245 return (SSLSocket) getSource();
246 }
247 }