| |
|
| java.lang.Object
 java.net.Socket
javax.net.ssl.SSLSocket
| SSLSocket | | abstract public class SSLSocket extends Socket (Code) | | 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 futher 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.
See Also: java.net.Socket
See Also: SSLServerSocket
See Also: SSLSocketFactory
since:
1.4
version:
1.37
author:
David Brownell |
| Constructor Summary | |
| protected | SSLSocket()
Used only by subclasses. | | protected | SSLSocket(String host, int port)
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. | | protected | SSLSocket(InetAddress address, int port)
Used only by subclasses.
Constructs a TCP connection to a server at a specified address
and port. | | protected | SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)
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. | | protected | SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)
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. |
| Method Summary | |
| abstract public void | addHandshakeCompletedListener(HandshakeCompletedListener listener)
Registers an event listener to receive notifications that an
SSL handshake has completed on this connection. | | abstract public boolean | getEnableSessionCreation()
Returns true if new SSL sessions may be established by this socket.
true indicates that sessions may be created; thisis the default. | | abstract public String[] | getEnabledCipherSuites()
Returns the names of the SSL cipher suites which are currently
enabled for use on this connection. | | abstract public String[] | getEnabledProtocols()
Returns the names of the protocol versions which are currently
enabled for use on this connection. | | abstract public boolean | getNeedClientAuth()
Returns true if the socket will require client authentication. | | public SSLParameters | getSSLParameters()
Returns the SSLParameters in effect for this SSLSocket. | | abstract public SSLSession | getSession()
Returns the SSL Session in use by this connection. | | abstract public String[] | getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use
on this connection. | | abstract public String[] | getSupportedProtocols()
Returns the names of the protocols which could be enabled for use
on an SSL connection. | | abstract public boolean | getUseClientMode()
Returns true if the socket is set to use client mode when
handshaking. | | abstract public boolean | getWantClientAuth()
Returns true if the socket will request client authentication. | | abstract public void | removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes a previously registered handshake completion listener. | | abstract public void | setEnableSessionCreation(boolean flag)
Controls whether new SSL sessions may be established by this socket.
If session creations are not allowed, and there are no
existing sessions to resume, there will be no successful
handshaking.
Parameters:
flag - true indicates that sessions may be created; thisis the default. | | abstract public void | setEnabledCipherSuites(String suites)
Sets the cipher suites enabled for use on this connection.
Each cipher suite in the suites parameter must have
been listed by getSupportedCipherSuites(), or the method will
fail. | | abstract public void | setEnabledProtocols(String protocols)
Sets the protocol versions enabled for use on this connection. | | abstract public void | setNeedClientAuth(boolean need)
Configures the socket to require client authentication. | | public void | setSSLParameters(SSLParameters params)
Applies SSLParameters to this socket. | | abstract public void | setUseClientMode(boolean mode)
Configures the socket to use client (or server) mode when
handshaking. | | abstract public void | setWantClientAuth(boolean want)
Configures the socket to request client authentication. | | abstract public void | startHandshake()
Starts an SSL handshake on this connection. |
| SSLSocket | | protected SSLSocket()(Code) | | Used only by subclasses.
Constructs an uninitialized, unconnected TCP socket.
|
| SSLSocket | | protected SSLSocket(String host, int port) throws IOException, UnknownHostException(Code) | | 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, ornull for the loopback address.
Parameters:
port - number of the server's port
throws:
IOException - if an I/O error occurs when creating the socket
throws:
SecurityException - if a security manager exists and itscheckConnect method doesn't allow the operation.
throws:
UnknownHostException - if the host is not known
throws:
IllegalArgumentException - if the port parameter is outside thespecified range of valid port values, which is between 0 and65535, inclusive.
See Also: SecurityManager.checkConnect |
| SSLSocket | | protected SSLSocket(InetAddress address, int port) throws IOException(Code) | | 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
Parameters:
port - its port
throws:
IOException - if an I/O error occurs when creating the socket
throws:
SecurityException - if a security manager exists and itscheckConnect method doesn't allow the operation.
throws:
IllegalArgumentException - if the port parameter is outside thespecified range of valid port values, which is between 0 and65535, inclusive.
throws:
NullPointerException - if address is null.
See Also: SecurityManager.checkConnect |
| SSLSocket | | protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) throws IOException, UnknownHostException(Code) | | 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, ornull for the loopback address.
Parameters:
port - number of the server's port
Parameters:
clientAddress - the client's host
Parameters:
clientPort - number of the client's port
throws:
IOException - if an I/O error occurs when creating the socket
throws:
SecurityException - if a security manager exists and itscheckConnect method doesn't allow the operation.
throws:
UnknownHostException - if the host is not known
throws:
IllegalArgumentException - if the port parameter or clientPortparameter is outside the specified range of valid port values,which is between 0 and 65535, inclusive.
See Also: SecurityManager.checkConnect |
| SSLSocket | | protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) throws IOException(Code) | | 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
Parameters:
port - its port
Parameters:
clientAddress - the client's host
Parameters:
clientPort - number of the client's port
throws:
IOException - if an I/O error occurs when creating the socket
throws:
SecurityException - if a security manager exists and itscheckConnect method doesn't allow the operation.
throws:
IllegalArgumentException - if the port parameter or clientPortparameter is outside the specified range of valid port values,which is between 0 and 65535, inclusive.
throws:
NullPointerException - if address is null.
See Also: SecurityManager.checkConnect |
| getEnableSessionCreation | | abstract public boolean getEnableSessionCreation()(Code) | | Returns true if new SSL sessions may be established by this socket.
true indicates that sessions may be created; thisis the default. false indicates that an existing sessionmust be resumed
See Also: SSLSocket.setEnableSessionCreation(boolean) |
| getEnabledCipherSuites | | abstract public String[] getEnabledCipherSuites()(Code) | | Returns the names of the SSL cipher suites which are currently
enabled for use on this connection. When an SSLSocket is first
created, all enabled cipher suites support a minimum quality of
service. Thus, in some environments this value might be empty.
Even if a suite has been enabled, it might never be used. (For
example, the peer does not support it, the requisite certificates
(and private keys) for the suite are not available, or an
anonymous suite is enabled but authentication is required.
an array of cipher suite names
See Also: SSLSocket.getSupportedCipherSuites()
See Also: SSLSocket.setEnabledCipherSuites(String[]) |
| getSSLParameters | | public SSLParameters getSSLParameters()(Code) | | Returns the SSLParameters in effect for this SSLSocket.
The ciphersuites and protocols of the returned SSLParameters
are always non-null.
the SSLParameters in effect for this SSLSocket.
since:
1.6 |
| getSession | | abstract public SSLSession getSession()(Code) | | Returns 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.
This method will initiate the initial handshake if
necessary and then block until the handshake has been
established.
If an error occurs during the initial handshake, this method
returns an invalid session object which reports an invalid
cipher suite of "SSL_NULL_WITH_NULL_NULL".
the SSLSession |
| getSupportedCipherSuites | | abstract public String[] getSupportedCipherSuites()(Code) | | Returns the names of the cipher suites which could be enabled for use
on this 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 might be useful in specialized applications.
an array of cipher suite names
See Also: SSLSocket.getEnabledCipherSuites()
See Also: SSLSocket.setEnabledCipherSuites(String[]) |
| getSupportedProtocols | | abstract public String[] getSupportedProtocols()(Code) | | Returns the names of the protocols which could be enabled for use
on an SSL connection.
an array of protocols supported |
| getUseClientMode | | abstract public boolean getUseClientMode()(Code) | | Returns true if the socket is set to use client mode when
handshaking.
true if the socket should do handshakingin "client" mode
See Also: SSLSocket.setUseClientMode(boolean) |
| setEnableSessionCreation | | abstract public void setEnableSessionCreation(boolean flag)(Code) | | Controls whether new SSL sessions may be established by this socket.
If session creations are not allowed, and there are no
existing sessions to resume, there will be no successful
handshaking.
Parameters:
flag - true indicates that sessions may be created; thisis the default. false indicates that an existing sessionmust be resumed
See Also: SSLSocket.getEnableSessionCreation() |
| setEnabledCipherSuites | | abstract public void setEnabledCipherSuites(String suites)(Code) | | Sets the cipher suites enabled for use on this connection.
Each cipher suite in the suites parameter must have
been listed by getSupportedCipherSuites(), or the method will
fail. Following a successful call to this method, only suites
listed in the suites parameter are enabled for use.
See
SSLSocket.getEnabledCipherSuites() for more information
on why a specific ciphersuite may never be used on a connection.
Parameters:
suites - Names of all the cipher suites to enable
throws:
IllegalArgumentException - when one or more of the ciphersnamed by the parameter is not supported, or when theparameter is null.
See Also: SSLSocket.getSupportedCipherSuites()
See Also: SSLSocket.getEnabledCipherSuites() |
| setEnabledProtocols | | abstract public void setEnabledProtocols(String protocols)(Code) | | Sets the protocol versions enabled for use on this connection.
The protocols must have been listed by
getSupportedProtocols() as being supported.
Following a successful call to this method, only protocols listed
in the protocols parameter are enabled for use.
Parameters:
protocols - Names of all the protocols to enable.
throws:
IllegalArgumentException - when one or more ofthe protocols named by the parameter is not supported orwhen the protocols parameter is null.
See Also: SSLSocket.getEnabledProtocols() |
| setSSLParameters | | public void setSSLParameters(SSLParameters params)(Code) | | Applies SSLParameters to this socket.
This means:
- if
params.getCipherSuites() is non-null,
setEnabledCipherSuites() is called with that value
- if
params.getProtocols() is non-null,
setEnabledProtocols() is called with that value
- if
params.getNeedClientAuth() or
params.getWantClientAuth() return true,
setNeedClientAuth(true) and
setWantClientAuth(true) are called, respectively;
otherwise setWantClientAuth(false) is called.
Parameters:
params - the parameters
throws:
IllegalArgumentException - if the setEnabledCipherSuites() orthe setEnabledProtocols() call fails
since:
1.6 |
| setUseClientMode | | abstract public void setUseClientMode(boolean mode)(Code) | | 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 handshakingin "client" mode
throws:
IllegalArgumentException - if a mode change is attemptedafter the initial handshake has begun.
See Also: SSLSocket.getUseClientMode() |
| startHandshake | | abstract public void startHandshake() throws IOException(Code) | | 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
See Also: SSLSocket.addHandshakeCompletedListener(HandshakeCompletedListener) |
|
|
|