SSLContextSpi (Java SE 14 & JDK 14)
Description: declaration: module: java.base, package: javax.net.ssl, class: SSLContextSpi
Keywords: javax.net.ssl.SSLContextSpi class

Module java.base
Package javax.net.ssl

# Class SSLContextSpi

java.lang.Object
javax.net.ssl.SSLContextSpi

    public abstract class SSLContextSpi
    extends Object

This class defines the Service Provider Interface (SPI) for the `SSLContext` class.

All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a particular SSL context.

Since:
  1.4
See Also:
  `SSLContext`

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `SSLContextSpi()` |

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `protected abstract SSLEngine` | `engineCreateSSLEngine()` | Creates a new `SSLEngine` using this context.
  `protected abstract SSLEngine` | `engineCreateSSLEngine​(String host, int port)` | Creates a `SSLEngine` using this context.
  `protected abstract SSLSessionContext` | `engineGetClientSessionContext()` | Returns a client `SSLSessionContext` object for this context.
  `protected SSLParameters` | `engineGetDefaultSSLParameters()` | Returns a copy of the SSLParameters indicating the default settings for this SSL context.
  `protected abstract SSLSessionContext` | `engineGetServerSessionContext()` | Returns a server `SSLSessionContext` object for this context.
  `protected abstract SSLServerSocketFactory` | `engineGetServerSocketFactory()` | Returns a `ServerSocketFactory` object for this context.
  `protected abstract SSLSocketFactory` | `engineGetSocketFactory()` | Returns a `SocketFactory` object for this context.
  `protected SSLParameters` | `engineGetSupportedSSLParameters()` | Returns a copy of the SSLParameters indicating the maximum supported settings for this SSL context.
  `protected abstract void` | `engineInit​(KeyManager[] km, TrustManager[] tm, SecureRandom sr)` | Initializes this context.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### SSLContextSpi

    public SSLContextSpi()

- ## Method Details

  - ### engineInit

    protected abstract void engineInit​(KeyManager[] km, TrustManager[] tm, SecureRandom sr) throws KeyManagementException
    Initializes this context.
    Parameters:
      `km` - the sources of authentication keys
      `tm` - the sources of peer authentication trust decisions
      `sr` - the source of randomness
    Throws:
      `KeyManagementException` - if this operation fails
    See Also:
      `SSLContext.init(KeyManager [], TrustManager [], SecureRandom)`

  - ### engineGetSocketFactory

    protected abstract SSLSocketFactory engineGetSocketFactory()
    Returns a `SocketFactory` object for this context.
    Returns:
      the `SocketFactory` object
    Throws:
      `UnsupportedOperationException` - if the underlying provider does not implement the operation.
      `IllegalStateException` - if the SSLContextImpl requires initialization and the `engineInit()` has not been called
    See Also:
      `SSLContext.getSocketFactory()`

  - ### engineGetServerSocketFactory

    protected abstract SSLServerSocketFactory engineGetServerSocketFactory()
    Returns a `ServerSocketFactory` object for this context.
    Returns:
      the `ServerSocketFactory` object
    Throws:
      `UnsupportedOperationException` - if the underlying provider does not implement the operation.
      `IllegalStateException` - if the SSLContextImpl requires initialization and the `engineInit()` has not been called
    See Also:
      `SSLContext.getServerSocketFactory()`

  - ### engineCreateSSLEngine

    protected abstract SSLEngine engineCreateSSLEngine()
    Creates a new `SSLEngine` using this context.

    Applications using this factory method are providing no hints for an internal session reuse strategy. If hints are desired, `engineCreateSSLEngine(String, int)` should be used instead.

    Some cipher suites (such as Kerberos) require remote hostname information, in which case this factory method should not be used.

    Implementation Note:
      It is provider-specific if the returned SSLEngine uses client or server mode by default for the (D)TLS connection. The JDK SunJSSE provider implementation uses server mode by default. However, it is recommended to always set the desired mode explicitly by calling `SSLEngine.setUseClientMode()` before invoking other methods of the SSLEngine.
    Returns:
      the `SSLEngine` Object
    Throws:
      `IllegalStateException` - if the SSLContextImpl requires initialization and the `engineInit()` has not been called
    Since:
      1.5
    See Also:
      `SSLContext.createSSLEngine()`

  - ### engineCreateSSLEngine

    protected abstract SSLEngine engineCreateSSLEngine​(String host, int port)
    Creates a `SSLEngine` using this context.

    Applications using this factory method are providing hints for an internal session reuse strategy.

    Some cipher suites (such as Kerberos) require remote hostname information, in which case peerHost needs to be specified.

    Implementation Note:
      It is provider-specific if the returned SSLEngine uses client or server mode by default for the (D)TLS connection. The JDK SunJSSE provider implementation uses server mode by default. However, it is recommended to always set the desired mode explicitly by calling `SSLEngine.setUseClientMode()` before invoking other methods of the SSLEngine.
    Parameters:
      `host` - the non-authoritative name of the host
      `port` - the non-authoritative port
    Returns:
      the `SSLEngine` Object
    Throws:
      `IllegalStateException` - if the SSLContextImpl requires initialization and the `engineInit()` has not been called
    Since:
      1.5
    See Also:
      `SSLContext.createSSLEngine(String, int)`

  - ### engineGetServerSessionContext

    protected abstract SSLSessionContext engineGetServerSessionContext()
    Returns a server `SSLSessionContext` object for this context.
    Returns:
      the `SSLSessionContext` object
    See Also:
      `SSLContext.getServerSessionContext()`

  - ### engineGetClientSessionContext

    protected abstract SSLSessionContext engineGetClientSessionContext()
    Returns a client `SSLSessionContext` object for this context.
    Returns:
      the `SSLSessionContext` object
    See Also:
      `SSLContext.getClientSessionContext()`

  - ### engineGetDefaultSSLParameters

    protected SSLParameters engineGetDefaultSSLParameters()
    Returns a copy of the SSLParameters indicating the default settings for this SSL context.

    The parameters will always have the ciphersuite and protocols arrays set to non-null values.

    The default implementation obtains the parameters from an SSLSocket created by calling the SocketFactory.createSocket() method of this context's SocketFactory.

    Returns:
      a copy of the SSLParameters object with the default settings
    Throws:
      `UnsupportedOperationException` - if the default SSL parameters could not be obtained.
    Since:
      1.6

  - ### engineGetSupportedSSLParameters

    protected SSLParameters engineGetSupportedSSLParameters()
    Returns a copy of the SSLParameters indicating the maximum supported settings for this SSL context.

    The parameters will always have the ciphersuite and protocols arrays set to non-null values.

    The default implementation obtains the parameters from an SSLSocket created by calling the SocketFactory.createSocket() method of this context's SocketFactory.

    Returns:
      a copy of the SSLParameters object with the maximum supported settings
    Throws:
      `UnsupportedOperationException` - if the supported SSL parameters could not be obtained.
    Since:
      1.6