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, toStringpublic SSLSocket(java.net.Socket socket,
SSLContext context)
throws java.io.IOException
java.io.IOExceptionpublic 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.UnknownHostExceptionpublic 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.IOExceptionpublic 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.IOExceptionpublic void setUseClientMode(boolean mode)
throws java.io.IOException
SSLCommunicationThis 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 SSLCommunicationjava.io.IOExceptionpublic boolean getUseClientMode()
SSLCommunicationgetUseClientMode in interface SSLCommunicationpublic SSLContext getContext()
SSLCommunicationgetContext in interface SSLCommunicationpublic void setAutoHandshake(boolean on)
SSLCommunicationIf 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 SSLCommunicationon - true if handshake should start automatically, false otherwiseSSLCommunication.startHandshake()public java.security.cert.X509Certificate[] getPeerCertificateChain()
SSLCommunicationIn 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 SSLCommunicationpublic java.lang.String getPSKIdentity()
null if no PSK cipher suite is used for
the communication.getPSKIdentity in interface TLSCommunicationnull if no PSK cipher
suite is used for the communicationpublic int getActiveProtocolVersion()
SSLCommunicationgetActiveProtocolVersion in interface SSLCommunicationSSLContextpublic CipherSuite getActiveCipherSuite()
SSLCommunicationgetActiveCipherSuite in interface SSLCommunicationCipherSuitepublic CompressionMethod getActiveCompressionMethod()
SSLCommunicationgetActiveCompressionMethod in interface SSLCommunicationCompressionMethodpublic CipherSuiteList getPeerSupportedCipherSuiteList()
SSLCommunicationgetPeerSupportedCipherSuiteList in interface SSLCommunicationCipherSuite,
SSLCommunication.getActiveCipherSuite()public CompressionMethod[] getPeerSupportedCompressionMethods()
SSLCommunicationgetPeerSupportedCipherSuiteList(), see there with
the exception of the SSLv2 case. As there are no compression
in SSLv2 the empty array is returned.getPeerSupportedCompressionMethods in interface SSLCommunicationCompressionMethod,
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 TLSCommunicationnull
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 TLSCommunicationnull
if no extensions are usedpublic Session getSession()
SSLCommunicationgetSession in interface SSLCommunicationpublic ChannelBindings getChannelBindings()
getChannelBindings in interface TLSCommunicationnull 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
SSLCommunicationgetSession().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 SSLCommunicationjava.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 TLS13CommunicationpostHandshakeConfig - 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
SSLCommunicationThis 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 SSLCommunicationjava.io.IOException - if an error occurs during the handshake procedureSSLCommunication.setAutoHandshake(boolean)public java.io.OutputStream getOutputStream()
throws java.io.IOException
SSLCommunicationgetOutputStream in interface SSLCommunicationgetOutputStream in class java.net.Socketjava.io.IOException - if an error occurs when creating the output streampublic java.io.InputStream getInputStream()
throws java.io.IOException
SSLCommunicationgetInputStream in interface SSLCommunicationgetInputStream in class java.net.Socketjava.io.IOException - if an error occurs when creating the input stream.public void setDebugStream(java.io.Writer writer)
SSLCommunicationsetDebugStream in interface SSLCommunicationwriter - the Writer to which debug information shall be writtenpublic void setDebugStream(java.io.OutputStream os)
SSLCommunicationsetDebugStream in interface SSLCommunicationos - the OutputStream to which debug information shall be writtenpublic void shutdown()
throws java.io.IOException
SSLCommunicationA SSL layer shutdown occurs in the following cases:
shutdown in interface SSLCommunicationjava.io.IOException - if an I/O error occurs when closing this SSLSocketpublic void close()
throws java.io.IOException
SSLCommunicationThis 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 SSLCommunicationclose in interface java.io.Closeableclose in interface java.lang.AutoCloseableclose in class java.net.Socketjava.io.IOExceptionpublic CipherSuite[] getClientSupportedCipherSuites()
public CompressionMethod[] getClientSupportedCompressionMethods()
public boolean isServer()
public java.net.InetAddress getInetAddress()
getInetAddress in class java.net.Socketpublic java.net.InetAddress getLocalAddress()
getLocalAddress in class java.net.Socketpublic int getPort()
getPort in class java.net.Socketpublic int getLocalPort()
getLocalPort in class java.net.Socketpublic void setTcpNoDelay(boolean on)
throws java.net.SocketException
setTcpNoDelay in class java.net.Socketjava.net.SocketExceptionpublic boolean getTcpNoDelay()
throws java.net.SocketException
getTcpNoDelay in class java.net.Socketjava.net.SocketExceptionpublic void setSoLinger(boolean on,
int val)
throws java.net.SocketException
setSoLinger in class java.net.Socketjava.net.SocketExceptionpublic int getSoLinger()
throws java.net.SocketException
getSoLinger in class java.net.Socketjava.net.SocketExceptionpublic void setSoTimeout(int timeout)
throws java.net.SocketException
setSoTimeout in class java.net.Socketjava.net.SocketExceptionpublic int getSoTimeout()
throws java.net.SocketException
getSoTimeout in class java.net.Socketjava.net.SocketExceptionpublic final void shutdownInput()
throws java.io.IOException
shutdownInput in class java.net.Socketjava.lang.UnsupportedOperationExceptionjava.io.IOExceptionpublic final void shutdownOutput()
throws java.io.IOException
shutdownOutput in class java.net.Socketjava.lang.UnsupportedOperationExceptionjava.io.IOException