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:
- 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.
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:
- Supported cipher suites: all the suites
which are supported by the SSL implementation. This group
is acquired 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.
- Default cipher suites ... the group of cipher
suites which are enabled by default. You can query the group
of cipher suites which are enabled by default using the
getDefaultCipherSuites method.
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:
- This API is still a "work in progress". Comments are solicited!
It is not intended to be a complete (or final) API at this time.
- As of this writing, client authentication is not implemented. Client
authentication (to servers) is a requirement, and it will be supported in
a later release.
- See Also:
- SSLServerSocket
-
SSLSocket(AuthContext, InetAddress, int)
- Constructs an SSL connection to a server at a specified address.
-
SSLSocket(AuthContext, String, int)
- Constructs an SSL connection to a named host at a specified port,
using the authentication context provided.
-
SSLSocket(InetAddress, int)
- Constructs an SSL connection to a server at a specified address
and TCP port.
-
SSLSocket(Socket, AuthContext)
- Layer SSL traffic over an existing connection, rather than creating
a new connection.
-
SSLSocket(Socket, AuthContext, 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 SSL cipher suite which is currently active
on this connection.
-
getDefaultCipherSuites()
- Returns the list of cipher suites which are enabled by default.
-
getEnabledCipherSuites()
- Returns the names of the SSL 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.
-
getSession()
- Valid only on the server side of an SSL connection, this returns the
the SSL Session in use by this connection.
-
getSoLinger()
- Returns the socket's linger timeout.
-
getSoTimeout()
- Returns the socket timeout.
-
getSupportedCipherSuites()
- Returns the names of the cipher suites which could be enabled for use
on an SSL connection.
-
getTcpNoDelay()
- Returns true if the Nagle optimization is disabled.
-
setEnabledCipherSuites(String[])
- Controls which particular cipher suites are enabled for use on
this connection.
-
setSoLinger(boolean, int)
- Assigns the socket's linger timeout.
-
setSoTimeout(int)
- Assigns the socket timeout.
-
setTcpNoDelay(boolean)
- Enables or disables the Nagle optimization.
-
toString()
- Returns a printable representation of this end of the connection.
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
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
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
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
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
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
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
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
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:
- SSL_RSA_WITH_RC4_128_MD5 ... a non-exportable cipher suite
supporting 128 bit RC4 encryption keys and full RSA key sizes.
- SSL_DH_anon_WITH_DES_CBC_SHA ... a non-exportable cipher suite
supporting 56 bit DES encryption keys, but which doesn't support
authentication of servers.
- SSL_RSA_EXPORT_WITH_RC4_40_MD5 ... an exportable cipher
suite using weakened RC4 encryption and limited RSA key sizes.
- SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA ... an exportable cipher
suite using weakened DES encryption, and which doesn't support
authentication of servers.
- SSL_RSA_WITH_NULL_MD5 ... an exportable cipher suite using
no encryption and full RSA key sizes.
- SSL_NULL_WITH_NULL_NULL ... indicates that the connection
has not yet been used to send application data, so that no cipher
suite is in effect.
- Returns:
- the name of the currently active cipher suite
- See Also:
- getEnabledCipherSuites, getSupportedCipherSuites, setEnabledCipherSuites
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
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
getInetAddress
public InetAddress getInetAddress()
- Returns the address of the remote peer for this connection.
- Overrides:
- getInetAddress in class Socket
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
getLocalPort
public int getLocalPort()
- Returns the number of the local port that this connection uses.
- Overrides:
- getLocalPort in class Socket
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
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.
getPort
public int getPort()
- Returns the number of the remote port that this connection uses.
- Overrides:
- getPort in class Socket
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.
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
getSoLinger
public int getSoLinger() throws SocketException
- Returns the socket's linger timeout.
- Overrides:
- getSoLinger in class Socket
- See Also:
- getSoLinger
getSoTimeout
public synchronized int getSoTimeout() throws SocketException
- Returns the socket timeout.
- Overrides:
- getSoTimeout in class Socket
- See Also:
- getSoTimeout
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
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
setSoLinger
public void setSoLinger(boolean flag,
int linger) throws SocketException
- Assigns the socket's linger timeout.
- Overrides:
- setSoLinger in class Socket
- See Also:
- setSoLinger
setSoTimeout
public synchronized void setSoTimeout(int timeout) throws SocketException
- Assigns the socket timeout.
- Overrides:
- setSoTimeout in class Socket
- See Also:
- setSoTimeout
setTcpNoDelay
public void setTcpNoDelay(boolean value) throws SocketException
- Enables or disables the Nagle optimization.
- Overrides:
- setTcpNoDelay in class Socket
- See Also:
- setTcpNoDelay
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