All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class sun.security.ssl.SSLSocket

java.lang.Object
   |
   +----java.net.Socket
           |
           +----sun.security.ssl.SSLSocket

public final class SSLSocket
extends Socket
SSLSocket acts like any other stream Socket, but it's got the Secure Sockets Layer (SSL) protocol underneath. SSL is a secure channel communications protocol. You may think of it as being like TCP, with these security features added:


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.

When SSL connections are first set up, no security is provided. However, security is always provided by the time that application data is sent on the connection. Before sending such data, application programs may then express preferences for what cipher suites may be used in communication. SSL code performs a negotiation as part of preparing to send data. Some session suite that is supported by both sides of the SSL connection will be used; if there is no such suite, application data will not flow across the connection.

By default, this interface will only enable use of SSL 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.

There are three groups of cipher suites which you will need to know about when managing cipher suites, in addition to the single "active" cipher suite used with a connection's session:


This API offers a non-traditional option for establishing SSL connections. You may first establish the connection directly, then pass that connection to the SSL socket constructor with a flag saying which role should be taken in the handshake protocol. (The two ends of the connection must not choose the same role!) This allows setup of SSL proxying or tunneling, and also allows the kind of "role reversal" that is required for most FTP data transfers.

SSL connections acting with a server side role have access to a session information, used to identify multiple connections associated with a single client.


Notes:

See Also:
SSLServerSocket

Constructor Index

 o SSLSocket(AuthContext, InetAddress, int)
Constructs an SSL connection to a server at a specified address.
 o SSLSocket(AuthContext, String, int)
Constructs an SSL connection to a named host at a specified port, using the authentication context provided.
 o SSLSocket(InetAddress, int)
Constructs an SSL connection to a server at a specified address and TCP port.
 o SSLSocket(Socket, AuthContext)
Layer SSL traffic over an existing connection, rather than creating a new connection.
 o SSLSocket(Socket, AuthContext, boolean)
Layer SSL traffic over an existing connection, rather than creating a new connection.
 o SSLSocket(String, int)
Constructs an SSL connection to a named host at a specified port.

Method Index

 o close()
Closes the SSL connection.
 o finalize()
Ensures that the SSL connection is closed down as cleanly as possible, in case the application forgets to do so.
 o getActiveCipherSuite()
Returns the name of the SSL cipher suite which is currently active on this connection.
 o getDefaultCipherSuites()
Returns the list of cipher suites which are enabled by default.
 o getEnabledCipherSuites()
Returns the names of the SSL cipher suites which are currently enabled for use on this connection.
 o getInetAddress()
Returns the address of the remote peer for this connection.
 o getInputStream()
Gets an input stream to read from the peer on the other side.
 o getLocalPort()
Returns the number of the local port that this connection uses.
 o getOutputStream()
Gets an output stream to write to the peer on the other side.
 o getPeerCertificateChain()
Returns a certificate chain from the peer to a root CA.
 o getPort()
Returns the number of the remote port that this connection uses.
 o getSession()
Valid only on the server side of an SSL connection, this returns the the SSL Session in use by this connection.
 o getSoLinger()
Returns the socket's linger timeout.
 o getSoTimeout()
Returns the socket timeout.
 o getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on an SSL connection.
 o getTcpNoDelay()
Returns true if the Nagle optimization is disabled.
 o setEnabledCipherSuites(String[])
Controls which particular cipher suites are enabled for use on this connection.
 o setSoLinger(boolean, int)
Assigns the socket's linger timeout.
 o setSoTimeout(int)
Assigns the socket timeout.
 o setTcpNoDelay(boolean)
Enables or disables the Nagle optimization.
 o toString()
Returns a printable representation of this end of the connection.

Constructors

 o SSLSocket
  public SSLSocket(String host,
                   int port) throws IOException, UnknownHostException
Constructs an SSL connection to a named host at a specified port. This acts as the SSL client, and may authenticate itself or rejoin existing SSL sessions allowed by the default authentication context.

Parameters:
host - name of the host with which to connect
port - number of the server's port
 o SSLSocket
  public SSLSocket(InetAddress host,
                   int port) throws IOException, UnknownHostException
Constructs an SSL connection to a server at a specified address and TCP port. This acts as the SSL client, and may authenticate itself or rejoin existing SSL sessions allowed by the default authentication context.

Parameters:
address - the server's host
port - its port
 o SSLSocket
  public SSLSocket(AuthContext context,
                   String host,
                   int port) throws IOException, UnknownHostException
Constructs an SSL connection to a named host at a specified port, using the authentication context provided. This endpoint acts as the client, and may rejoin an existing SSL session if appropriate.

Parameters:
context - authentication context to use
host - name of the host with which to connect
port - number of the server's port
 o SSLSocket
  public SSLSocket(AuthContext context,
                   InetAddress host,
                   int port) throws IOException, UnknownHostException
Constructs an SSL connection to a server at a specified address. and TCP port, using the authentication context provided. This endpoint acts as the client, and may rejoin an existing SSL session if appropriate.

Parameters:
context - authentication context to use
address - the server's host
port - its port
 o SSLSocket
  public SSLSocket(Socket sock,
                   AuthContext context) throws IOException
Layer SSL traffic over an existing connection, rather than creating a new connection. The existing connection may be used only for SSL traffic (using this SSLSocket) until the SSLSocket.close() call returns. However, if a protocol error is detected, that existing connection is automatically closed.

This particular constructor always uses the socket in the role of an SSL client. It may be useful in cases which start using SSL after some initial data transfers, for example in some SSL tunneling applications or as part of some kinds of application protocols which negotiate use of a SSL based security.

