javax.net.ssl

Class SSLSocket

java.lang.Object

java.net.Socket

javax.net.ssl.SSLSocket

All Implemented Interfaces:

Closeable, AutoCloseable

public abstract class SSLSocket
extends Socket

This class extends Sockets and provides secure socket using protocols such as the "Secure Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.

Such sockets are normal stream sockets, but they add a layer of security protections over the underlying network transport protocol, such as TCP. Those protections include:

• Integrity Protection. SSL protects against modification of messages by an active wiretapper.
• Authentication. In most modes, SSL provides peer authentication. Servers are usually authenticated, and clients may be authenticated as requested by servers.
• Confidentiality (Privacy Protection). In most modes, SSL encrypts data being sent between client and server. This protects the confidentiality of data, so that passive wiretappers won't see sensitive data such as financial information or personal information of many kinds.

These kinds of protection are specified by a "cipher suite", which is a combination of cryptographic algorithms used by a given SSL connection. During the negotiation process, the two endpoints must agree on a ciphersuite that is available in both environments. If there is no such suite in common, no SSL connection can be established, and no data can be exchanged.

The cipher suite used is established by a negotiation process called "handshaking". The goal of this process is to create or rejoin a "session", which may protect many connections over time. After handshaking has completed, you can access session attributes by using the getSession method. The initial handshake on this connection can be initiated in one of three ways:

• calling startHandshake which explicitly begins handshakes, or
• any attempt to read or write application data on this socket causes an implicit handshake, or
• a call to getSession tries to set up a session if there is no currently valid session, and an implicit handshake is done.

If handshaking fails for any reason, the SSLSocket is closed, and no further communications can be done.

There are two groups of cipher suites which you will need to know about when managing cipher suites:

• Supported cipher suites: all the suites which are supported by the SSL implementation. This list is reported using getSupportedCipherSuites.
• Enabled cipher suites, which may be fewer than the full set of supported suites. This group is set using the setEnabledCipherSuites method, and queried using the getEnabledCipherSuites method. Initially, a default set of cipher suites will be enabled on a new socket that represents the minimum suggested configuration.

Implementation defaults require that only cipher suites which authenticate servers and provide confidentiality be enabled by default. Only if both sides explicitly agree to unauthenticated and/or non-private (unencrypted) communications will such a ciphersuite be selected.

When SSLSockets are first created, no handshaking is done so that applications may first set their communication preferences: what cipher suites to use, whether the socket should be in client or server mode, etc. However, security is always provided by the time that application data is sent over the connection.

You may register to receive event notification of handshake completion. This involves the use of two additional classes. HandshakeCompletedEvent objects are passed to HandshakeCompletedListener instances, which are registered by users of this API. SSLSockets are created by SSLSocketFactorys, or by accepting a connection from a SSLServerSocket.

A SSL socket must choose to operate in the client or server mode. This will determine who begins the handshaking process, as well as which messages should be sent by each party. Each connection must have one client and one server, or handshaking will not progress properly. Once the initial handshaking has started, a socket can not switch between client and server modes, even when performing renegotiations.

Since:

1.4

Author:

David Brownell

See Also:

Socket, SSLSocketFactory

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SSLSocket() Used only by subclasses.
protected	SSLSocket(InetAddress address, int port) Used only by subclasses.
protected	SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) Used only by subclasses.
protected	SSLSocket(String host, int port) Used only by subclasses.
protected	SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) Used only by subclasses.

Method Summary

Modifier and Type	Method and Description
abstract boolean	getNeedClientAuth() Returns true if the socket will require client authentication.
abstract boolean	getUseClientMode() Returns true if the socket is set to use client mode when handshaking.
abstract void	setNeedClientAuth(boolean need) Configures the socket to require client authentication.
abstract void	setUseClientMode(boolean mode) Configures the socket to use client (or server) mode when handshaking.
abstract void	startHandshake() Starts an SSL handshake on this connection.

Methods inherited from class java.net.Socket

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

Methods inherited from class java.lang.Object

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

Constructor Detail

SSLSocket

protected SSLSocket()

Used only by subclasses. Constructs an uninitialized, unconnected TCP socket.

SSLSocket

protected SSLSocket(InetAddress address,
                    int port)
             throws IOException

Used only by subclasses. Constructs a TCP connection to a server at a specified address and port. This acts as the SSL client.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

