javax.net.ssl.SSLServerSocket Maven / Gradle / Ivy

Neither this file nor any files generated from it describe a complete specification, and they may only be used as described below. For example, no permission is given for you to incorporate this file, in whole or in part, in an implementation of a Java specification.

Sun Microsystems Inc. owns the copyright in this file and it is provided to you for informative, as opposed to normative, use. The file and any files generated from it may be used to generate other informative documentation, such as a unified set of documents of API signatures for a platform that includes technologies expressed as Java APIs. The file may also be used to produce "compilation stubs," which allow applications to be compiled and validated for such platforms.

Any work generated from this file, such as unified javadocs or compiled stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of CDC Security (Java Secure Socket Extension - JSSE) Optional Package interfaces and modules. */ /* * @(#)SSLServerSocket.java 1.11 05/03/12 */ /* * NOTE: * Because of various external restrictions (i.e. US export * regulations, etc.), the actual source code can not be provided * at this time. This file represents the skeleton of the source * file, so that javadocs of the API can be created. */ package javax.net.ssl; import java.io.*; import java.net.*; /** * This class extends ServerSockets and * provides secure server sockets using protocols such as the Secure * Sockets Layer (SSL) or Transport Layer Security (TLS) protocols. *

* Instances of this class are generally created using a * SSLServerSocketFactory. The primary function * of SSLServerSockets * is to create SSLSockets by accepting * connections. *

* SSLServerSockets contain several pieces of state data * which are inherited by the SSLSocket at * socket creation. These include the enabled cipher * suites and protocols, whether client * authentication is necessary, and whether created sockets should * begin handshaking in client or server mode. The state * inherited by the created SSLSocket can be * overriden by calling the appropriate methods. * * @see java.net.ServerSocket * @see SSLSocket * * @since 1.4 * @version 1.22 * @author David Brownell */ public abstract class SSLServerSocket extends ServerSocket { /** * Used only by subclasses. * Create an unbound TCP server socket using the default authentication * context. * @throws IOException if an I/O error occurs when creating the socket */ protected SSLServerSocket() throws IOException { } /** * Used only by subclasses. * Create a TCP server socket on a port, using the default * authentication context. The connection backlog defaults to * fifty connections queued up before the system starts to * reject new connection requests. * * @param port the port on which to listen * @throws IOException if an I/O error occurs when creating the socket */ protected SSLServerSocket(int port) throws IOException { } /** * Used only by subclasses. * Create a TCP server socket on a port, using the default * authentication context and a specified backlog of connections. * * @param port the port on which to listen * @param backlog how many connections may be pending before * the system should start rejecting new requests * @throws IOException if an I/O error occurs when creating the socket */ protected SSLServerSocket(int port, int backlog) throws IOException { } /** * Used only by subclasses. * Create a TCP server socket on a port, using the default * authentication context and a specified backlog of connections * as well as a particular specified network interface. This * constructor is used on multihomed hosts, such as those used * for firewalls or as routers, to control through which interface * a network service is provided. * * @param port the port on which to listen * @param backlog how many connections may be pending before * the system should start rejecting new requests * @param address the address of the network interface through * which connections will be accepted * @throws IOException if an I/O error occurs when creating the socket */ protected SSLServerSocket(int port, int backlog, InetAddress address) throws IOException { } /** * Returns the list of cipher suites which are currently enabled * for use by newly accepted connections. If this has not been * explicitly modified, a system-provided default guarantees a * minimum quality of service in all enabled cipher suites. * *

There are several reasons why an enabled cipher suite might * not actually be used. For example: the server socket might * not have appropriate private keys available to it or the cipher * suite might be anonymous, precluding the use of client authentication, * while the server socket has been told to require that sort of * authentication. * * @return an array of cipher suites enabled * @see #getSupportedCipherSuites() * @see #setEnabledCipherSuites(String []) */ public abstract String[] getEnabledCipherSuites(); /** * Controls which particular SSL cipher suites are enabled for use * by accepted connections. The cipher suites must have been listed * by getSupportedCipherSuites() as being supported. Suites * which require authentication information which is not available * in this ServerSocket's authentication context will not be used * in any case, even if they are enabled. *

* SSLSockets returned from accept() * inherit this setting. * * @param suites Names of all the cipher suites to enable * @exception IllegalArgumentException when one or more of ciphers * named by the parameter is not supported, or when * the parameter is null. * @see #getSupportedCipherSuites() * @see #getEnabledCipherSuites() */ public abstract void setEnabledCipherSuites(String[] suites); /** * Returns the names of the cipher suites which could be enabled for use * on an SSL connection. Normally, only a subset of these will actually * be enabled by default, since this list may include cipher suites which * do not meet quality of service requirements for those defaults. Such * cipher suites are useful in specialized applications. * * @return an array of cipher suite names * @see #getEnabledCipherSuites() * @see #setEnabledCipherSuites(String []) */ public abstract String[] getSupportedCipherSuites(); /** * Returns the names of the protocols which could be enabled for use. * * @return an array of protocol names supported * @see #getEnabledProtocols() * @see #setEnabledProtocols(String []) */ public abstract String[] getSupportedProtocols(); /** * Returns the names of the protocols which are currently * enabled for use by the newly accepted connections. * * @return an array of protocol names * @see #getSupportedProtocols() * @see #setEnabledProtocols(String []) */ public abstract String[] getEnabledProtocols(); /** * Controls which particular protocols are enabled for use by * accepted connections. The protocols must have been listed by * getSupportedProtocols() as being supported. *

* SSLSockets returned from accept() * inherit this setting. * * @param protocols Names of all the protocols to enable. * @exception IllegalArgumentException when one or more of * the protocols named by the parameter is not supported or * when the protocols parameter is null. * @see #getEnabledProtocols() * @see #getSupportedProtocols() */ public abstract void setEnabledProtocols(String[] protocols); /** * Controls whether the connections which are accepted must include * successful client authentication. This option is only useful * for sockets in the server mode. *

* Unlike {@link #setWantClientAuth(boolean)}, * if the client chooses not to provide authentication information * about itself, the negotiations will stop and the connection * will be dropped. *

* SSLSockets returned from accept() * inherit this setting. * * @param flag true if the clients must authenticate themselves. * Setting this parameter to true overrides the current * setting of {@link #setWantClientAuth(boolean)}. * @see #getNeedClientAuth() * @see #setWantClientAuth(boolean) * @see #getWantClientAuth() * @see #setUseClientMode(boolean) */ public abstract void setNeedClientAuth(boolean flag); /** * Returns true if client authentication is required on newly accepted * connections. This option is only useful for sockets in the * server mode. * * @return true if the clients must authenticate themselves. * @see #setNeedClientAuth(boolean) * @see #setWantClientAuth(boolean) * @see #getWantClientAuth() * @see #setUseClientMode(boolean) */ public abstract boolean getNeedClientAuth(); /** * Controls whether the connections which are accepted should request * client authentication as part of the SSL negotiations. This * option is only useful for sockets in the server mode. *

* Unlike {@link #setNeedClientAuth(boolean)}, * if the client chooses not to provide * authentication information about itself, the negotiations will * continue. *

* SSLSockets returned from accept() * inherit this setting. * * @param flag true if the clients should try to authenticate themselves. * Setting this parameter to true overrides the current * setting of {@link #setNeedClientAuth(boolean)}. * @see #getWantClientAuth() * @see #setNeedClientAuth(boolean) * @see #getNeedClientAuth() * @see #setUseClientMode(boolean) */ public abstract void setWantClientAuth(boolean flag); /** * Returns true if client authentication is requested on newly accepted * connections. This option is only useful for sockets in the * server mode. * * @return true if the clients must authenticate themselves. * @see #setWantClientAuth(boolean) * @see #setNeedClientAuth(boolean) * @see #getNeedClientAuth() * @see #setUseClientMode(boolean) */ public abstract boolean getWantClientAuth(); /** * Controls whether accepted connections are in the (default) SSL * server mode, or the SSL client mode. Servers normally * authenticate themselves, and clients are not required to do so. *

* In rare cases, TCP servers * need to act in the SSL client mode on newly accepted * connections. For example, FTP clients acquire server sockets * and listen there for reverse connections from the server. An * FTP client would use an SSLServerSocket in "client" mode to * accept the reverse connection while the FTP server uses an * SSLSocket with "client" mode disabled to initiate the * connection. During the resulting handshake, existing SSL * sessions may be reused. *

* SSLSockets returned from accept() * inherit this setting. * * @param flag true if newly accepted connections should use SSL * client mode. * @see #getUseClientMode() */ public abstract void setUseClientMode(boolean flag); /** * Returns true if accepted connections will be in SSL client mode. * * @see #setUseClientMode(boolean) * @return true if the connection should use SSL client mode. */ public abstract boolean getUseClientMode(); /** * Controls whether new SSL sessions may be established by the * sockets which are created from this server socket. *