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
public abstract class JSSEngine extends SSLEngine
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 Details

    • logger

      public static org.slf4j.Logger logger

    • BUFFER_SIZE

      protected static int BUFFER_SIZE
      Size 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_server
      Whether or not this SSLEngine is acting as the client end of the handshake.

    • hostname

      protected String hostname
      Peer's hostname, used for certificate validation.

    • certAlias

      protected String certAlias
      Certificate alias used by the JSSEngine instance.

    • cert

      protected PK11Cert 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

      protected PK11PrivKey key
      Key corresponding to the local certificate.

    • key_managers

      protected X509KeyManager[] 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

      protected X509TrustManager[] 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_auth
      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. See also the note for want_client_auth.

    • want_client_auth

      protected boolean want_client_auth
      Whether 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

      protected SSLEngineResult.HandshakeStatus 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

      protected SSLCipher[] 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

      protected SSLVersion min_protocol
      The minimum TLS protocol version we should attempt to handshake. This version is tempered by local policy, when applicable.

    • max_protocol

      protected SSLVersion max_protocol
      The maximum TLS protocol version we should attempt to handshake. This version is tempered by local policy, when applicable.

    • session

      protected JSSSession session
      A JSSSession extends the SSLSession, providing useful information not otherwise contained in the SSLSession, but exposed by NSS.

    • ssl_fd

      protected SSLFDProxy 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_closed
      Whether or not the outbound portion of this connection is closed.

    • is_inbound_closed

      protected boolean is_inbound_closed
      Whether or not the inbound portion of this connection is closed.

    • config

      protected HashMap<Integer,Integer> config
      Set of configuration options to enable via SSL_OptionSet(...).

    • serverTemplates

      protected static HashMap<PK11Cert,SSLFDProxy> serverTemplates
      Set of cached server sockets based on the PK11Cert they were initialized with.

    • sessionCacheInitialized

      private static final AtomicBoolean 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

      private Collection<? extends EventListener> 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

      public JSSEngine(String peerHost, int peerPort)
      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

      public 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. This should always be called from an implementation's corresponding constructor.

  • Method Details

    • errorText

      protected static String errorText(int error)
      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

      public SSLFDProxy 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

      public JSSParameters 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 class SSLEngine

    • setSSLParameters

      public void setSSLParameters(SSLParameters params)
      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 class SSLEngine

    • setHostname

      public void setHostname(String name)
      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

      public void setCertFromAlias(String alias) throws IllegalArgumentException
      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

      public void setEnabledCipherSuites(String[] suites) throws IllegalArgumentException
      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 class SSLEngine
      Throws:
      IllegalArgumentException

    • setEnabledCipherSuites

      public void setEnabledCipherSuites(SSLCipher[] suites) throws IllegalArgumentException
      Sets the list of enabled cipher suites from a a list of SSLCipher enum instances.
      Throws:
      IllegalArgumentException

    • queryEnabledCipherSuites

      public static SSLCipher[] queryEnabledCipherSuites()
      Queries the list of cipher suites enabled by default, if a corresponding setEnabledCIpherSuites call hasn't yet been made.

    • getEnabledCipherSuites

      public String[] getEnabledCipherSuites()
      Lists cipher suites currently enabled on this JSSEngine instance.
      Specified by:
      getEnabledCipherSuites in class SSLEngine

    • getSupportedCipherSuites

      public String[] 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 class SSLEngine

    • setEnabledProtocols

      public void setEnabledProtocols(String[] protocols) throws IllegalArgumentException
      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 class SSLEngine
      Throws:
      IllegalArgumentException

    • setEnabledProtocols

      public void setEnabledProtocols(SSLVersion min, SSLVersion max) throws IllegalArgumentException
      Sets the range of enabled SSL Protocols from a minimum and maximum SSLVersion value.
      Throws:
      IllegalArgumentException

    • setEnabledProtocols

      public void setEnabledProtocols(SSLVersionRange vrange)
      Sets the range of enabled SSL Protocols from a SSLVersionRange object.

    • queryEnabledProtocols

      public static SSLVersionRange queryEnabledProtocols()
      Queries the list of protocols enabled by default. Only used when setEnabledProtocols(...) hasn't yet been called.

    • getEnabledProtocols

      public String[] 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 class SSLEngine

    • getSupportedProtocols

      public String[] getSupportedProtocols()
      Gets the list of SSL protocols supported, as a list of JCA-standardized strings.
      Specified by:
      getSupportedProtocols in class SSLEngine

    • setKeyMaterials

      public void setKeyMaterials(PK11Cert our_cert, PK11PrivKey our_key) throws IllegalArgumentException
      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

      public void setKeyManager(X509KeyManager km)
      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

      public void setKeyManagers(X509KeyManager[] xkms)
      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

      public void setTrustManager(JSSTrustManager tm)
      Set the internal TrustManager, when present, replacing all previous TrustManagers.

    • setTrustManagers

      public void setTrustManagers(X509TrustManager[] xtms)
      Set the internal list of TrustManagers.

    • getSession

      public JSSSession getSession()
      Gets the JSSSession object which reflects the status of this JSS Engine's session.
      Specified by:
      getSession in class SSLEngine

    • 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 class SSLEngine

    • getEnableSessionCreation

      public boolean getEnableSessionCreation()
      Whether or not new sessions can be created by this SSLEngine instance. This always returns true.
      Specified by:
      getEnableSessionCreation in class SSLEngine

    • setUseClientMode

      public void setUseClientMode(boolean mode) throws IllegalArgumentException
      Set whether or not to handshake as a client.
      Specified by:
      setUseClientMode in class SSLEngine
      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 class SSLEngine

    • setWantClientAuth

      public void setWantClientAuth(boolean want)
      Set whether or not we should attempt client authentication.
      Specified by:
      setWantClientAuth in class SSLEngine

    • 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 class SSLEngine

    • getNeedClientAuth

      public boolean getNeedClientAuth()
      Query whether or not we must have client authentication for the TLS handshake to succeed.
      Specified by:
      getNeedClientAuth in class SSLEngine

    • getWantClientAuth

      public boolean getWantClientAuth()
      Query whether or not we request client authentication.
      Specified by:
      getWantClientAuth in class SSLEngine

    • setListeners

      public void setListeners(Collection<? extends EventListener> new_listeners)
      Sets a SSLSocketListener on this object.

    • getListeners

      public Collection<? extends EventListener> getListeners()
      Gets the set of SSLSocketListeners on this object.

    • fireAlertReceived

      protected void fireAlertReceived(SSLAlertEvent event)
      Fires any and all SSLSocketListeners on the specified alert received event. To be used by other implementations of JSSEngine.

    • fireAlertSent

      protected void fireAlertSent(SSLAlertEvent event)
      Fires any and all SSLSocketListeners on the specified alert sent event. To be used by other implementations of JSSEngine.

    • fireHandshakeComplete

      protected void fireHandshakeComplete(SSLHandshakeCompletedEvent event)
      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 class SSLEngine

    • isOutboundDone

      public boolean isOutboundDone()
      Query whether or not the outbound side of this connection is closed.
      Specified by:
      isOutboundDone in class SSLEngine

    • getStatus

      public abstract SecurityStatusResult 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

      public HashMap<Integer,Integer> 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

      public void setConfiguration(HashMap<Integer,Integer> config)
      Sets the configuration, replacing all current values.

    • getServerTemplate

      protected static SSLFDProxy getServerTemplate(PK11Cert cert, PK11PrivKey key)
      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.