001 /*
002 * Copyright 1997-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.net.ssl;
027
028 import java.util.EventObject;
029 import java.security.cert.Certificate;
030 import java.security.Principal;
031 import java.security.cert.X509Certificate;
032 import javax.security.auth.x500.X500Principal;
033
034 /**
035 * This event indicates that an SSL handshake completed on a given
036 * SSL connection. All of the core information about that handshake's
037 * result is captured through an "SSLSession" object. As a convenience,
038 * this event class provides direct access to some important session
039 * attributes.
040 *
041 * <P> The source of this event is the SSLSocket on which handshaking
042 * just completed.
043 *
044 * @see SSLSocket
045 * @see HandshakeCompletedListener
046 * @see SSLSession
047 *
048 * @since 1.4
049 * @version 1.29
050 * @author David Brownell
051 */
052 public class HandshakeCompletedEvent extends EventObject {
053 private static final long serialVersionUID = 7914963744257769778L;
054
055 private transient SSLSession session;
056
057 /**
058 * Constructs a new HandshakeCompletedEvent.
059 *
060 * @param sock the SSLSocket acting as the source of the event
061 * @param s the SSLSession this event is associated with
062 */
063 public HandshakeCompletedEvent(SSLSocket sock, SSLSession s) {
064 super (sock);
065 session = s;
066 }
067
068 /**
069 * Returns the session that triggered this event.
070 *
071 * @return the <code>SSLSession</code> for this handshake
072 */
073 public SSLSession getSession() {
074 return session;
075 }
076
077 /**
078 * Returns the cipher suite in use by the session which was produced
079 * by the handshake. (This is a convenience method for
080 * getting the ciphersuite from the SSLsession.)
081 *
082 * @return the name of the cipher suite negotiated during this session.
083 */
084 public String getCipherSuite() {
085 return session.getCipherSuite();
086 }
087
088 /**
089 * Returns the certificate(s) that were sent to the peer during
090 * handshaking.
091 * Note: This method is useful only when using certificate-based
092 * cipher suites.
093 *
094 * When multiple certificates are available for use in a
095 * handshake, the implementation chooses what it considers the
096 * "best" certificate chain available, and transmits that to
097 * the other side. This method allows the caller to know
098 * which certificate chain was actually used.
099 *
100 * @return an ordered array of certificates, with the local
101 * certificate first followed by any
102 * certificate authorities. If no certificates were sent,
103 * then null is returned.
104 * @see #getLocalPrincipal()
105 */
106 public java.security.cert.Certificate[] getLocalCertificates() {
107 return session.getLocalCertificates();
108 }
109
110 /**
111 * Returns the identity of the peer which was established as part
112 * of defining the session.
113 * Note: This method can be used only when using certificate-based
114 * cipher suites; using it with non-certificate-based cipher suites,
115 * such as Kerberos, will throw an SSLPeerUnverifiedException.
116 *
117 * @return an ordered array of the peer certificates,
118 * with the peer's own certificate first followed by
119 * any certificate authorities.
120 * @exception SSLPeerUnverifiedException if the peer is not verified.
121 * @see #getPeerPrincipal()
122 */
123 public java.security.cert.Certificate[] getPeerCertificates()
124 throws SSLPeerUnverifiedException {
125 return session.getPeerCertificates();
126 }
127
128 /**
129 * Returns the identity of the peer which was identified as part
130 * of defining the session.
131 * Note: This method can be used only when using certificate-based
132 * cipher suites; using it with non-certificate-based cipher suites,
133 * such as Kerberos, will throw an SSLPeerUnverifiedException.
134 *
135 * <p><em>Note: this method exists for compatibility with previous
136 * releases. New applications should use
137 * {@link #getPeerCertificates} instead.</em></p>
138 *
139 * @return an ordered array of peer X.509 certificates,
140 * with the peer's own certificate first followed by any
141 * certificate authorities. (The certificates are in
142 * the original JSSE
143 * {@link javax.security.cert.X509Certificate} format).
144 * @exception SSLPeerUnverifiedException if the peer is not verified.
145 * @see #getPeerPrincipal()
146 */
147 public javax.security.cert.X509Certificate[] getPeerCertificateChain()
148 throws SSLPeerUnverifiedException {
149 return session.getPeerCertificateChain();
150 }
151
152 /**
153 * Returns the identity of the peer which was established as part of
154 * defining the session.
155 *
156 * @return the peer's principal. Returns an X500Principal of the
157 * end-entity certiticate for X509-based cipher suites, and
158 * KerberosPrincipal for Kerberos cipher suites.
159 *
160 * @throws SSLPeerUnverifiedException if the peer's identity has not
161 * been verified
162 *
163 * @see #getPeerCertificates()
164 * @see #getLocalPrincipal()
165 *
166 * @since 1.5
167 */
168 public Principal getPeerPrincipal()
169 throws SSLPeerUnverifiedException {
170 Principal principal;
171 try {
172 principal = session.getPeerPrincipal();
173 } catch (AbstractMethodError e) {
174 // if the provider does not support it, fallback to peer certs.
175 // return the X500Principal of the end-entity cert.
176 Certificate[] certs = getPeerCertificates();
177 principal = (X500Principal) ((X509Certificate) certs[0])
178 .getSubjectX500Principal();
179 }
180 return principal;
181 }
182
183 /**
184 * Returns the principal that was sent to the peer during handshaking.
185 *
186 * @return the principal sent to the peer. Returns an X500Principal
187 * of the end-entity certificate for X509-based cipher suites, and
188 * KerberosPrincipal for Kerberos cipher suites. If no principal was
189 * sent, then null is returned.
190 *
191 * @see #getLocalCertificates()
192 * @see #getPeerPrincipal()
193 *
194 * @since 1.5
195 */
196 public Principal getLocalPrincipal() {
197 Principal principal;
198 try {
199 principal = session.getLocalPrincipal();
200 } catch (AbstractMethodError e) {
201 principal = null;
202 // if the provider does not support it, fallback to local certs.
203 // return the X500Principal of the end-entity cert.
204 Certificate[] certs = getLocalCertificates();
205 if (certs != null) {
206 principal = (X500Principal) ((X509Certificate) certs[0])
207 .getSubjectX500Principal();
208 }
209 }
210 return principal;
211 }
212
213 /**
214 * Returns the socket which is the source of this event.
215 * (This is a convenience function, to let applications
216 * write code without type casts.)
217 *
218 * @return the socket on which the connection was made.
219 */
220 public SSLSocket getSocket() {
221 return (SSLSocket) getSource();
222 }
223 }
|