All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class javax.net.ssl.SSLSocket

java.lang.Object
   |
   +----java.net.Socket
           |
           +----javax.net.ssl.SSLSocket

public abstract class SSLSocket

extends Socket

• 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. For example, how is integrity protection provided (what kind of message digest is used), how and whether the traffic is privacy-protected, and how authentication keys are exchanged.

The cipher suite used is established by a negotiation process, between SSL clients and servers, which is 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 get access to session attributes using the getSession method. Handshaking is fully transparent in most cases, but may be explicitly initiated.

You may register to receive event notification of handshake completion, using the standard Java Beans event model. This involves the use of two additional classes. HandshakeCompletedEvent objects are passed to HandshakeCompletedListener instances, which are implemented by users of this API.

Implementation defaults are required to enable use only of cipher suites which authenticate servers, and which provide confidentiality. The client and server must both agree on a common cipher suite in order to communicate. Only if both explicitly agree to unauthenticated or nonprivate communications will those security protections not exist.

There are two groups of cipher suites which you will need to know about when managing cipher suites, in addition to the default list and the active suite associated with the connection's session:

• 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. This will normally ensure confidentiality and integrity of your data.

See Also:

Socket, SSLServerSocket, SSLSocketFactory

SSLSocket()

Used only by subclasses.

SSLSocket(InetAddress, int)

Used only by subclasses.

SSLSocket(InetAddress, int, InetAddress, int)

Used only by subclasses.

SSLSocket(String, int)

Used only by subclasses.

SSLSocket(String, int, InetAddress, int)

Used only by subclasses.

addHandshakeCompletedListener(HandshakeCompletedListener)

Registers an event listener to receive notifications that an SSL handshake has completed on this connection.

getEnabledCipherSuites()

Returns the names of the SSL cipher suites which are currently enabled for use on this connection.

getEnableSessionCreation()

Returns true if new SSL sessions may be established by this socket.

getNeedClientAuth()

Returns true if the socket will require client authentication.

getSession()

Returns the the SSL Session in use by this connection.

getSupportedCipherSuites()

Returns the names of the cipher suites which could be enabled for use on an SSL connection.

getUseClientMode()

Returns true if the socket is set to use client mode in its first handshake.

removeHandshakeCompletedListener(HandshakeCompletedListener)

Removes a previously registered handshake completion listener.

setEnabledCipherSuites(String[])

Controls which particular cipher suites are enabled for use on this connection.

setEnableSessionCreation(boolean)

Controls whether new SSL sessions may be established by this socket.

setNeedClientAuth(boolean)

Configures the socket to require client authentication.

setUseClientMode(boolean)

Configures the socket to use client (or server) mode in its first handshake.

startHandshake()

Starts an SSL handshake on this connection.

 protected SSLSocket()

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

 protected SSLSocket(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.

Parameters:

host - name of the host with which to connect

port - number of the server's port

 protected SSLSocket(InetAddress address,
                     int port) throws IOException, UnknownHostException

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

Parameters:

address - the server's host

port - its port

 protected SSLSocket(String host,
                     int port,
                     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.

Parameters:

host - name of the host with which to connect

port - number of the server's port

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

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.

Parameters:

address - the server's host

port - its port

 public abstract String[] getSupportedCipherSuites()

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.

Returns:

an array of cipher suite names

 public abstract String[] getEnabledCipherSuites()

Returns the names of the SSL cipher suites which are currently enabled for use on this connection. When an SSL socket is first created, all enabled cipher suites support a minium quality of service. Thus, in some environments this value might be empty.

Returns:

an array of cipher suite names

See Also:

setEnabledCipherSuites

 public abstract void setEnabledCipherSuites(String suites[])

Controls which particular cipher suites are enabled for use on this connection. The cipher suites must have been listed by getSupportedCipherSuites() as being supported. Even if a suite has been enabled, it might never be used if no peer supports it, or the requisite certificates (and private keys) are not available.

Parameters:

suites - Names of all the cipher suites to enable.

Throws: IllegalArgumentException

when one of the ciphers named by the parameter is not supported.

See Also:

getEnabledCipherSuites

 public abstract SSLSession getSession()

Returns the the SSL Session in use by this connection. These can be long lived, and frequently correspond to an entire login session for some user. The session specifies a particular cipher suite which is being actively used by all connections in that session, as well as the identities of the session's client and server.

 public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)

Registers an event listener to receive notifications that an SSL handshake has completed on this connection.

See Also:

startHandshake, removeHandshakeCompletedListener

 public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)

Removes a previously registered handshake completion listener.

See Also:

addHandshakeCompletedListener

 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.

See Also:

addHandshakeCompletedListener

 public abstract void setUseClientMode(boolean mode)

Configures the socket to use client (or server) mode in its first handshake. Servers normally authenticate themselves, and clients are not required to do so.

Parameters:

mode - true iff the socket should start its first handshake in "client" mode

 public abstract boolean getUseClientMode()

Returns true if the socket is set to use client mode in its first handshake.

Returns:

true iff the socket should start its first handshake in "client" mode

See Also:

setUseClientMode

 public abstract void setNeedClientAuth(boolean need)

Configures the socket to require client authentication. The socket must be a server mode socket.

Parameters:

need - true iff the server mode socket should request that the client authenticate itself.

 public abstract boolean getNeedClientAuth()

Returns true if the socket will require client authentication. The socket must be a server mode socket.

Returns:

true iff the server mode socket should request that the client authenticate itself.

See Also:

setNeedClientAuth

 public abstract void setEnableSessionCreation(boolean flag)

Controls whether new SSL sessions may be established by this socket.

Parameters:

flag - true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed.

 public abstract boolean getEnableSessionCreation()

Returns true if new SSL sessions may be established by this socket.

Returns:

true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed.

All Packages  Class Hierarchy  This Package  Previous  Next  Index