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}