Parameters:

address - the server's host

port - its port

Throws:

IOException - if an I/O error occurs when creating the socket

SecurityException - if a security manager exists and its checkConnect method doesn't allow the operation.

IllegalArgumentException - if the port parameter is outside the specified range of valid port values, which is between 0 and 65535, inclusive.

NullPointerException - if address is null.

SSLSocket

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

Used only by subclasses. Constructs an SSL connection to a server at a specified address and TCP port, binding the client side of the connection a given address and port. This acts as the SSL client.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

Parameters:

address - the server's host

port - its port

clientAddress - the client's address the socket is bound to, or null for the anyLocal address.

clientPort - the client's port the socket is bound to, or zero for a system selected free port.

Throws:

IOException - if an I/O error occurs when creating the socket

SecurityException - if a security manager exists and its checkConnect method doesn't allow the operation.

IllegalArgumentException - if the port parameter or clientPort parameter is outside the specified range of valid port values, which is between 0 and 65535, inclusive.

NullPointerException - if address is null.

SSLSocket

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

Used only by subclasses. Constructs a TCP connection to a named host at a specified port. This acts as the SSL client.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

Parameters:

host - name of the host with which to connect, or null for the loopback address.

port - number of the server's port

Throws:

IOException - if an I/O error occurs when creating the socket

SecurityException - if a security manager exists and its checkConnect method doesn't allow the operation.

UnknownHostException - if the host is not known

IllegalArgumentException - if the port parameter is outside the specified range of valid port values, which is between 0 and 65535, inclusive.

SSLSocket

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

Used only by subclasses. Constructs an SSL connection to a named host at a specified port, binding the client side of the connection a given address and port. This acts as the SSL client.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

Parameters:

host - name of the host with which to connect, or null for the loopback address.

port - number of the server's port

clientAddress - the client's address the socket is bound to, or null for the anyLocal address.

clientPort - the client's port the socket is bound to, or zero for a system selected free port.

Throws:

IOException - if an I/O error occurs when creating the socket

SecurityException - if a security manager exists and its checkConnect method doesn't allow the operation.

UnknownHostException - if the host is not known

IllegalArgumentException - if the port parameter or clientPort parameter is outside the specified range of valid port values, which is between 0 and 65535, inclusive.

Method Detail

getNeedClientAuth

public abstract boolean getNeedClientAuth()

Returns true if the socket will require client authentication. This option is only useful to sockets in the server mode.

Returns:

true if client authentication is required, or false if no client authentication is desired.

See Also:

setNeedClientAuth(boolean), setUseClientMode(boolean)

getUseClientMode

public abstract boolean getUseClientMode()

Returns true if the socket is set to use client mode when handshaking.

Returns:

true if the socket should do handshaking in "client" mode

See Also:

setUseClientMode(boolean)

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)

Configures the socket to require client authentication. This option is only useful for sockets in the server mode.

A socket's client authentication setting is one of the following:

• client authentication required
• client authentication requested
• no client authentication desired

If this option is set and the client chooses not to provide authentication information about itself, the negotiations will stop and the connection will be dropped.

Parameters:

need - set to true if client authentication is required, or false if no client authentication is desired.

See Also:

getNeedClientAuth(), setUseClientMode(boolean)

setUseClientMode

public abstract void setUseClientMode(boolean mode)

Configures the socket to use client (or server) mode when handshaking.

This method must be called before any handshaking occurs. Once handshaking has begun, the mode can not be reset for the life of this socket.

Servers normally authenticate themselves, and clients are not required to do so.

Parameters:

mode - true if the socket should start its handshaking in "client" mode

Throws:

IllegalArgumentException - if a mode change is attempted after the initial handshake has begun.

See Also:

getUseClientMode()

startHandshake

public abstract void startHandshake()
                             throws IOException

Starts an SSL handshake on this connection. Common reasons include a need to use new encryption keys, to change cipher suites, or to initiate a new session. To force complete reauthentication, the current session could be invalidated before starting this handshake.

If data has already been sent on the connection, it continues to flow during this handshake. When the handshake completes, this will be signaled with an event. This method is synchronous for the initial handshake on a connection and returns when the negotiated handshake is complete. Some protocols may not support multiple handshakes on an existing socket and may throw an IOException.

Throws:

IOException - on a network level error