001    /* SSLSocket.java -- an SSL client socket.
002       Copyright (C) 2004 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.net.ssl;
040    
041    import java.io.IOException;
042    import java.net.InetAddress;
043    import java.net.Socket;
044    import java.net.UnknownHostException;
045    
046    /**
047     * A socket that communicates over the secure socket layer protocol.
048     */
049    public 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    }