HandshakeCompletedEvent.java revision 11581:7a4b6292286b
1/* 2 * Copyright (c) 1997, 2015, 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 * 124 * @return an ordered array of the peer certificates, 125 * with the peer's own certificate first followed by 126 * any certificate authorities. 127 * @exception SSLPeerUnverifiedException if the peer is not verified. 128 * @see #getPeerPrincipal() 129 */ 130 public java.security.cert.Certificate [] getPeerCertificates() 131 throws SSLPeerUnverifiedException 132 { 133 return session.getPeerCertificates(); 134 } 135 136 137 /** 138 * Returns the identity of the peer which was identified as part 139 * of defining the session. 140 * Note: This method can be used only when using certificate-based 141 * cipher suites; using it with non-certificate-based cipher suites, 142 * such as Kerberos, will throw an SSLPeerUnverifiedException. 143 * 144 * <p><em>Note: this method exists for compatibility with previous 145 * releases. New applications should use 146 * {@link #getPeerCertificates} instead.</em></p> 147 * 148 * @return an ordered array of peer X.509 certificates, 149 * with the peer's own certificate first followed by any 150 * certificate authorities. (The certificates are in 151 * the original JSSE 152 * {@link javax.security.cert.X509Certificate} format). 153 * @exception SSLPeerUnverifiedException if the peer is not verified. 154 * @see #getPeerPrincipal() 155 * @deprecated The {@link #getPeerCertificates()} method that returns an 156 * array of {@code java.security.cert.Certificate} should 157 * be used instead. 158 */ 159 @Deprecated 160 public javax.security.cert.X509Certificate [] getPeerCertificateChain() 161 throws SSLPeerUnverifiedException 162 { 163 return session.getPeerCertificateChain(); 164 } 165 166 /** 167 * Returns the identity of the peer which was established as part of 168 * defining the session. 169 * 170 * @return the peer's principal. Returns an X500Principal of the 171 * end-entity certiticate for X509-based cipher suites, and 172 * KerberosPrincipal for Kerberos cipher suites. 173 * 174 * @throws SSLPeerUnverifiedException if the peer's identity has not 175 * been verified 176 * 177 * @see #getPeerCertificates() 178 * @see #getLocalPrincipal() 179 * 180 * @since 1.5 181 */ 182 public Principal getPeerPrincipal() 183 throws SSLPeerUnverifiedException 184 { 185 Principal principal; 186 try { 187 principal = session.getPeerPrincipal(); 188 } catch (AbstractMethodError e) { 189 // if the provider does not support it, fallback to peer certs. 190 // return the X500Principal of the end-entity cert. 191 Certificate[] certs = getPeerCertificates(); 192 principal = ((X509Certificate)certs[0]).getSubjectX500Principal(); 193 } 194 return principal; 195 } 196 197 /** 198 * Returns the principal that was sent to the peer during handshaking. 199 * 200 * @return the principal sent to the peer. Returns an X500Principal 201 * of the end-entity certificate for X509-based cipher suites, and 202 * KerberosPrincipal for Kerberos cipher suites. If no principal was 203 * sent, then null is returned. 204 * 205 * @see #getLocalCertificates() 206 * @see #getPeerPrincipal() 207 * 208 * @since 1.5 209 */ 210 public Principal getLocalPrincipal() 211 { 212 Principal principal; 213 try { 214 principal = session.getLocalPrincipal(); 215 } catch (AbstractMethodError e) { 216 principal = null; 217 // if the provider does not support it, fallback to local certs. 218 // return the X500Principal of the end-entity cert. 219 Certificate[] certs = getLocalCertificates(); 220 if (certs != null) { 221 principal = 222 ((X509Certificate)certs[0]).getSubjectX500Principal(); 223 } 224 } 225 return principal; 226 } 227 228 /** 229 * Returns the socket which is the source of this event. 230 * (This is a convenience function, to let applications 231 * write code without type casts.) 232 * 233 * @return the socket on which the connection was made. 234 */ 235 public SSLSocket getSocket() 236 { 237 return (SSLSocket) getSource(); 238 } 239} 240