public class SSLSocket extends java.net.Socket implements TLS13Communication
java.net.Socket
and therefore can be used
anywhere in its place making it very easy to secure existing
applications. The actual TLS functionality is located in the
SSLTransport class, see there for more general documentation.
Note that by default the TLS handshake is automatically
started when you call getInputStream()
or
getOutputStream()
. This will be the desired behavior
in most cases, but not when connecting through proxies.
In that case you have three options:
proxyConnect()
in the Utils
class.
Constructor and Description |
---|
SSLSocket(java.net.InetAddress address,
int port,
java.net.InetAddress localAddr,
int localPort,
SSLContext context)
Creates a SSL socket and connects it to the specified remote address on
the specified remote port.
|
SSLSocket(java.net.InetAddress address,
int port,
SSLContext context)
Creates a SSL socket and connects it to the specified port
number at the specified IP address.
|
SSLSocket(java.net.InetAddress address,
java.lang.String host,
int port,
java.net.InetAddress localAddr,
int localPort,
SSLContext context)
Creates a SSL socket and connects it to the specified remote address on
the specified remote port.
|
SSLSocket(java.net.InetAddress address,
java.lang.String host,
int port,
SSLContext context)
Creates a SSL socket and connects it to the specified port
number at the specified IP address.
|
SSLSocket(java.net.Socket socket,
SSLContext context)
Creates a SSLSocket from an existing socket.
|
SSLSocket(java.net.Socket proxySocket,
SSLContext context,
java.lang.String host,
int port)
Creates a socket layered over an existing socket to a ServerSocket on the named host,
at the given port.
|
SSLSocket(java.lang.String host,
int port,
java.net.InetAddress localAddr,
int localPort,
SSLContext context)
Creates a SSL socket and connects it to the specified remote host on
the specified remote port.
|
SSLSocket(java.lang.String host,
int port,
SSLContext context)
Creates a SSL socket and connects it to the specified port
number on the named host.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Close this SSL socket.
|
CipherSuite |
getActiveCipherSuite()
Returns the active cipher suite.
|
CompressionMethod |
getActiveCompressionMethod()
Returns the active compression method.
|
ExtensionList |
getActiveExtensions()
Gets the active TLS extensions of the current TLS session.
|
int |
getActiveProtocolVersion()
Return the active SSL protocol version.
|
ChannelBindings |
getChannelBindings()
Gets the ChannelBindings associated with this Handshaker.
|
CipherSuite[] |
getClientSupportedCipherSuites()
Deprecated.
use getPeerSupportedCipherSuiteList()
|
CompressionMethod[] |
getClientSupportedCompressionMethods()
Deprecated.
use getPeerSupportedCompressionMethods()
|
SSLContext |
getContext()
Returns the SSLContext of this SSLSocket.
|
java.net.InetAddress |
getInetAddress()
See JDK documentation of java.net.Socket for a description of this method.
|
java.io.InputStream |
getInputStream()
Returns an input stream for this socket.
|
java.net.InetAddress |
getLocalAddress()
See JDK documentation of java.net.Socket for a description of this method.
|
int |
getLocalPort()
See JDK documentation of java.net.Socket for a description of this method.
|
java.io.OutputStream |
getOutputStream()
Returns an output stream for this socket.
|
java.security.cert.X509Certificate[] |
getPeerCertificateChain()
Returns the certificate chain sent by the peer or null if the peer
has no certificate.
|
ExtensionList |
getPeerExtensions()
Gets the TLS extension received from the peer.
|
CipherSuiteList |
getPeerSupportedCipherSuiteList()
Return the list of cipher suites known to be supported by the remote peer.
|
CompressionMethod[] |
getPeerSupportedCompressionMethods()
Return the compression methods supported by the remote peer.
|
int |
getPort()
See JDK documentation of java.net.Socket for a description of this method.
|
java.lang.String |
getPSKIdentity()
Returns the PSK identity used for identifying the pre-shared
key or
null if no PSK cipher suite is used for
the communication. |
Session |
getSession()
Returns the currently active Session for this SSLSocket.
|
int |
getSoLinger()
See JDK documentation of java.net.Socket for a description of this method.
|
int |
getSoTimeout()
See JDK documentation of java.net.Socket for a description of this method.
|
boolean |
getTcpNoDelay()
See JDK documentation of java.net.Socket for a description of this method.
|
SSLTransport |
getTransport()
Get the SSLTransport this socket is talking over.
|
boolean |
getUseClientMode()
Returns whether or not this socket resides on the client
side of the connection.
|
void |
init(java.net.Socket s,
SSLContext context,
boolean useClientMode)
Initialize the SSLSocket.
|
boolean |
isServer()
Deprecated.
use getUseClientMode()
|
void |
postHandshake(TLS13PostHandshakeConfig postHandshakeConfig)
Performs a TLS 1.3 post handshake.
|
void |
renegotiate()
Start a renegotiating SSL handshake.
|
void |
setAutoHandshake(boolean on)
Can be used to switch off the automatic start of the handshake procedure.
|
void |
setDebugStream(java.io.OutputStream os)
Enables debugging mode.
|
void |
setDebugStream(java.io.Writer writer)
Enables debugging mode.
|
void |
setSoLinger(boolean on,
int val)
See JDK documentation of java.net.Socket for a description of this method.
|
void |
setSoTimeout(int timeout)
See JDK documentation of java.net.Socket for a description of this method.
|
void |
setTcpNoDelay(boolean on)
See JDK documentation of java.net.Socket for a description of this method.
|
void |
setUseClientMode(boolean mode)
Select client or server mode for this socket.
|
void |
shutdown()
Shuts the SSL layer down.
|
void |
shutdownInput()
Not supported for SSL/TLS.
|
void |
shutdownOutput()
Not supported for SSL/TLS.
|
void |
startHandshake()
Start the SSL handshake process.
|
bind, connect, connect, getChannel, getKeepAlive, getLocalSocketAddress, getOOBInline, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setTrafficClass, toString
public SSLSocket(java.net.Socket socket, SSLContext context) throws java.io.IOException
java.io.IOException
public SSLSocket(java.lang.String host, int port, SSLContext context) throws java.io.IOException, java.net.UnknownHostException
All properties of this SSLSocket are defined in the SSLContext.
host
- the host name.port
- the port number.context
- the SSLContext for the new socketjava.io.IOException
- if an error occurs when creating the socketjava.net.UnknownHostException
public SSLSocket(java.net.InetAddress address, int port, SSLContext context) throws java.io.IOException
All properties of this SSLSocket are defined in the SSLContext.
address
- the IP address.port
- the port number.context
- the SSLContext for the new socketjava.io.IOException
- if an error occurs when creating the socketpublic SSLSocket(java.net.InetAddress address, java.lang.String host, int port, SSLContext context) throws java.io.IOException
All properties of this SSLSocket are defined in the SSLContext.
address
- the IP address.host
- the host nameport
- the port number.context
- the SSLContext for the new socketjava.io.IOException
- if an error occurs when creating the socketpublic SSLSocket(java.lang.String host, int port, java.net.InetAddress localAddr, int localPort, SSLContext context) throws java.io.IOException
All properties of this SSLSocket are defined in the SSLContext.
host
- the name of the remote hostport
- the remote portlocalAddr
- the local address the socket is bound tolocalPort
- the local port the socket is bound tocontext
- the SSLContext for the new socketjava.io.IOException
- if an error occurs when creating the socketpublic SSLSocket(java.net.InetAddress address, int port, java.net.InetAddress localAddr, int localPort, SSLContext context) throws java.io.IOException
All properties of this SSLSocket are defined in the SSLContext.
address
- the remote addressport
- the remote portlocalAddr
- the local address the socket is bound tolocalPort
- the local port the socket is bound tocontext
- the SSLContext for the new socketjava.io.IOException
- if an error occurs when creating the socketpublic SSLSocket(java.net.InetAddress address, java.lang.String host, int port, java.net.InetAddress localAddr, int localPort, SSLContext context) throws java.io.IOException
All properties of this SSLSocket are defined in the SSLContext.
address
- the remote addresshost
- the name of the remote hostport
- the remote portlocalAddr
- the local address the socket is bound tolocalPort
- the local port the socket is bound tocontext
- the SSLContext for the new socketjava.io.IOException
- if an error occurs when creating the socketpublic SSLSocket(java.net.Socket proxySocket, SSLContext context, java.lang.String host, int port) throws java.io.IOException
proxySocket
- the socket connected to the proxy servercontext
- the SSLContext for the new sockethost
- the name of the logical destination serverport
- the port of the logical destination serverjava.io.IOException
public SSLTransport getTransport()
public void init(java.net.Socket s, SSLContext context, boolean useClientMode) throws java.io.IOException
s
- the socket to be initializedcontext
- the SSLContext of this socketuseClientMode
- true if client mode should be usedjava.io.IOException
public void setUseClientMode(boolean mode) throws java.io.IOException
SSLCommunication
This selection can only be made prior to the initial SSL handshake. If the method is called made afterwards an SSLException is thrown.
setUseClientMode
in interface SSLCommunication
java.io.IOException
public boolean getUseClientMode()
SSLCommunication
getUseClientMode
in interface SSLCommunication
public SSLContext getContext()
SSLCommunication
getContext
in interface SSLCommunication
public void setAutoHandshake(boolean on)
SSLCommunication
If auto handshake is switched off the application has to start the handshaking process manually using the method startHandshake(). This kind of operation is used when connecting over a proxy or firewall.
setAutoHandshake
in interface SSLCommunication
on
- true if handshake should start automatically, false otherwiseSSLCommunication.startHandshake()
public java.security.cert.X509Certificate[] getPeerCertificateChain()
SSLCommunication
In SSLv2 this will always just return the server's certificate (protocol limitation). Note that some SSLv3/TLS server do not include self signed certificates as those will have to be obtained and verified using a different method anyway.
getPeerCertificateChain
in interface SSLCommunication
public java.lang.String getPSKIdentity()
null
if no PSK cipher suite is used for
the communication.getPSKIdentity
in interface TLSCommunication
null
if no PSK cipher
suite is used for the communicationpublic int getActiveProtocolVersion()
SSLCommunication
getActiveProtocolVersion
in interface SSLCommunication
SSLContext
public CipherSuite getActiveCipherSuite()
SSLCommunication
getActiveCipherSuite
in interface SSLCommunication
CipherSuite
public CompressionMethod getActiveCompressionMethod()
SSLCommunication
getActiveCompressionMethod
in interface SSLCommunication
CompressionMethod
public CipherSuiteList getPeerSupportedCipherSuiteList()
SSLCommunication
getPeerSupportedCipherSuiteList
in interface SSLCommunication
CipherSuite
,
SSLCommunication.getActiveCipherSuite()
public CompressionMethod[] getPeerSupportedCompressionMethods()
SSLCommunication
getPeerSupportedCipherSuiteList()
, see there with
the exception of the SSLv2 case. As there are no compression
in SSLv2 the empty array is returned.getPeerSupportedCompressionMethods
in interface SSLCommunication
CompressionMethod
,
SSLCommunication.getActiveCompressionMethod()
public ExtensionList getPeerExtensions()
Note that the extensions are cloned before returned by this method. Since cloning may be an expensive operation, you may call this method only if required.
getPeerExtensions
in interface TLSCommunication
null
if the peer did not sent any extensionspublic ExtensionList getActiveExtensions()
peer extensions
.
Note that the extensions are cloned before returned by this method. Since cloning may be an expensive operation, you may call this method only if required.
getActiveExtensions
in interface TLSCommunication
null
if no extensions are usedpublic Session getSession()
SSLCommunication
getSession
in interface SSLCommunication
public ChannelBindings getChannelBindings()
getChannelBindings
in interface TLSCommunication
null
if no channel bindings are
available (e.g. if the application does not have
announced
interest in channel bindings.public void renegotiate() throws java.io.IOException
SSLCommunication
getSession().invalidate()
before
calling renegotiate, see below for more information.
Basically there are two reasons you might want to initiate renegotiation:
This method locks the InputStream and the OutputStream for exclusive access before proceeding with the handshake. That means that for the duration of the handshake procedure no communication is possible and more importantly that the handshake can not begin until possible blocking read() and write() calls by other threads have completed.
renegotiate
in interface SSLCommunication
java.io.IOException
- if an error occurs during the handshake procedurepublic void postHandshake(TLS13PostHandshakeConfig postHandshakeConfig) throws java.io.IOException
This method may be called by an application to trigger some
post handshake action. The given post handshake configuration
specifies the type of post handshake
to be performed (either NEW_SESSION_TICKET
to send a new session ticket to the client,
POST_HANDSHAKE_AUTH
to
request post client authentication, or KEY_UPDATE
to perform a key update) and may provide some configuration options.
Sending a new session ticket or requesting post client authentication may
be only triggered on the server side, a key update may be done on both, client
or server side.
postHandshake
in interface TLS13Communication
postHandshakeConfig
- the post handshake configurationjava.io.IOException
- if the requested post handshake action is not suitable for the local
connection end, handshake state or protocol version, or some error occurs when
performing the post handshakepublic void startHandshake() throws java.io.IOException
SSLCommunication
This method locks the InputStream and the OutputStream for exclusive access before proceeding with the handshake. That means that for the duration of the handshake procedure no communication is possible and more importantly that the handshake can not begin until possible blocking read() and write() calls by other threads have completed.
startHandshake
in interface SSLCommunication
java.io.IOException
- if an error occurs during the handshake procedureSSLCommunication.setAutoHandshake(boolean)
public java.io.OutputStream getOutputStream() throws java.io.IOException
SSLCommunication
getOutputStream
in interface SSLCommunication
getOutputStream
in class java.net.Socket
java.io.IOException
- if an error occurs when creating the output streampublic java.io.InputStream getInputStream() throws java.io.IOException
SSLCommunication
getInputStream
in interface SSLCommunication
getInputStream
in class java.net.Socket
java.io.IOException
- if an error occurs when creating the input stream.public void setDebugStream(java.io.Writer writer)
SSLCommunication
setDebugStream
in interface SSLCommunication
writer
- the Writer to which debug information shall be writtenpublic void setDebugStream(java.io.OutputStream os)
SSLCommunication
setDebugStream
in interface SSLCommunication
os
- the OutputStream to which debug information shall be writtenpublic void shutdown() throws java.io.IOException
SSLCommunication
A SSL layer shutdown occurs in the following cases:
shutdown
in interface SSLCommunication
java.io.IOException
- if an I/O error occurs when closing this SSLSocketpublic void close() throws java.io.IOException
SSLCommunication
This method will never be called by the library itself, it will always just call shutdown(). It is the responsibility of the application to always close the socket when communication has been completed. Once the socket has been closed read() and write() calls will throw SocketExceptions. The behaviour described here is compatible with the original Java sockets.
close
in interface SSLCommunication
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
close
in class java.net.Socket
java.io.IOException
public CipherSuite[] getClientSupportedCipherSuites()
public CompressionMethod[] getClientSupportedCompressionMethods()
public boolean isServer()
public java.net.InetAddress getInetAddress()
getInetAddress
in class java.net.Socket
public java.net.InetAddress getLocalAddress()
getLocalAddress
in class java.net.Socket
public int getPort()
getPort
in class java.net.Socket
public int getLocalPort()
getLocalPort
in class java.net.Socket
public void setTcpNoDelay(boolean on) throws java.net.SocketException
setTcpNoDelay
in class java.net.Socket
java.net.SocketException
public boolean getTcpNoDelay() throws java.net.SocketException
getTcpNoDelay
in class java.net.Socket
java.net.SocketException
public void setSoLinger(boolean on, int val) throws java.net.SocketException
setSoLinger
in class java.net.Socket
java.net.SocketException
public int getSoLinger() throws java.net.SocketException
getSoLinger
in class java.net.Socket
java.net.SocketException
public void setSoTimeout(int timeout) throws java.net.SocketException
setSoTimeout
in class java.net.Socket
java.net.SocketException
public int getSoTimeout() throws java.net.SocketException
getSoTimeout
in class java.net.Socket
java.net.SocketException
public final void shutdownInput() throws java.io.IOException
shutdownInput
in class java.net.Socket
java.lang.UnsupportedOperationException
java.io.IOException
public final void shutdownOutput() throws java.io.IOException
shutdownOutput
in class java.net.Socket
java.lang.UnsupportedOperationException
java.io.IOException