Package javax.net.ssl

Class SSLSocket

java.lang.Object

java.net.Socket

javax.net.ssl.SSLSocket

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

OpenSSLSocketImpl, SSLSocketImpl

public abstract class SSLSocket
extends Socket

The extension of Socket providing secure protocols like SSL (Secure Sockets Layer) or TLS (Transport Layer Security).

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	SSLSocket()	Only to be used by subclasses.
protected	SSLSocket(String host, int port)	Only to be used by subclasses.
protected	SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)	Only to be used by subclasses.
protected	SSLSocket(InetAddress address, int port)	Only to be used by subclasses.
protected	SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)	Only to be used by subclasses.

Method Summary

Modifier and Type	Method	Description
abstract void	addHandshakeCompletedListener(HandshakeCompletedListener listener)	Registers the specified listener to receive notification on completion of a handshake on this connection.
abstract String[]	getEnabledCipherSuites()	Returns the names of the enabled cipher suites.
abstract String[]	getEnabledProtocols()	Returns the names of the enabled protocols.
abstract boolean	getEnableSessionCreation()	Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract boolean	getNeedClientAuth()	Returns true if the server socket should require client authentication.
abstract SSLSession	getSession()	Returns the SSLSession for this connection.
SSLParameters	getSSLParameters()	Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.
abstract String[]	getSupportedCipherSuites()	Returns the names of the supported cipher suites.
abstract String[]	getSupportedProtocols()	Returns the names of the supported protocols.
abstract boolean	getUseClientMode()	Returns true if this connection will act in client mode when handshaking.
abstract boolean	getWantClientAuth()	Returns true if the server should request client authentication.
abstract void	removeHandshakeCompletedListener(HandshakeCompletedListener listener)	Removes the specified handshake completion listener.
abstract void	setEnabledCipherSuites(String[] suites)	Sets the names of the cipher suites to be enabled.
abstract void	setEnabledProtocols(String[] protocols)	Sets the names of the protocols to be enabled.
abstract void	setEnableSessionCreation(boolean flag)	Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract void	setNeedClientAuth(boolean need)	Sets whether the server should require client authentication.
void	setSSLParameters(SSLParameters p)	Sets various SSL handshake parameters based on the SSLParameter argument.
abstract void	setUseClientMode(boolean mode)	Sets whether this connection should act in client mode when handshaking.
abstract void	setWantClientAuth(boolean want)	Sets whether the server should request client authentication.
void	shutdownInput()	Unsupported for SSL because reading from an SSL socket may require writing to the network.
void	shutdownOutput()	Unsupported for SSL because writing to an SSL socket may require reading from the network.
abstract void	startHandshake()	Starts a new SSL handshake on this connection.

Methods inherited from class java.net.Socket

bind, close, connect, connect, getChannel, getFileDescriptor$, getInetAddress, getInputStream, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getOutputStream, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

SSLSocket

protected SSLSocket()

Only to be used by subclasses.

Creates a TCP socket.

SSLSocket

protected SSLSocket(String host,
int port)
             throws IOException,
UnknownHostException

Only to be used by subclasses.

Creates a TCP socket connection to the specified host at the specified port.

Parameters:

host - the host name to connect to.

port - the port number to connect to.

Throws:

IOException - if creating the socket fails.

UnknownHostException - if the specified host is not known.

SSLSocket

protected SSLSocket(InetAddress address,
int port)
             throws IOException

Only to be used by subclasses.

Creates a TCP socket connection to the specified address at the specified port.

Parameters:

address - the address to connect to.

port - the port number to connect to.

Throws:

IOException - if creating the socket fails.

SSLSocket

protected SSLSocket(String host,
int port,
InetAddress clientAddress,
int clientPort)
             throws IOException,
UnknownHostException

Only to be used by subclasses.

Creates a TCP socket connection to the specified host at the specified port with the client side bound to the specified address and port.

Parameters:

host - the host name to connect to.

port - the port number to connect to.

clientAddress - the client address to bind to

clientPort - the client port number to bind to.

Throws:

IOException - if creating the socket fails.

UnknownHostException - if the specified host is not known.

SSLSocket

protected SSLSocket(InetAddress address,
int port,
InetAddress clientAddress,
int clientPort)
             throws IOException

Only to be used by subclasses.

