Package org.mozilla.jss.ssl.javax
Class JSSEngine
java.lang.Object
javax.net.ssl.SSLEngine
org.mozilla.jss.ssl.javax.JSSEngine
- Direct Known Subclasses:
JSSEngineReferenceImpl
JSS's SSLEngine base class for alternative implementations.
This abstracts out many components for all JSS SSLEngine implementations,
such as cipher suite support, SSLSession creation, and various other
common functions. This allows alternative SSLEngine implementations to
focus on two main things: wrap/unwrap and init.
There are the following implementations:
- JSSEngineReferenceImpl - A reference implementation with extensive
logging and debugging.
Usually a JSSEngine isn't constructed directly, but instead accessed via
the Provider mechanism, SSLContext. See JSSContextSpi for more information.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected boolean
Whether or not this SSLEngine is acting as the client end of the handshake.protected static int
Size of the underlying BUFFERs.protected PK11Cert
Certificate used by this JSSEngine instance.protected String
Certificate alias used by the JSSEngine instance.Set of configuration options to enable via SSL_OptionSet(...).protected SSLCipher[]
A list of all ciphers enabled by this SSLEngine.protected SSLEngineResult.HandshakeStatus
What the official SSLEngineResult handshake status is, at the present time.protected String
Peer's hostname, used for certificate validation.protected boolean
Whether or not the inbound portion of this connection is closed.protected boolean
Whether or not the outbound portion of this connection is closed.protected PK11PrivKey
Key corresponding to the local certificate.protected X509KeyManager[]
A list of all KeyManagers available to this JSSEngine instance.private Collection
<? extends EventListener> Set of listeners to fire on events (SSL alerts, handshake completed).static org.slf4j.Logger
protected SSLVersion
The maximum TLS protocol version we should attempt to handshake.protected SSLVersion
The minimum TLS protocol version we should attempt to handshake.protected boolean
Whether or not we should fail to handshake if client authentication is not passed by the peer and we are a server; if we are a client, whether or not we offer our certificate to the server.protected static HashMap
<PK11Cert, SSLFDProxy> Set of cached server sockets based on the PK11Cert they were initialized with.protected JSSSession
A JSSSession extends the SSLSession, providing useful information not otherwise contained in the SSLSession, but exposed by NSS.private static final AtomicBoolean
Whether or not the session cache has been initialized already.protected SSLFDProxy
Internal SSLFDProxy instance; useful for JSSSession support and any custom extensions the developer wishes to support.protected X509TrustManager[]
A list of all TrustManagers available to this JSSEngine instance.protected boolean
Whether or not we should attempt to handshake with client authentication. -
Constructor Summary
ConstructorsConstructorDescriptionConstructor for a JSSEngine, providing no hints for an internal session reuse strategy and no key.Constructor for a JSSEngine, providing hints for an internal session reuse strategy (the peer's hostname and port), but no local cert or key.JSSEngine
(String peerHost, int peerPort, X509Certificate localCert, PrivateKey localKey) Constructor for a JSSEngine, providing hints for an internal session reuse strategy (the peer's hostname and port), along with a chosen certificate and key to use. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addConfiguration
(int key, int value) Updates the configuration with the given value.abstract void
cleanup()
Performs cleanup of internal data, closing both inbound and outbound data streams if still open.protected static String
errorText
(int error) Gets the error text from the NSPR layerprotected void
fireAlertReceived
(SSLAlertEvent event) Fires any and all SSLSocketListeners on the specified alert received event.protected void
fireAlertSent
(SSLAlertEvent event) Fires any and all SSLSocketListeners on the specified alert sent event.protected void
Fires any and all SSLHandshakeCompletedListener on the specified event.Gets the default configuration.String[]
Lists cipher suites currently enabled on this JSSEngine instance.String[]
Gets the list of enabled SSL protocol versions on this particular JSSEngine instance, as a list of JCA-standardized strings.boolean
Whether or not new sessions can be created by this SSLEngine instance.Collection
<? extends EventListener> Gets the set of SSLSocketListeners on this object.boolean
Query whether or not we must have client authentication for the TLS handshake to succeed.protected static SSLFDProxy
getServerTemplate
(PK11Cert cert, PK11PrivKey key) Returns the templated server certificate, if one exists.Gets the JSSSession object which reflects the status of this JSS Engine's session.Get the internal SSLFDProxy object; this should be preferred to directly accessing ssl_fd.Get the configuration from the current JSSEngine object as a JSSParameters object.abstract SecurityStatusResult
Gets the current security status of this JSSEngine instance.String[]
Lists all cipher suites supported by JSS/NSS.String[]
Gets the list of SSL protocols supported, as a list of JCA-standardized strings.boolean
Query whether this JSSEngine is a client (true) or a server (false).boolean
Query whether or not we request client authentication.static void
initializeSessionCache
(int maxCacheEntries, long timeout, String directory) Safely initializes the session cache if not already initialized.boolean
Query whether or not the inbound side of this connection is closed.boolean
Query whether or not the outbound side of this connection is closed.static SSLCipher[]
Queries the list of cipher suites enabled by default, if a corresponding setEnabledCIpherSuites call hasn't yet been made.static SSLVersionRange
Queries the list of protocols enabled by default.protected abstract void
Implementation-specific handler to handle reconfiguration of client authentication after the handshake has completed.void
removeConfiguration
(int key) Removes the given key from the configuration.void
setCertFromAlias
(String alias) Choose a certificate to give to the peer from the specified alias, assuming KeyManagers have already been specified and at least one is a JSSKeyManager.void
setConfiguration
(HashMap<Integer, Integer> config) Sets the configuration, replacing all current values.void
setEnabledCipherSuites
(String[] suites) Sets the list of enabled cipher suites from a list of JCA-approved String names.void
setEnabledCipherSuites
(SSLCipher[] suites) Sets the list of enabled cipher suites from a a list of SSLCipher enum instances.void
setEnabledProtocols
(String[] protocols) Set the range of SSL protocols enabled by this SSLEngine instance, from a list of JCA-standardized protocol String names.void
setEnabledProtocols
(SSLVersionRange vrange) Sets the range of enabled SSL Protocols from a SSLVersionRange object.void
setEnabledProtocols
(SSLVersion min, SSLVersion max) Sets the range of enabled SSL Protocols from a minimum and maximum SSLVersion value.void
setEnableSessionCreation
(boolean flag) Whether or not to enable this SSLEngine instance to create new sessions.void
setHostname
(String name) Set the hostname used to validate the peer's certificate.void
Set the internal KeyManager, when present, replacing all previous KeyManagers.void
setKeyManagers
(X509KeyManager[] xkms) Set the internal list of KeyManagers.void
setKeyMaterials
(PK11Cert our_cert, PK11PrivKey our_key) Set public and protected key material; useful when doing client auth or if this wasn't provided to the constructor.void
setListeners
(Collection<? extends EventListener> new_listeners) Sets a SSLSocketListener on this object.void
setNeedClientAuth
(boolean need) Set whether or not client authentication is required for the TLS handshake to succeed.void
setSSLParameters
(SSLParameters params) Set the configuration from the given SSLParameters object onto this JSSEngine.void
Set the internal TrustManager, when present, replacing all previous TrustManagers.void
setTrustManagers
(X509TrustManager[] xtms) Set the internal list of TrustManagers.void
setUseClientMode
(boolean mode) Set whether or not to handshake as a client.void
setWantClientAuth
(boolean want) Set whether or not we should attempt client authentication.abstract void
Calls cleanup only if both inbound and outbound data streams are closed.Methods inherited from class javax.net.ssl.SSLEngine
beginHandshake, closeInbound, closeOutbound, getApplicationProtocol, getDelegatedTask, getHandshakeApplicationProtocol, getHandshakeApplicationProtocolSelector, getHandshakeSession, getHandshakeStatus, getPeerHost, getPeerPort, setHandshakeApplicationProtocolSelector, unwrap, unwrap, unwrap, wrap, wrap, wrap
-
Field Details
-
logger
public static org.slf4j.Logger logger -
BUFFER_SIZE
protected static int BUFFER_SIZESize of the underlying BUFFERs. Helps to be large enough to fit well-formed SSL packets during the initial handshake and subsequent data transfer. See MAX_ENCRYPTED_PACKET_LENGTH calculation from Tomcat's org.apache.tomcat.util.net.openssl.OpenSSLEngine. -
as_server
protected boolean as_serverWhether or not this SSLEngine is acting as the client end of the handshake. -
hostname
Peer's hostname, used for certificate validation. -
certAlias
Certificate alias used by the JSSEngine instance. -
cert
Certificate used by this JSSEngine instance. Selected and inferred from the KeyManagers passed, when not passed explicitly (either during construction or with a call to setKeyMaterials(...)). -
key
Key corresponding to the local certificate. -
key_managers
A list of all KeyManagers available to this JSSEngine instance. Note: currently only a single JSSKeyManager instance is exposed, and it can only handle finding a single certificate by nickname. In the future, more KeyManagers should be supported. -
trust_managers
A list of all TrustManagers available to this JSSEngine instance. The behavior of this list depends on how which TrustManagers are passed. -
need_client_auth
protected boolean need_client_authWhether or not we should fail to handshake if client authentication is not passed by the peer and we are a server; if we are a client, whether or not we offer our certificate to the server. See also the note for want_client_auth. -
want_client_auth
protected boolean want_client_authWhether or not we should attempt to handshake with client authentication. Note that under a strict reading of the SSLEngine spec, this is mutually exclusive with need_client_auth: either want_client_auth or need_client_auth can be true, but not both. However, both can be false. Under NSS semantics however, we have control over two values: whether we offer/request client auth, and whether we should fail to handshake if we don't get client auth. This doesn't quite map onto the want/need semantics, but it is what we have available. -
handshake_state
What the official SSLEngineResult handshake status is, at the present time. Note that while we store the current handshake state in JSSEngine, we don't implement getHandshakeStatus(...), as different JSSEngine implementations could have different implementations for that method. -
enabled_ciphers
A list of all ciphers enabled by this SSLEngine. This list is restricted to a list of ciphers that are supported and approved by local policy. -
min_protocol
The minimum TLS protocol version we should attempt to handshake. This version is tempered by local policy, when applicable. -
max_protocol
The maximum TLS protocol version we should attempt to handshake. This version is tempered by local policy, when applicable. -
session
A JSSSession extends the SSLSession, providing useful information not otherwise contained in the SSLSession, but exposed by NSS. -
ssl_fd
Internal SSLFDProxy instance; useful for JSSSession support and any custom extensions the developer wishes to support. -
is_outbound_closed
protected boolean is_outbound_closedWhether or not the outbound portion of this connection is closed. -
is_inbound_closed
protected boolean is_inbound_closedWhether or not the inbound portion of this connection is closed. -
config
Set of configuration options to enable via SSL_OptionSet(...). -
serverTemplates
Set of cached server sockets based on the PK11Cert they were initialized with. -
sessionCacheInitialized
Whether or not the session cache has been initialized already. A session cache must always be created in order to utilize a server-side JSSEngine. However, NSS isn't threadsafe when creating such a cache, so synchronize it within JSSEngine. -
listeners
Set of listeners to fire on events (SSL alerts, handshake completed).
-
-
Constructor Details
-
JSSEngine
public JSSEngine()Constructor for a JSSEngine, providing no hints for an internal session reuse strategy and no key. This should always be called from an implementation's corresponding constructor. -
JSSEngine
Constructor for a JSSEngine, providing hints for an internal session reuse strategy (the peer's hostname and port), but no local cert or key. This should always be called from an implementation's corresponding constructor. -
JSSEngine
Constructor for a JSSEngine, providing hints for an internal session reuse strategy (the peer's hostname and port), along with a chosen certificate and key to use. This should always be called from an implementation's corresponding constructor.
-
-
Method Details
-
errorText
Gets the error text from the NSPR layer -
initializeSessionCache
public static void initializeSessionCache(int maxCacheEntries, long timeout, String directory) throws SSLException Safely initializes the session cache if not already initialized.- Throws:
SSLException
-
getSSLFDProxy
Get the internal SSLFDProxy object; this should be preferred to directly accessing ssl_fd. Note that ssl_fd can be null at various times during SSLEngine initialization and destruction. This method should be used with caution as callers can risk damaging the SSLEngine and making it unusable or crash. -
getSSLParameters
Get the configuration from the current JSSEngine object as a JSSParameters object. This populates the following values, when set: - cipher suites - protocols - need/want client auth - certificate alias - peer's hostname - ALPN protocols- Overrides:
getSSLParameters
in classSSLEngine
-
setSSLParameters
Set the configuration from the given SSLParameters object onto this JSSEngine. Aligning with the parent implementation, this calls: - setEnabledCipherSuites when getCipherSuites is non-null, - setEnabledProtocols when getProtocols is non-null, - setListeners when getListeners is non-null, and - setWantClientAuth and setNeedClientAuth. This doesn't yet understand from the parent implementation, the following calls: - getServerNames for the local server certificate selection, and - getSNIMatchers for configuring SNI selection criteria Unlike the parent, this also understands: - setCertFromAlias when getAlias is non-null, - setHostname when getHostname is non-null. Note: this implementation overrides the one in SSLEngine so that we create a JSSParameters object from the passed SSLParameters (if it is not already an instance of JSSParameters), simplifying the other function calls and reducing duplicate parsing.- Overrides:
setSSLParameters
in classSSLEngine
-
setHostname
Set the hostname used to validate the peer's certificate. This is usually passed to NSS via a call to NSS's ill-named SSL_SetURL(...), which really takes a hostname. Note: if this isn't called (and no peerHost was specified via a constructor), NSS will accept any host name provided by the server! Only useful for validating the server certificate; not used when validating the peer's certificate. -
setCertFromAlias
Choose a certificate to give to the peer from the specified alias, assuming KeyManagers have already been specified and at least one is a JSSKeyManager. When alias is null, this clears all previous certs and keys. If no KeyManagers have been specified, raises an IllegalArgumentException stating as much.- Throws:
IllegalArgumentException
-
setEnabledCipherSuites
Sets the list of enabled cipher suites from a list of JCA-approved String names. Note: this method is slower than creating a JSSParameters configuration object and calling setSSLParameters(...) with it. This call must construct its own JSSParameters instance internally and translate between JCA String names and SSLCipher instances.- Specified by:
setEnabledCipherSuites
in classSSLEngine
- Throws:
IllegalArgumentException
-
setEnabledCipherSuites
Sets the list of enabled cipher suites from a a list of SSLCipher enum instances.- Throws:
IllegalArgumentException
-
queryEnabledCipherSuites
Queries the list of cipher suites enabled by default, if a corresponding setEnabledCIpherSuites call hasn't yet been made. -
getEnabledCipherSuites
Lists cipher suites currently enabled on this JSSEngine instance.- Specified by:
getEnabledCipherSuites
in classSSLEngine
-
getSupportedCipherSuites
Lists all cipher suites supported by JSS/NSS. Note that this list isn't just all values in SSLCipher: it is only those which are supported and allowed by local policy.- Specified by:
getSupportedCipherSuites
in classSSLEngine
-
setEnabledProtocols
Set the range of SSL protocols enabled by this SSLEngine instance, from a list of JCA-standardized protocol String names. Note that this enables all protocols in the range of min(protocols) to max(protocols), inclusive due to the underlying call to NSS's SSL_VersionRangeSet(...). It is also recommend to construct your own JSSParameters object first and pass it to setSSLParameters(...), rather than calling this method directly.- Specified by:
setEnabledProtocols
in classSSLEngine
- Throws:
IllegalArgumentException
-
setEnabledProtocols
Sets the range of enabled SSL Protocols from a minimum and maximum SSLVersion value.- Throws:
IllegalArgumentException
-
setEnabledProtocols
Sets the range of enabled SSL Protocols from a SSLVersionRange object. -
queryEnabledProtocols
Queries the list of protocols enabled by default. Only used when setEnabledProtocols(...) hasn't yet been called. -
getEnabledProtocols
Gets the list of enabled SSL protocol versions on this particular JSSEngine instance, as a list of JCA-standardized strings.- Specified by:
getEnabledProtocols
in classSSLEngine
-
getSupportedProtocols
Gets the list of SSL protocols supported, as a list of JCA-standardized strings.- Specified by:
getSupportedProtocols
in classSSLEngine
-
setKeyMaterials
Set public and protected key material; useful when doing client auth or if this wasn't provided to the constructor. Can also be used to remove key material; however note that both arguments must match: either both certificate and key are null or both are not-null.- Throws:
IllegalArgumentException
-
setKeyManager
Set the internal KeyManager, when present, replacing all previous KeyManagers. It is suggested that at least one key manager be a JSSKeyManager instance if a key and certificate must be provided for this end of the connection. -
setKeyManagers
Set the internal list of KeyManagers. It is suggested that at least one key manager be a JSSKeyManager instance if a key and certificate must be provided for this end of the connection. -
setTrustManager
Set the internal TrustManager, when present, replacing all previous TrustManagers. -
setTrustManagers
Set the internal list of TrustManagers. -
getSession
Gets the JSSSession object which reflects the status of this JSS Engine's session.- Specified by:
getSession
in classSSLEngine
-
setEnableSessionCreation
public void setEnableSessionCreation(boolean flag) Whether or not to enable this SSLEngine instance to create new sessions. The default value is true. When passed the value false, this will throw a RuntimeException, stating that all JSS Engines do not support restricting to only resuming existing sessions.- Specified by:
setEnableSessionCreation
in classSSLEngine
-
getEnableSessionCreation
public boolean getEnableSessionCreation()Whether or not new sessions can be created by this SSLEngine instance. This always returns true.- Specified by:
getEnableSessionCreation
in classSSLEngine
-
setUseClientMode
Set whether or not to handshake as a client.- Specified by:
setUseClientMode
in classSSLEngine
- Throws:
IllegalArgumentException
-
setNeedClientAuth
public void setNeedClientAuth(boolean need) Set whether or not client authentication is required for the TLS handshake to succeed.- Specified by:
setNeedClientAuth
in classSSLEngine
-
setWantClientAuth
public void setWantClientAuth(boolean want) Set whether or not we should attempt client authentication.- Specified by:
setWantClientAuth
in classSSLEngine
-
reconfigureClientAuth
protected abstract void reconfigureClientAuth()Implementation-specific handler to handle reconfiguration of client authentication after the handshake has completed. Note that this always gets called, regardless of if the handshake has started; it is up to the implementation to handle this appropriately. -
getUseClientMode
public boolean getUseClientMode()Query whether this JSSEngine is a client (true) or a server (false).- Specified by:
getUseClientMode
in classSSLEngine
-
getNeedClientAuth
public boolean getNeedClientAuth()Query whether or not we must have client authentication for the TLS handshake to succeed.- Specified by:
getNeedClientAuth
in classSSLEngine
-
getWantClientAuth
public boolean getWantClientAuth()Query whether or not we request client authentication.- Specified by:
getWantClientAuth
in classSSLEngine
-
setListeners
Sets a SSLSocketListener on this object. -
getListeners
Gets the set of SSLSocketListeners on this object. -
fireAlertReceived
Fires any and all SSLSocketListeners on the specified alert received event. To be used by other implementations of JSSEngine. -
fireAlertSent
Fires any and all SSLSocketListeners on the specified alert sent event. To be used by other implementations of JSSEngine. -
fireHandshakeComplete
Fires any and all SSLHandshakeCompletedListener on the specified event. To be used by other implementations of JSSEngine. -
isInboundDone
public boolean isInboundDone()Query whether or not the inbound side of this connection is closed.- Specified by:
isInboundDone
in classSSLEngine
-
isOutboundDone
public boolean isOutboundDone()Query whether or not the outbound side of this connection is closed.- Specified by:
isOutboundDone
in classSSLEngine
-
getStatus
Gets the current security status of this JSSEngine instance. This is abstract to allow implementations to implement this (and step their handshake mechanism) as they wish. -
getDefaultConfiguration
Gets the default configuration. -
addConfiguration
public void addConfiguration(int key, int value) Updates the configuration with the given value. -
removeConfiguration
public void removeConfiguration(int key) Removes the given key from the configuration. -
setConfiguration
Sets the configuration, replacing all current values. -
getServerTemplate
Returns the templated server certificate, if one exists. -
tryCleanup
public abstract void tryCleanup()Calls cleanup only if both inbound and outbound data streams are closed. This prevents accidental cleanup in the case of a partially open connection. -
cleanup
public abstract void cleanup()Performs cleanup of internal data, closing both inbound and outbound data streams if still open.
-