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

implements SSLOptions

See the SSLOptions class for more information about the features supported by all SSL sockets. Apart from the construction facilities (summarized below), this class only implements the features described in that interface, and basi csocket features.

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.

An SSLSocket is used exactly like a regular socket, but it offers additional functions by implementing SSLOptions. The basic constructors are like those on normal client stream sockets, taking a host identifier (hostname or IP address) and a port. These will esteablish a connection to that host and port, and negotiate the client side of an SSL connection.

SSL offers one non-traditional option for establishing an SSL connection. 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" required for most FTP data transfers.

See Also:

SSLOptions, SSLServerSocket

SSLSocket(InetAddress, int)

Constructs an SSL connection to a server at a specified address.

SSLSocket(Socket, boolean)

Layer SSL traffic over an existing connection, rather than creating a new connection.

SSLSocket(String, int)

Constructs an SSL connection to a named host at a specified port.

close()

Closes the SSL connection.

finalize()

Ensures that the SSL connection is closed down as cleanly as possible, in case the application forgets to do so.

getActiveCipherSuite()

Returns the name of the cipher suite which is currently active on this connection.

getEnabledCipherSuites()

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

getInetAddress()

Returns the address of the remote peer for this connection.

getInputStream()

Gets an input stream to read from the peer on the other side.

getLocalPort()

Returns the number of the local port that this connection uses.

getOutputStream()

Gets an output stream to write to the peer on the other side.

getPeerCertificateChain()

Returns a certificate chain from the peer to a root CA.

getPort()

Returns the number of the remote port that this connection uses.

getSupportedCipherSuites()

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

setEnabledCipherSuites(String[])

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

toString()

Returns a printable representation of this end of the connection.

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

Constructs an SSL connection to a named host at a specified port. This endpoint acts as the client, and may rejoin an existing SSL session if appropriate.

Parameters:

host - name of the host with which to connect

port - number of the server's port

  public SSLSocket(InetAddress host,
                   int port) throws IOException, UnknownHostException

Constructs an SSL connection to a server at a specified address. and TCP port. This endpoint acts as the client, and may rejoin an existing SSL session if appropriate.

Parameters:

address - the server's host

port - its port

  public SSLSocket(Socket sock,
                   boolean isServer) 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 style of API may be useful in situations where the normal client and server roles are not followed, such as during most kinds of FTP data exchange. It may also 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.

NOTE: Since no security context is passed in to this constructor, no mechanism is available for this endpoint of the connection to authenticate itself, or to reuse any SSL session state which has already been established.

Parameters:

sock - the existing connection

isServer - true iff this endpoint should assume the "server" role in the SSL protocol.

  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

  public void finalize()

Ensures that the SSL connection is closed down as cleanly as possible, in case the application forgets to do so.

Overrides:

finalize in class Object

  public String getActiveCipherSuite()

Returns the name of the 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.

Returns:

the name of the currently active cipher suite

  public String[] getEnabledCipherSuites()

Returns the names of the cipher suites which are currently enabled for use on this connection. The initial value will never include cipher suites which do not support server authentication, or which do not provide confidentiality for the data being transferred.

Returns:

an array of cipher suite names; treat as readonly.

  public InetAddress getInetAddress()

Returns the address of the remote peer for this connection.

Overrides:

getInetAddress in class Socket

  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 be confidentiality protected.

Overrides:

getInputStream in class Socket

  public int getLocalPort()

Returns the number of the local port that this connection uses.

Overrides:

getLocalPort in class Socket

  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

  public CertChain 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.

  public int getPort()

Returns the number of the remote port that this connection uses.

Overrides:

getPort in class Socket

  public String[] getSupportedCipherSuites()

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

Returns:

an array of cipher suite names; treat as readonly.

  public void setEnabledCipherSuites(String suites[])

Controls which particular cipher suites are enabled for use on this connection. The cipher suites must have been listed by getCipherSuites() as being supported.

Parameters:

suites - Names of all the cipher suites to enable.

  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