Creates a TCP socket connection to the specified address at the specified port with the client side bound to the specified address and port.

Parameters:

address - the address to connect to.

port - the port number to connect to.

clientAddress - the client address to bind to.

clientPort - the client port number to bind to.

Throws:

IOException - if creating the socket fails.

Method Details

shutdownInput

public void shutdownInput()
                   throws IOException

Unsupported for SSL because reading from an SSL socket may require writing to the network.

Overrides:

shutdownInput in class Socket

Throws:

IOException - if an error occurs while closing the socket input stream.

SocketException - if the input stream is already closed.

shutdownOutput

public void shutdownOutput()
                    throws IOException

Unsupported for SSL because writing to an SSL socket may require reading from the network.

Overrides:

shutdownOutput in class Socket

Throws:

IOException - if an error occurs while closing the socket output stream.

SocketException - if the output stream is already closed.

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()

Returns the names of the supported cipher suites.

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()

Returns the names of the enabled cipher suites.

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)

Sets the names of the cipher suites to be enabled. Only cipher suites returned by getSupportedCipherSuites() are allowed.

Parameters:

suites - the names of the to be enabled cipher suites.

Throws:

IllegalArgumentException - if one of the cipher suite names is not supported.

getSupportedProtocols

public abstract String[] getSupportedProtocols()

Returns the names of the supported protocols.

getEnabledProtocols

public abstract String[] getEnabledProtocols()

Returns the names of the enabled protocols.

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)

Sets the names of the protocols to be enabled. Only protocols returned by getSupportedProtocols() are allowed.

Parameters:

protocols - the names of the to be enabled protocols.

Throws:

IllegalArgumentException - if one of the protocols is not supported.

getSession

public abstract SSLSession getSession()

Returns the SSLSession for this connection. If necessary, a handshake will be initiated, in which case this method will block until the handshake has been established. If the handshake fails, an invalid session object will be returned.

Returns:

the session object.

addHandshakeCompletedListener

public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)

Registers the specified listener to receive notification on completion of a handshake on this connection.

Parameters:

listener - the listener to register.

Throws:

IllegalArgumentException - if listener is null.

removeHandshakeCompletedListener

public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)

Removes the specified handshake completion listener.

Parameters:

listener - the listener to remove.

Throws:

IllegalArgumentException - if the specified listener is not registered or null.

startHandshake

public abstract void startHandshake()
                             throws IOException

Starts a new SSL handshake on this connection.

Throws:

IOException - if an error occurs.

setUseClientMode

public abstract void setUseClientMode(boolean mode)

Sets whether this connection should act in client mode when handshaking.

Parameters:

mode - true if this connection should act in client mode, false if not.

getUseClientMode

public abstract boolean getUseClientMode()

Returns true if this connection will act in client mode when handshaking.

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)

Sets whether the server should require client authentication. This does not apply to sockets in client mode. Client authentication is one of the following:

• authentication required
• authentication requested
• no authentication needed

This method overrides the setting of setWantClientAuth(boolean).

setWantClientAuth

public abstract void setWantClientAuth(boolean want)

Sets whether the server should request client authentication. Unlike setNeedClientAuth(boolean) this won't stop the negotiation if the client doesn't authenticate. This does not apply to sockets in client mode.The client authentication is one of:

• authentication required
• authentication requested
• no authentication needed

This method overrides the setting of setNeedClientAuth(boolean).

getNeedClientAuth

public abstract boolean getNeedClientAuth()

Returns true if the server socket should require client authentication. This does not apply to sockets in client mode.

getWantClientAuth

public abstract boolean getWantClientAuth()

Returns true if the server should request client authentication. This does not apply to sockets in client mode.

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)

Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused. If flag is false and there are no sessions to resume, handshaking will fail.

Parameters:

flag - true if new sessions may be created.

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()

Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.

Returns:

true if new sessions may be created, otherwise false.

getSSLParameters

public SSLParameters getSSLParameters()

Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.

Since:

1.6

setSSLParameters

public void setSSLParameters(SSLParameters p)

Sets various SSL handshake parameters based on the SSLParameter argument. Specifically, sets the SSLSocket's enabled cipher suites if the parameter's cipher suites are non-null. Similarly sets the enabled protocols. If the parameters specify the want or need for client authentication, those requirements are set on the SSLSocket, otherwise both are set to false.

Since:

1.6