Parameters:
sock - the existing connection
context - the authentication context to use
 o SSLSocket
  public SSLSocket(Socket sock,
                   AuthContext context,
                   boolean needClientAuth) throws IOException
Layer SSL traffic over an existing connection, rather than creating a new connection. The existing connection may be used only for SSL traffic (using this SSLSocket) until the SSLSocket.close() call returns. However, if a protocol error is detected, that existing connection is automatically closed.

This particular constructor always uses the socket in the role of an SSL server.

Parameters:
sock - the existing connection
context - the authentication context to use
needClientAuth - true iff the client must authenticate itself

Methods

 o close
  public synchronized void close() throws IOException
Closes the SSL connection. SSL includes an application level shutdown handshake; you should close SSL sockets explicitly rather than leaving it for finalization, so that your remote peer does not experience a protcool error.

If the SSL connection was established using an existing Socket, that socket needs to be closed separately.

Overrides:
close in class Socket
 o finalize
  protected void finalize()
Ensures that the SSL connection is closed down as cleanly as possible, in case the application forgets to do so. This allows SSL connections to be implicitly reclaimed, rather than forcing them to be explicitly reclaimed at the penalty of prematurly killing SSL sessions.

Overrides:
finalize in class Object
 o getActiveCipherSuite
  public String getActiveCipherSuite()
Returns the name of the SSL cipher suite which is currently active on this connection. This defines the level of protection which is provided to the data sent on the connection, including the kind of encryption used and most aspects of how authentication is performed.

The cipher suite names are as defined in the SSL protocol definition, and include:

Returns:
the name of the currently active cipher suite
See Also:
getEnabledCipherSuites, getSupportedCipherSuites, setEnabledCipherSuites
 o getDefaultCipherSuites
  public static String[] getDefaultCipherSuites()
Returns the list of cipher suites which are enabled by default.

Returns:
array of the cipher suites enabled by default
See Also:
getActiveCipherSuite, getEnabledCipherSuites, setEnabledCipherSuites, getSupportedCipherSuites
 o getEnabledCipherSuites
  public 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 (a) protect data confidentiality, by traffic encryption, and (b) can mutually authenticate both clients and servers. Thus, in some environments, this value might be empty.

Returns:
an array of cipher suite names
See Also:
getActiveCipherSuite, getDefaultCipherSuites, getSupportedCipherSuites, setEnabledCipherSuites
 o getInetAddress
  public InetAddress getInetAddress()
Returns the address of the remote peer for this connection.

Overrides:
getInetAddress in class Socket
 o getInputStream
  public InputStream getInputStream()
Gets an input stream to read from the peer on the other side. Data read from this stream was always integrity protected in transit, and will usually have been confidentiality protected.

Overrides:
getInputStream in class Socket
 o getLocalPort
  public int getLocalPort()
Returns the number of the local port that this connection uses.

Overrides:
getLocalPort in class Socket
 o getOutputStream
  public OutputStream getOutputStream()
Gets an output stream to write to the peer on the other side. Data written on this stream is always integrity protected, and will usually be confidentiality protected.

Overrides:
getOutputStream in class Socket
 o getPeerCertificateChain
  public X509Cert[] getPeerCertificateChain() throws SSLPeerUnverified
Returns a certificate chain from the peer to a root CA.

Returns:
the chain of certificates
Throws: SSLPeerUnverified
the identity of the peer is not known.
 o getPort
  public int getPort()
Returns the number of the remote port that this connection uses.

Overrides:
getPort in class Socket
 o getSession
  public Session getSession()
Valid only on the server side of an SSL connection, this 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.

 o getSupportedCipherSuites
  public static 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 support the mutual authentication of servers and clients, or which do not protect data confidentiality. Servers may also need certain kinds of certificates to use certain cipher suites.

Returns:
an array of cipher suite names
See Also:
getActiveCipherSuite, getDefaultCipherSuites, getEnabledCipherSuites, setEnabledCipherSuites
 o getSoLinger
  public int getSoLinger() throws SocketException
Returns the socket's linger timeout.

Overrides:
getSoLinger in class Socket
See Also:
getSoLinger
 o getSoTimeout
  public synchronized int getSoTimeout() throws SocketException
Returns the socket timeout.

Overrides:
getSoTimeout in class Socket
See Also:
getSoTimeout
 o getTcpNoDelay
  public boolean getTcpNoDelay() throws SocketException
Returns true if the Nagle optimization is disabled. This relates to low-level buffering of TCP traffic, delaying the traffic to promote better throughput.

Overrides:
getTcpNoDelay in class Socket
See Also:
getTcpNoDelay
 o setEnabledCipherSuites
  public void setEnabledCipherSuites(String suites[]) throws IllegalArgumentException
Controls which particular cipher suites are enabled for use on this connection. The cipher suites must have been listed by getCipherSuites() 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:
getActiveCipherSuite, getDefaultCipherSuites, getEnabledCipherSuites, getSupportedCipherSuites
 o setSoLinger
  public void setSoLinger(boolean flag,
                          int linger) throws SocketException
Assigns the socket's linger timeout.

Overrides:
setSoLinger in class Socket
See Also:
setSoLinger
 o setSoTimeout
  public synchronized void setSoTimeout(int timeout) throws SocketException
Assigns the socket timeout.

Overrides:
setSoTimeout in class Socket
See Also:
setSoTimeout
 o setTcpNoDelay
  public void setTcpNoDelay(boolean value) throws SocketException
Enables or disables the Nagle optimization.

Overrides:
setTcpNoDelay in class Socket
See Also:
setTcpNoDelay
 o toString
  public String toString()
Returns a printable representation of this end of the connection.

Overrides:
toString in class Socket

All Packages  Class Hierarchy  This Package  Previous  Next  Index