Package org.mozilla.jss.ssl.javax
Class JSSSocket
java.lang.Object
java.net.Socket
javax.net.ssl.SSLSocket
org.mozilla.jss.ssl.javax.JSSSocket
- All Implemented Interfaces:
Closeable
,AutoCloseable
SSL-enabled socket following the javax.net.ssl.SSLSocket interface.
Most users will want to use the JSSSocketFactory provided by the Java
Provider interface instead of using this class directly.
This SSLSocket implementation is a wrapped implementation. In particular, we
need to consume an existing Socket (via the consumeSocket(...) call) which
we actually send data over. When called from a socket factory, this
additional socket will be automatically created for the caller. This
is necessary because SSLSocketFactory includes a mode which wraps an
existing socket.
All JSSSocket instances have a underlying SocketChannel, of type
JSSSocketChannel. Notably lacking is a javax.net.ssl.SSLSocketChannel type,
so JSSSocketChannel includes no additional SSL-specific options. However,
the core of the SSLEngine wrapping logic exists there.
In order to interoperate with JSSEngine, many of the adjacent methods have
been included in this class as well.
This socket can either be a client or a server, depending on how it was
created. For more information, see the javax.net.ssl.SSLSocket
documentation.
To construct a (useful) new instance, the following calls must be made:
- new JSSSocket();
- consumeSocket(inst);
- initSSLEngine(...);
- setKeyManagers(...);
- setTrustManagers(...);
Optionally, setSSLContext(...) could be called to provide the SSLContext
from which the SSLEngine should be constructed. This should be called prior
to initSSLEngine(...) being called.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
Whether or not to automatically close the underlying Socket when this socket has been closed; defaults to true.private JSSSocketChannel
Underlying SocketChannel for this socket; always exists.private boolean
Whether or not this socket has been closed.private InputStream
Previously consumed data, if any; utilized for certain SSLSocketFactory calls.private JSSEngine
JSSEngine instance to utilize for SSLEngine operations.private String
Name of the SSLEngine provider to use.private String
Name of the SSLEngine protocol to use.private ArrayList
<HandshakeCompletedListener> All registered handshake callbacks.private SSLContext
SSLContext to use to create the JSSEngine.private Socket
The socket this JSSSocket was created over; all read/write operations go through this socket and all information exposed via Socket members go through here. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
Add a callback to fire on handshake completion.void
bind
(SocketAddress bindpoint) void
close()
void
connect
(SocketAddress endpoint) void
connect
(SocketAddress endpoint, int timeout) void
consumeSocket
(Socket parent) Consume a parent socket, utilizing it for all read/write operations.private void
Internal helper to perform the handshake operation, blocking.boolean
Get the autoClose status of this socket, that is, whether or not its parent socket will be automatically closed.Get the underlying SocketChannel for this Socket.String[]
Get the set of enabled cipher suites for this SSLSocket.String[]
Get the set of enabled protocol versions for this SSLSocket.boolean
Get whether or not this SSLSocket enables creation of new sessions.Get the underlying JSSEngine instance.Get the initial session constructed during handshaking.Get a copy of an input stream for this Socket.protected JSSSocketChannel
Helper to always return the channel for this socket, initializing it if it isn't yet created.boolean
Collection
<? extends EventListener> Gets the current list of event listeners this SSLSocket will fire on certain events.int
boolean
Get whether or not this SSLSocket needs client authentication.boolean
<T> T
getOption
(SocketOption<T> name) Get a copy of an output stream for this Socket.int
getPort()
int
boolean
int
Get the established session for this SSLSocket.int
int
protected SSLContext
Get the SSLContext if one exists or create a new instance.Get the configuration of this SSLSocket as a JSSParameters object.String[]
Get the set of supported cipher suites for this SSLSocket.String[]
Get the set of supported protocol versions for this SSLSocket.boolean
int
boolean
Get whether or not this SSLSocket is handshaking as a client.boolean
Get whether or not this SSLSocket wants client authentication.private void
init()
Initialize the underlying SocketChannel.void
Explicitly initialize the SSLEngine with no session resumption information.void
initEngine
(String host, int port) Explicitly initialize the SSLEngine with information for session resumption, including peer's hostname and port.boolean
isBound()
boolean
isClosed()
boolean
boolean
boolean
protected void
Internal helper to fire callbacks on handshake completion.void
Remove a callback from firing on handshake completion.void
sendUrgentData
(int data) void
setAutoClose
(boolean on) Set the autoClose status of this socket, that is, whether or not its parent socket will be automatically closed.void
setCertFromAlias
(String alias) Set the certificate this SSLSocket will utilize from an alias in the NSS DB.void
setConsumedData
(InputStream consumed) Helper to inform this socket of data already consumed from the wrapped socket.void
setEnabledCipherSuites
(String[] suites) Set the list of enabled cipher suites for this SSLSocket.void
setEnabledProtocols
(String[] protocols) Set the list of enabled protocol versions for this SSLSocket.void
setEnableSessionCreation
(boolean enabled) Set whether or not this SSLSocket enables creation of new sessions.void
setHostname
(String name) Set the hostname this client socket is connecting to, for HTTPS TLS certificate validation purposes.void
setKeepAlive
(boolean on) void
Set the KeyManager this SSLSocket will utilize to select a key.void
setKeyManagers
(X509KeyManager[] xkms) Set the key managers this SSLSocket will utilize to select a key.void
setKeyMaterials
(PK11Cert ourCert, PK11PrivKey ourKey) Set the certificate this SSLSocket will utilize from a certificate and its matching private key.void
setListeners
(Collection<? extends EventListener> listeners) Set the listeners this SSLSocket will fire on certain events.void
setNeedClientAuth
(boolean need) Set whether or not this SSLSocket needs client authentication.void
setOOBInline
(boolean on) <T> Socket
setOption
(SocketOption<T> name, T value) void
setPerformancePreferences
(int connectionTime, int latency, int bandwidth) void
setReceiveBufferSize
(int size) void
setReuseAddress
(boolean on) void
setSendBufferSize
(int size) void
setSoLinger
(boolean on, int linger) void
setSoTimeout
(int timeout) void
setSSLContext
(SSLContext ctx) Explicitly set the SSLContext utilized by this JSSSocket instance.void
setSSLParameters
(SSLParameters params) Set the configuration of this SSLSocket from the given SSLParameters instance.void
setTcpNoDelay
(boolean on) void
setTrafficClass
(int tc) void
Set the trust manager this SSLSocket will utilize to validate a peer's certificate.void
setTrustManagers
(X509TrustManager[] xtms) Set the trust managers this SSLSocket will utilize to validate a peer's certificate.void
setUseClientMode
(boolean client) Set whether or not this SSLSocket is handshaking as a client.void
setWantClientAuth
(boolean want) Set whether or not this SSLSocket wants client authentication.void
void
void
Begin a handshake, blocking to completion; this will begin a new handshake when one has already been issued.Set
<SocketOption<?>> toString()
Methods inherited from class javax.net.ssl.SSLSocket
getApplicationProtocol, getHandshakeApplicationProtocol, getHandshakeApplicationProtocolSelector, setHandshakeApplicationProtocolSelector
Methods inherited from class java.net.Socket
setSocketImplFactory
-
Field Details
-
engineProviderProtocol
Name of the SSLEngine protocol to use. -
engineProvider
Name of the SSLEngine provider to use. -
jssContext
SSLContext to use to create the JSSEngine. Note that JSSSocket will fail if the context doesn't create JSSEngine instances. -
engine
JSSEngine instance to utilize for SSLEngine operations. -
handshakeCallbacks
All registered handshake callbacks. -
parent
The socket this JSSSocket was created over; all read/write operations go through this socket and all information exposed via Socket members go through here. -
consumedData
Previously consumed data, if any; utilized for certain SSLSocketFactory calls. -
channel
Underlying SocketChannel for this socket; always exists. -
autoClose
private boolean autoCloseWhether or not to automatically close the underlying Socket when this socket has been closed; defaults to true. -
closed
private boolean closedWhether or not this socket has been closed.
-
-
Constructor Details
-
JSSSocket
public JSSSocket()Start building a new JSSSocket. We specifically avoid creating any other constructors as we wish to consume an existing socket rather than creating a new one.
-
-
Method Details
-
consumeSocket
Consume a parent socket, utilizing it for all read/write operations. This JSSSocket instance will inherit all information about the connection from this underlying socket. When utilized in a JSSSocket, callers should refrain from interacting with the underlying socket directly until the TLS connection is closed. Otherwise, messages may get dropped.- Throws:
IOException
-
getSSLContext
Get the SSLContext if one exists or create a new instance. This is used by initSSLEngine(..) to create the underlying SSLEngine.- Throws:
IOException
-
setSSLContext
Explicitly set the SSLContext utilized by this JSSSocket instance. This enables JSSServerSocket to copy its SSLContext over to the accepted JSSSocket. -
init
Initialize the underlying SocketChannel.- Throws:
IOException
-
initEngine
Explicitly initialize the SSLEngine with no session resumption information.- Throws:
IOException
-
initEngine
Explicitly initialize the SSLEngine with information for session resumption, including peer's hostname and port.- Throws:
IOException
-
getEngine
Get the underlying JSSEngine instance. Note that, just like accessing the underlying Socket instance while the JSSSocket instance is still open is dangerous, performing other TLS operations directly via JSSEngine is also dangerous. This is mostly exposed to enable advanced configuration of the JSSEngine that isn't otherwise allowed by JSSSocket, and to facilitate the accept() method on JSSServerSocket. -
getChannel
Get the underlying SocketChannel for this Socket.- Overrides:
getChannel
in classSocket
- See Also:
-
getInternalChannel
Helper to always return the channel for this socket, initializing it if it isn't yet created. -
getInputStream
Get a copy of an input stream for this Socket.- Overrides:
getInputStream
in classSocket
- Throws:
IOException
- See Also:
-
getOutputStream
Get a copy of an output stream for this Socket.- Overrides:
getOutputStream
in classSocket
- Throws:
IOException
- See Also:
-
doHandshake
Internal helper to perform the handshake operation, blocking. Note that JSSSocket doesn't invoke JSSEngine.wrap/unwrap directly; instead everything is contained within JSSSocketChannel.- Throws:
IOException
-
setConsumedData
Helper to inform this socket of data already consumed from the wrapped socket. This is provided to facilitate a SSLSocketFactory call which allows construction of SSLSocket instances from a non-SSL ServerSocket, allowing the application to check SNI information directly. -
getAutoClose
public boolean getAutoClose()Get the autoClose status of this socket, that is, whether or not its parent socket will be automatically closed. -
setAutoClose
public void setAutoClose(boolean on) Set the autoClose status of this socket, that is, whether or not its parent socket will be automatically closed. -
setHostname
Set the hostname this client socket is connecting to, for HTTPS TLS certificate validation purposes.- See Also:
-
setCertFromAlias
Set the certificate this SSLSocket will utilize from an alias in the NSS DB.- Throws:
IllegalArgumentException
- See Also:
-
setKeyMaterials
Set the certificate this SSLSocket will utilize from a certificate and its matching private key.- Throws:
IllegalArgumentException
- See Also:
-
setKeyManager
Set the KeyManager this SSLSocket will utilize to select a key.- See Also:
-
setKeyManagers
Set the key managers this SSLSocket will utilize to select a key.- See Also:
-
setTrustManager
Set the trust manager this SSLSocket will utilize to validate a peer's certificate.- See Also:
-
setTrustManagers
Set the trust managers this SSLSocket will utilize to validate a peer's certificate.- See Also:
-
setListeners
Set the listeners this SSLSocket will fire on certain events.- See Also:
-
getListeners
Gets the current list of event listeners this SSLSocket will fire on certain events.- See Also:
-
startHandshake
Begin a handshake, blocking to completion; this will begin a new handshake when one has already been issued.- Specified by:
startHandshake
in classSSLSocket
- Throws:
IOException
- See Also:
-
addHandshakeCompletedListener
public void addHandshakeCompletedListener(HandshakeCompletedListener callback) throws IllegalArgumentException Add a callback to fire on handshake completion.- Specified by:
addHandshakeCompletedListener
in classSSLSocket
- Throws:
IllegalArgumentException
- See Also:
-
notifyHandshakeCompletedListeners
protected void notifyHandshakeCompletedListeners()Internal helper to fire callbacks on handshake completion. -
removeHandshakeCompletedListener
public void removeHandshakeCompletedListener(HandshakeCompletedListener callback) throws IllegalArgumentException Remove a callback from firing on handshake completion.- Specified by:
removeHandshakeCompletedListener
in classSSLSocket
- Throws:
IllegalArgumentException
- See Also:
-
getEnabledCipherSuites
Get the set of enabled cipher suites for this SSLSocket.- Specified by:
getEnabledCipherSuites
in classSSLSocket
- See Also:
-
getSupportedCipherSuites
Get the set of supported cipher suites for this SSLSocket.- Specified by:
getSupportedCipherSuites
in classSSLSocket
- See Also:
-
setEnabledCipherSuites
Set the list of enabled cipher suites for this SSLSocket.- Specified by:
setEnabledCipherSuites
in classSSLSocket
- See Also:
-
getEnabledProtocols
Get the set of enabled protocol versions for this SSLSocket.- Specified by:
getEnabledProtocols
in classSSLSocket
- See Also:
-
getSupportedProtocols
Get the set of supported protocol versions for this SSLSocket.- Specified by:
getSupportedProtocols
in classSSLSocket
- See Also:
-
setEnabledProtocols
Set the list of enabled protocol versions for this SSLSocket.- Specified by:
setEnabledProtocols
in classSSLSocket
- See Also:
-
getEnableSessionCreation
public boolean getEnableSessionCreation()Get whether or not this SSLSocket enables creation of new sessions.- Specified by:
getEnableSessionCreation
in classSSLSocket
- See Also:
-
setEnableSessionCreation
public void setEnableSessionCreation(boolean enabled) Set whether or not this SSLSocket enables creation of new sessions.- Specified by:
setEnableSessionCreation
in classSSLSocket
- See Also:
-
getHandshakeSession
Get the initial session constructed during handshaking.- Overrides:
getHandshakeSession
in classSSLSocket
- See Also:
-
getSession
Get the established session for this SSLSocket.- Specified by:
getSession
in classSSLSocket
- See Also:
-
getUseClientMode
public boolean getUseClientMode()Get whether or not this SSLSocket is handshaking as a client.- Specified by:
getUseClientMode
in classSSLSocket
- See Also:
-
setUseClientMode
public void setUseClientMode(boolean client) Set whether or not this SSLSocket is handshaking as a client.- Specified by:
setUseClientMode
in classSSLSocket
- See Also:
-
getWantClientAuth
public boolean getWantClientAuth()Get whether or not this SSLSocket wants client authentication.- Specified by:
getWantClientAuth
in classSSLSocket
- See Also:
-
setWantClientAuth
public void setWantClientAuth(boolean want) Set whether or not this SSLSocket wants client authentication.- Specified by:
setWantClientAuth
in classSSLSocket
- See Also:
-
getNeedClientAuth
public boolean getNeedClientAuth()Get whether or not this SSLSocket needs client authentication.- Specified by:
getNeedClientAuth
in classSSLSocket
- See Also:
-
setNeedClientAuth
public void setNeedClientAuth(boolean need) Set whether or not this SSLSocket needs client authentication.- Specified by:
setNeedClientAuth
in classSSLSocket
- See Also:
-
getSSLParameters
Get the configuration of this SSLSocket as a JSSParameters object.- Overrides:
getSSLParameters
in classSSLSocket
- See Also:
-
setSSLParameters
Set the configuration of this SSLSocket from the given SSLParameters instance.- Overrides:
setSSLParameters
in classSSLSocket
- See Also:
-
connect
- Overrides:
connect
in classSocket
- Throws:
IOException
-
connect
- Overrides:
connect
in classSocket
- Throws:
IOException
-
bind
- Overrides:
bind
in classSocket
- Throws:
IOException
-
close
- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Overrides:
close
in classSocket
- Throws:
IOException
-
shutdownInput
- Overrides:
shutdownInput
in classSocket
- Throws:
IOException
-
shutdownOutput
- Overrides:
shutdownOutput
in classSocket
- Throws:
IOException
-
getInetAddress
- Overrides:
getInetAddress
in classSocket
-
getLocalAddress
- Overrides:
getLocalAddress
in classSocket
-
getPort
public int getPort() -
getLocalPort
public int getLocalPort()- Overrides:
getLocalPort
in classSocket
-
getLocalSocketAddress
- Overrides:
getLocalSocketAddress
in classSocket
-
getRemoteSocketAddress
- Overrides:
getRemoteSocketAddress
in classSocket
-
getTcpNoDelay
- Overrides:
getTcpNoDelay
in classSocket
- Throws:
SocketException
-
setTcpNoDelay
- Overrides:
setTcpNoDelay
in classSocket
- Throws:
SocketException
-
getSoLinger
- Overrides:
getSoLinger
in classSocket
- Throws:
SocketException
-
setSoLinger
- Overrides:
setSoLinger
in classSocket
- Throws:
SocketException
-
getSoTimeout
- Overrides:
getSoTimeout
in classSocket
- Throws:
SocketException
-
setSoTimeout
- Overrides:
setSoTimeout
in classSocket
- Throws:
SocketException
-
getOOBInline
- Overrides:
getOOBInline
in classSocket
- Throws:
SocketException
-
setOOBInline
- Overrides:
setOOBInline
in classSocket
- Throws:
SocketException
-
sendUrgentData
- Overrides:
sendUrgentData
in classSocket
- Throws:
IOException
-
getSendBufferSize
- Overrides:
getSendBufferSize
in classSocket
- Throws:
SocketException
-
setSendBufferSize
- Overrides:
setSendBufferSize
in classSocket
- Throws:
SocketException
-
getReceiveBufferSize
- Overrides:
getReceiveBufferSize
in classSocket
- Throws:
SocketException
-
setReceiveBufferSize
- Overrides:
setReceiveBufferSize
in classSocket
- Throws:
SocketException
-
getKeepAlive
- Overrides:
getKeepAlive
in classSocket
- Throws:
SocketException
-
setKeepAlive
- Overrides:
setKeepAlive
in classSocket
- Throws:
SocketException
-
getTrafficClass
- Overrides:
getTrafficClass
in classSocket
- Throws:
SocketException
-
setTrafficClass
- Overrides:
setTrafficClass
in classSocket
- Throws:
SocketException
-
getReuseAddress
- Overrides:
getReuseAddress
in classSocket
- Throws:
SocketException
-
setReuseAddress
- Overrides:
setReuseAddress
in classSocket
- Throws:
SocketException
-
isConnected
public boolean isConnected()- Overrides:
isConnected
in classSocket
-
isBound
public boolean isBound() -
isClosed
public boolean isClosed() -
isInputShutdown
public boolean isInputShutdown()- Overrides:
isInputShutdown
in classSocket
-
isOutputShutdown
public boolean isOutputShutdown()- Overrides:
isOutputShutdown
in classSocket
-
setPerformancePreferences
public void setPerformancePreferences(int connectionTime, int latency, int bandwidth) - Overrides:
setPerformancePreferences
in classSocket
-
toString
-
setOption
- Overrides:
setOption
in classSocket
- Throws:
IOException
-
getOption
- Overrides:
getOption
in classSocket
- Throws:
IOException
-
supportedOptions
- Overrides:
supportedOptions
in classSocket
-