- java.lang.Object
-
- java.net.Socket
-
- javax.net.ssl.SSLSocket
-
- All Implemented Interfaces:
- Closeable, AutoCloseable
public abstract class SSLSocket extends Socket
This class extendsSocket
s 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
SSLSocket
s 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.
SSLSocket
s are created bySSLSocketFactory
s, or byaccept
ing a connection from aSSLServerSocket
.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.
- Since:
- 1.4
- See Also:
Socket
,SSLServerSocket
,SSLSocketFactory
-
-
Constructor Summary
Constructors Modifier Constructor and Description protected
SSLSocket()
Used only by subclasses.protected
SSLSocket(InetAddress address, int port)
Used only by subclasses.protected
SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)
Used only by subclasses.protected
SSLSocket(String host, int port)
Used only by subclasses.protected
SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)
Used only by subclasses.
-
Method Summary
Methods Modifier and Type Method and Description abstract void
addHandshakeCompletedListener(HandshakeCompletedListener listener)
Registers an event listener to receive notifications that an SSL handshake has completed on this connection.abstract String[]
getEnabledCipherSuites()
Returns the names of the SSL cipher suites which are currently enabled for use on this connection.abstract String[]
getEnabledProtocols()
Returns the names of the protocol versions which are currently enabled for use on this connection.abstract boolean
getEnableSessionCreation()
Returns true if new SSL sessions may be established by this socket.SSLSession
getHandshakeSession()
Returns theSSLSession
being constructed during a SSL/TLS handshake.abstract boolean
getNeedClientAuth()
Returns true if the socket will require client authentication.abstract SSLSession
getSession()
Returns the SSL Session in use by this connection.SSLParameters
getSSLParameters()
Returns the SSLParameters in effect for this SSLSocket.abstract String[]
getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on this connection.abstract String[]
getSupportedProtocols()
Returns the names of the protocols which could be enabled for use on an SSL connection.abstract boolean
getUseClientMode()
Returns true if the socket is set to use client mode when handshaking.abstract boolean
getWantClientAuth()
Returns true if the socket will request client authentication.abstract void
removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes a previously registered handshake completion listener.abstract void
setEnabledCipherSuites(String[] suites)
Sets the cipher suites enabled for use on this connection.abstract void
setEnabledProtocols(String[] protocols)
Sets the protocol versions enabled for use on this connection.abstract void
setEnableSessionCreation(boolean flag)
Controls whether new SSL sessions may be established by this socket.abstract void
setNeedClientAuth(boolean need)
Configures the socket to require client authentication.void
setSSLParameters(SSLParameters params)
Applies SSLParameters to this socket.abstract void
setUseClientMode(boolean mode)
Configures the socket to use client (or server) mode when handshaking.abstract void
setWantClientAuth(boolean want)
Configures the socket to request client authentication.abstract void
startHandshake()
Starts an SSL handshake on this connection.-
Methods inherited from class java.net.Socket
bind, close, connect, connect, getChannel, getInetAddress, getInputStream, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getOutputStream, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, shutdownInput, shutdownOutput, toString
-
-
-
-
Constructor Detail
-
SSLSocket
protected SSLSocket()
Used only by subclasses. Constructs an uninitialized, unconnected TCP socket.
-
SSLSocket
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.If there is a security manager, its
checkConnect
method is called with the host address andport
as its arguments. This could result in a SecurityException.- Parameters:
host
- name of the host with which to connect, ornull
for the loopback address.port
- number of the server's port- Throws:
IOException
- if an I/O error occurs when creating the socketSecurityException
- if a security manager exists and itscheckConnect
method doesn't allow the operation.UnknownHostException
- if the host is not knownIllegalArgumentException
- if the port parameter is outside the specified range of valid port values, which is between 0 and 65535, inclusive.- See Also:
SecurityManager.checkConnect(java.lang.String, int)
-
SSLSocket
protected SSLSocket(InetAddress address, int port) throws IOException
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 andport
as its arguments. This could result in a SecurityException.- Parameters:
address
- the server's hostport
- its port- Throws:
IOException
- if an I/O error occurs when creating the socketSecurityException
- if a security manager exists and itscheckConnect
method doesn't allow the operation.IllegalArgumentException
- if the port parameter is outside the specified range of valid port values, which is between 0 and 65535, inclusive.NullPointerException
- ifaddress
is null.- See Also:
SecurityManager.checkConnect(java.lang.String, int)
-
SSLSocket
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.If there is a security manager, its
checkConnect
method is called with the host address andport
as its arguments. This could result in a SecurityException.- Parameters:
host
- name of the host with which to connect, ornull
for the loopback address.port
- number of the server's portclientAddress
- the client's address the socket is bound to, ornull
for theanyLocal
address.clientPort
- the client's port the socket is bound to, orzero
for a system selected free port.- Throws:
IOException
- if an I/O error occurs when creating the socketSecurityException
- if a security manager exists and itscheckConnect
method doesn't allow the operation.UnknownHostException
- if the host is not knownIllegalArgumentException
- if the port parameter or clientPort parameter is outside the specified range of valid port values, which is between 0 and 65535, inclusive.- See Also:
SecurityManager.checkConnect(java.lang.String, int)
-
SSLSocket
protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) throws IOException
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 andport
as its arguments. This could result in a SecurityException.- Parameters:
address
- the server's hostport
- its portclientAddress
- the client's address the socket is bound to, ornull
for theanyLocal
address.clientPort
- the client's port the socket is bound to, orzero
for a system selected free port.- Throws:
IOException
- if an I/O error occurs when creating the socketSecurityException
- if a security manager exists and itscheckConnect
method doesn't allow the operation.IllegalArgumentException
- if the port parameter or clientPort parameter is outside the specified range of valid port values, which is between 0 and 65535, inclusive.NullPointerException
- ifaddress
is null.- See Also:
SecurityManager.checkConnect(java.lang.String, int)
-
-
Method Detail
-
getSupportedCipherSuites
public abstract String[] getSupportedCipherSuites()
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.- Returns:
- an array of cipher suite names
- See Also:
getEnabledCipherSuites()
,setEnabledCipherSuites(String [])
-
getEnabledCipherSuites
public abstract String[] getEnabledCipherSuites()
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.
- Returns:
- an array of cipher suite names
- See Also:
getSupportedCipherSuites()
,setEnabledCipherSuites(String [])
-
setEnabledCipherSuites
public abstract 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. Following a successful call to this method, only suites listed in thesuites
parameter are enabled for use.See
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 ciphers named by the parameter is not supported, or when the parameter is null.- See Also:
getSupportedCipherSuites()
,getEnabledCipherSuites()
-
getSupportedProtocols
public abstract String[] getSupportedProtocols()
Returns the names of the protocols which could be enabled for use on an SSL connection.- Returns:
- an array of protocols supported
-
getEnabledProtocols
public abstract String[] getEnabledProtocols()
Returns the names of the protocol versions which are currently enabled for use on this connection.- Returns:
- an array of protocols
- See Also:
setEnabledProtocols(String [])
-
setEnabledProtocols
public abstract void setEnabledProtocols(String[] protocols)
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 theprotocols
parameter are enabled for use.- Parameters:
protocols
- Names of all the protocols to enable.- Throws:
IllegalArgumentException
- when one or more of the protocols named by the parameter is not supported or when the protocols parameter is null.- See Also:
getEnabledProtocols()
-
getSession
public abstract SSLSession getSession()
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".
- Returns:
- the
SSLSession
-
getHandshakeSession
public SSLSession getHandshakeSession()
Returns theSSLSession
being constructed during a SSL/TLS handshake.TLS protocols may negotiate parameters that are needed when using an instance of this class, but before the
SSLSession
has been completely initialized and made available viagetSession
. For example, the list of valid signature algorithms may restrict the type of certificates that can used during TrustManager decisions, or the maximum TLS fragment packet sizes can be resized to better support the network environment.This method provides early access to the
SSLSession
being constructed. Depending on how far the handshake has progressed, some data may not yet be available for use. For example, if a remote server will be sending a Certificate chain, but that chain has yet not been processed, thegetPeerCertificates
method ofSSLSession
will throw a SSLPeerUnverifiedException. Once that chain has been processed,getPeerCertificates
will return the proper value.Unlike
getSession()
, this method does not initiate the initial handshake and does not block until handshaking is complete.- Returns:
- null if this instance is not currently handshaking, or
if the current handshake has not progressed far enough to
create a basic SSLSession. Otherwise, this method returns the
SSLSession
currently being negotiated. - Throws:
UnsupportedOperationException
- if the underlying provider does not implement the operation.- Since:
- 1.7
- See Also:
SSLEngine
,SSLSession
,ExtendedSSLSession
,X509ExtendedKeyManager
,X509ExtendedTrustManager
-
addHandshakeCompletedListener
public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)
Registers an event listener to receive notifications that an SSL handshake has completed on this connection.- Parameters:
listener
- the HandShake Completed event listener- Throws:
IllegalArgumentException
- if the argument is null.- See Also:
startHandshake()
,removeHandshakeCompletedListener(HandshakeCompletedListener)
-
removeHandshakeCompletedListener
public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes a previously registered handshake completion listener.- Parameters:
listener
- the HandShake Completed event listener- Throws:
IllegalArgumentException
- if the listener is not registered, or the argument is null.- See Also:
addHandshakeCompletedListener(HandshakeCompletedListener)
-
startHandshake
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. 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:
addHandshakeCompletedListener(HandshakeCompletedListener)
-
setUseClientMode
public abstract void setUseClientMode(boolean mode)
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 handshaking in "client" mode- Throws:
IllegalArgumentException
- if a mode change is attempted after the initial handshake has begun.- See Also:
getUseClientMode()
-
getUseClientMode
public abstract boolean getUseClientMode()
Returns true if the socket is set to use client mode when handshaking.- Returns:
- true if the socket should do handshaking in "client" mode
- See Also:
setUseClientMode(boolean)
-
setNeedClientAuth
public abstract void setNeedClientAuth(boolean need)
Configures the socket to require client authentication. This option is only useful for sockets in the server mode.A socket's client authentication setting is one of the following:
- client authentication required
- client authentication requested
- no client authentication desired
Unlike
setWantClientAuth(boolean)
, if this option is set and the client chooses not to provide authentication information about itself, the negotiations will stop and the connection will be dropped.Calling this method overrides any previous setting made by this method or
setWantClientAuth(boolean)
.- Parameters:
need
- set to true if client authentication is required, or false if no client authentication is desired.- See Also:
getNeedClientAuth()
,setWantClientAuth(boolean)
,getWantClientAuth()
,setUseClientMode(boolean)
-
getNeedClientAuth
public abstract boolean getNeedClientAuth()
Returns true if the socket will require client authentication. This option is only useful to sockets in the server mode.- Returns:
- true if client authentication is required, or false if no client authentication is desired.
- See Also:
setNeedClientAuth(boolean)
,setWantClientAuth(boolean)
,getWantClientAuth()
,setUseClientMode(boolean)
-
setWantClientAuth
public abstract void setWantClientAuth(boolean want)
Configures the socket to request client authentication. This option is only useful for sockets in the server mode.A socket's client authentication setting is one of the following:
- client authentication required
- client authentication requested
- no client authentication desired
Unlike
setNeedClientAuth(boolean)
, if this option is set and the client chooses not to provide authentication information about itself, the negotiations will continue.Calling this method overrides any previous setting made by this method or
setNeedClientAuth(boolean)
.- Parameters:
want
- set to true if client authentication is requested, or false if no client authentication is desired.- See Also:
getWantClientAuth()
,setNeedClientAuth(boolean)
,getNeedClientAuth()
,setUseClientMode(boolean)
-
getWantClientAuth
public abstract boolean getWantClientAuth()
Returns true if the socket will request client authentication. This option is only useful for sockets in the server mode.- Returns:
- true if client authentication is requested, or false if no client authentication is desired.
- See Also:
setNeedClientAuth(boolean)
,getNeedClientAuth()
,setWantClientAuth(boolean)
,setUseClientMode(boolean)
-
setEnableSessionCreation
public abstract 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; this is the default. false indicates that an existing session must be resumed- See Also:
getEnableSessionCreation()
-
getEnableSessionCreation
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
- See Also:
setEnableSessionCreation(boolean)
-
getSSLParameters
public SSLParameters getSSLParameters()
Returns the SSLParameters in effect for this SSLSocket. The ciphersuites and protocols of the returned SSLParameters are always non-null.- Returns:
- the SSLParameters in effect for this SSLSocket.
- Since:
- 1.6
-
setSSLParameters
public void setSSLParameters(SSLParameters params)
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()
orparams.getWantClientAuth()
returntrue
,setNeedClientAuth(true)
andsetWantClientAuth(true)
are called, respectively; otherwisesetWantClientAuth(false)
is called.
- Parameters:
params
- the parameters- Throws:
IllegalArgumentException
- if the setEnabledCipherSuites() or the setEnabledProtocols() call fails- Since:
- 1.6
- if
-
-
Document created the 11/06/2005, last modified the 04/03/2020
Source of the printed document:https://www.gaudry.be/en/java-api-rf-javax/net/ssl/SSLSocket.html
The infobrol is a personal site whose content is my sole responsibility. The text is available under CreativeCommons license (BY-NC-SA). More info on the terms of use and the author.
References
These references and links indicate documents consulted during the writing of this page, or which may provide additional information, but the authors of these sources can not be held responsible for the content of this page.
The author This site is solely responsible for the way in which the various concepts, and the freedoms that are taken with the reference works, are presented here. Remember that you must cross multiple source information to reduce the risk of errors.