001/* SSLSocket.java -- an SSL client socket. 002 Copyright (C) 2004 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package javax.net.ssl; 040 041import java.io.IOException; 042import java.net.InetAddress; 043import java.net.Socket; 044import java.net.UnknownHostException; 045 046/** 047 * A socket that communicates over the secure socket layer protocol. 048 */ 049public abstract class SSLSocket extends Socket 050{ 051 052 // Constructors. 053 // ------------------------------------------------------------------------- 054 055 protected SSLSocket() 056 { 057 super(); 058 } 059 060 protected SSLSocket(String host, int port) 061 throws IOException, UnknownHostException 062 { 063 super(host, port); 064 } 065 066 protected SSLSocket(InetAddress address, int port) throws IOException 067 { 068 super(address, port); 069 } 070 071 protected SSLSocket(String host, int port, 072 InetAddress localAddr, int localPort) 073 throws IOException, UnknownHostException 074 { 075 super(host, port, localAddr, localPort); 076 } 077 078 protected SSLSocket(InetAddress address, int port, 079 InetAddress localAddr, int localPort) 080 throws IOException 081 { 082 super(address, port, localAddr, localPort); 083 } 084 085 // Abstract methods. 086 // ------------------------------------------------------------------------- 087 088 /** 089 * Adds a handshake completed listener that wants to be notified when the 090 * SSL handshake completes. 091 * 092 * @param listener The listener to add. 093 */ 094 public abstract void 095 addHandshakeCompletedListener(HandshakeCompletedListener listener); 096 097 /** 098 * Removes a handshake listener from this socket. 099 * 100 * @param listener The listener to remove. 101 */ 102 public abstract void 103 removeHandshakeCompletedListener(HandshakeCompletedListener listener); 104 105 /** 106 * Returns the list of currently enabled cipher suites. 107 * 108 * @return The list of enabled cipher suites. 109 */ 110 public abstract String[] getEnabledCipherSuites(); 111 112 /** 113 * Sets the list of enabled cipher suites. 114 * 115 * @param suites The list of suites to enable. 116 */ 117 public abstract void setEnabledCipherSuites(String[] suites); 118 119 /** 120 * Returns the list of enabled SSL protocols. 121 * 122 * @return The list of enabled protocols. 123 */ 124 public abstract String[] getEnabledProtocols(); 125 126 /** 127 * Sets the list of enabled SSL protocols. 128 * 129 * @param protocols The list of protocols to enable. 130 */ 131 public abstract void setEnabledProtocols(String[] protocols); 132 133 /** 134 * Returns whether or not sessions will be created by this socket, and thus 135 * allow sessions to be continued later. 136 * 137 * @return Whether or not sessions will be created. 138 */ 139 public abstract boolean getEnableSessionCreation(); 140 141 /** 142 * Sets whether or not sessions will be created by this socket. 143 * 144 * @param enable The new value. 145 */ 146 public abstract void setEnableSessionCreation(boolean enable); 147 148 /** 149 * Returns whether or not this socket will require connecting clients to 150 * authenticate themselves. This value only applies to sockets in server 151 * mode. 152 * 153 * @return Whether or not this socket requires client authentication. 154 */ 155 public abstract boolean getNeedClientAuth(); 156 157 /** 158 * Sets whether or not this socket will require connecting clients to 159 * authenticate themselves. This value only applies to sockets in server 160 * mode. 161 * 162 * @param needAuth The new need auth value. 163 */ 164 public abstract void setNeedClientAuth(boolean needAuth); 165 166 /** 167 * Returns this socket's session object. 168 * 169 * @return The session. 170 */ 171 public abstract SSLSession getSession(); 172 173 /** 174 * Returns the list of cipher suites supported by this socket. 175 * 176 * @return The list of supported cipher suites. 177 */ 178 public abstract String[] getSupportedCipherSuites(); 179 180 /** 181 * Returns the list of protocols supported by this socket. 182 * 183 * @return The list of supported protocols. 184 */ 185 public abstract String[] getSupportedProtocols(); 186 187 /** 188 * Returns whether or not this socket will connect in client mode. 189 * 190 * @return True if this is a client socket. 191 */ 192 public abstract boolean getUseClientMode(); 193 194 /** 195 * Sets whether or not this socket will connect in client mode. 196 * 197 * @param clientMode The new value. 198 */ 199 public abstract void setUseClientMode(boolean clientMode); 200 201 /** 202 * Returns whether or not this socket will request that connecting clients 203 * authenticate themselves. This value only applies to sockets in server 204 * mode. 205 * 206 * @return The want client auth value. 207 */ 208 public abstract boolean getWantClientAuth(); 209 210 /** 211 * Sets whether or not this socket will request that connecting clients 212 * authenticate themselves. This value only applies to sockets in server 213 * mode. 214 * 215 * @param wantAuth The new want auth value. 216 */ 217 public abstract void setWantClientAuth(boolean wantAuth); 218 219 /** 220 * Explicitly begins the handshake, or, if the handshake has already 221 * completed, requests that the handshake be repeated. 222 * 223 * <p>The handshake will begin implicitly when any attempt to read or 224 * write to the socket is made.</p> 225 * 226 * @throws IOException If an I/O or SSL error occurs. 227 */ 228 public abstract void startHandshake() throws IOException; 229}