1 /* 2 * Copyright (c) 1997, 2020, 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 */ HandshakeCompletedEvent(SSLSocket sock, SSLSession s)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 */ getSession()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 */ getCipherSuite()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 */ getLocalCertificates()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 */ getPeerCertificates()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 * @throws SSLPeerUnverifiedException if the peer is not verified. 161 * @throws UnsupportedOperationException if the underlying provider 162 * does not implement the 163 * {@link SSLSession#getPeerCertificateChain} operation. 164 * @see #getPeerPrincipal() 165 * @deprecated The {@link #getPeerCertificates()} method that returns an 166 * array of {@code java.security.cert.Certificate} should 167 * be used instead. 168 */ 169 @SuppressWarnings("removal") 170 @Deprecated(since="9", forRemoval=true) getPeerCertificateChain()171 public javax.security.cert.X509Certificate [] getPeerCertificateChain() 172 throws SSLPeerUnverifiedException { 173 return session.getPeerCertificateChain(); 174 } 175 176 /** 177 * Returns the identity of the peer which was established as part of 178 * defining the session. 179 * 180 * @return the peer's principal. Returns an X500Principal of the 181 * end-entity certificate for X509-based cipher suites, and 182 * KerberosPrincipal for Kerberos cipher suites. 183 * 184 * @throws SSLPeerUnverifiedException if the peer's identity has not 185 * been verified 186 * 187 * @see #getPeerCertificates() 188 * @see #getLocalPrincipal() 189 * 190 * @since 1.5 191 */ getPeerPrincipal()192 public Principal getPeerPrincipal() 193 throws SSLPeerUnverifiedException 194 { 195 Principal principal; 196 try { 197 principal = session.getPeerPrincipal(); 198 } catch (AbstractMethodError e) { 199 // if the provider does not support it, fallback to peer certs. 200 // return the X500Principal of the end-entity cert. 201 Certificate[] certs = getPeerCertificates(); 202 principal = ((X509Certificate)certs[0]).getSubjectX500Principal(); 203 } 204 return principal; 205 } 206 207 /** 208 * Returns the principal that was sent to the peer during handshaking. 209 * 210 * @return the principal sent to the peer. Returns an X500Principal 211 * of the end-entity certificate for X509-based cipher suites, and 212 * KerberosPrincipal for Kerberos cipher suites. If no principal was 213 * sent, then null is returned. 214 * 215 * @see #getLocalCertificates() 216 * @see #getPeerPrincipal() 217 * 218 * @since 1.5 219 */ getLocalPrincipal()220 public Principal getLocalPrincipal() 221 { 222 Principal principal; 223 try { 224 principal = session.getLocalPrincipal(); 225 } catch (AbstractMethodError e) { 226 principal = null; 227 // if the provider does not support it, fallback to local certs. 228 // return the X500Principal of the end-entity cert. 229 Certificate[] certs = getLocalCertificates(); 230 if (certs != null) { 231 principal = 232 ((X509Certificate)certs[0]).getSubjectX500Principal(); 233 } 234 } 235 return principal; 236 } 237 238 /** 239 * Returns the socket which is the source of this event. 240 * (This is a convenience function, to let applications 241 * write code without type casts.) 242 * 243 * @return the socket on which the connection was made. 244 */ getSocket()245 public SSLSocket getSocket() 246 { 247 return (SSLSocket) getSource(); 248 } 249 } 250