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