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