Class SslContextBuilder

java.lang.Object
io.netty.handler.ssl.SslContextBuilder
public final class SslContextBuilder extends java.lang.Object
Builder for configuring a new SslContext for creation.

  • Field Details

    • EMPTY_ENTRIES

      private static final java.util.Map.Entry[] EMPTY_ENTRIES

    • forServer

      private final boolean forServer

    • provider

      private SslProvider provider

    • sslContextProvider

      private java.security.Provider sslContextProvider

    • trustCertCollection

      private java.security.cert.X509Certificate[] trustCertCollection

    • trustManagerFactory

      private javax.net.ssl.TrustManagerFactory trustManagerFactory

    • keyCertChain

      private java.security.cert.X509Certificate[] keyCertChain

    • key

      private java.security.PrivateKey key

    • keyPassword

      private java.lang.String keyPassword

    • keyManagerFactory

      private javax.net.ssl.KeyManagerFactory keyManagerFactory

    • credentials

      private java.util.List<OpenSslCredential> credentials

    • ciphers

      private java.lang.Iterable<java.lang.String> ciphers

    • cipherFilter

      private CipherSuiteFilter cipherFilter

    • apn

      private ApplicationProtocolConfig apn

    • sessionCacheSize

      private long sessionCacheSize

    • sessionTimeout

      private long sessionTimeout

    • clientAuth

      private ClientAuth clientAuth

    • protocols

      private java.lang.String[] protocols

    • startTls

      private boolean startTls

    • enableOcsp

      private boolean enableOcsp

    • secureRandom

      private java.security.SecureRandom secureRandom

    • keyStoreType

      private java.lang.String keyStoreType

    • endpointIdentificationAlgorithm

      private java.lang.String endpointIdentificationAlgorithm

    • options

      private final java.util.Map<SslContextOption<?>, java.lang.Object> options

    • serverNames

      private final java.util.List<javax.net.ssl.SNIServerName> serverNames

  • Constructor Details

    • SslContextBuilder

      private SslContextBuilder(boolean forServer)

  • Method Details

    • forClient

      public static SslContextBuilder forClient()
      Creates a builder for new client-side SslContext.

    • forServer

      public static SslContextBuilder forServer(java.io.File keyCertChainFile, java.io.File keyFile)
      Creates a builder for new server-side SslContext.
      Parameters:
      keyCertChainFile - an X.509 certificate chain file in PEM format
      keyFile - a PKCS#8 private key file in PEM format
      See Also:

    • forServer

      public static SslContextBuilder forServer(java.io.InputStream keyCertChainInputStream, java.io.InputStream keyInputStream)
      Creates a builder for new server-side SslContext.
      Parameters:
      keyCertChainInputStream - an input stream for an X.509 certificate chain in PEM format. The caller is responsible for calling InputStream.close() after build() has been called.
      keyInputStream - an input stream for a PKCS#8 private key in PEM format. The caller is responsible for calling InputStream.close() after build() has been called.
      See Also:

    • forServer

      public static SslContextBuilder forServer(java.security.PrivateKey key, java.security.cert.X509Certificate... keyCertChain)
      Creates a builder for new server-side SslContext.
      Parameters:
      key - a PKCS#8 private key
      keyCertChain - the X.509 certificate chain
      See Also:

    • forServer

      public static SslContextBuilder forServer(java.security.PrivateKey key, java.lang.Iterable<? extends java.security.cert.X509Certificate> keyCertChain)
      Creates a builder for new server-side SslContext.
      Parameters:
      key - a PKCS#8 private key
      keyCertChain - the X.509 certificate chain
      See Also:

    • forServer

      public static SslContextBuilder forServer(java.io.File keyCertChainFile, java.io.File keyFile, java.lang.String keyPassword)
      Creates a builder for new server-side SslContext.
      Parameters:
      keyCertChainFile - an X.509 certificate chain file in PEM format
      keyFile - a PKCS#8 private key file in PEM format
      keyPassword - the password of the keyFile, or null if it's not password-protected
      See Also:

    • forServer

      public static SslContextBuilder forServer(java.io.InputStream keyCertChainInputStream, java.io.InputStream keyInputStream, java.lang.String keyPassword)
      Creates a builder for new server-side SslContext.
      Parameters:
      keyCertChainInputStream - an input stream for an X.509 certificate chain in PEM format. The caller is responsible for calling InputStream.close() after build() has been called.
      keyInputStream - an input stream for a PKCS#8 private key in PEM format. The caller is responsible for calling InputStream.close() after build() has been called.
      keyPassword - the password of the keyFile, or null if it's not password-protected
      See Also:

    • forServer

      public static SslContextBuilder forServer(java.security.PrivateKey key, java.lang.String keyPassword, java.security.cert.X509Certificate... keyCertChain)
      Creates a builder for new server-side SslContext.
      Parameters:
      key - a PKCS#8 private key
      keyPassword - the password of the keyFile, or null if it's not password-protected
      keyCertChain - the X.509 certificate chain
      See Also:

    • forServer

      public static SslContextBuilder forServer(java.security.PrivateKey key, java.lang.String keyPassword, java.lang.Iterable<? extends java.security.cert.X509Certificate> keyCertChain)
      Creates a builder for new server-side SslContext.
      Parameters:
      key - a PKCS#8 private key
      keyPassword - the password of the keyFile, or null if it's not password-protected
      keyCertChain - the X.509 certificate chain
      See Also:

    • forServer

      public static SslContextBuilder forServer(javax.net.ssl.KeyManagerFactory keyManagerFactory)
      Creates a builder for new server-side SslContext.

      If you use SslProvider.OPENSSL or SslProvider.OPENSSL_REFCNT consider using OpenSslX509KeyManagerFactory or OpenSslCachingX509KeyManagerFactory.

      Parameters:
      keyManagerFactory - non-null factory for server's private key
      See Also:

    • forServer

      public static SslContextBuilder forServer(javax.net.ssl.KeyManager keyManager)
      Creates a builder for new server-side SslContext with KeyManager.
      Parameters:
      keyManager - non-null KeyManager for server's private key

    • option

      public <T> SslContextBuilder option(SslContextOption<T> option, T value)
      Configure a SslContextOption.

    • sslProvider

      public SslContextBuilder sslProvider(SslProvider provider)
      The SslContext implementation to use. null uses the default one.

    • keyStoreType

      public SslContextBuilder keyStoreType(java.lang.String keyStoreType)
      Sets the KeyStore type that should be used. null uses the default one.

    • sslContextProvider

      public SslContextBuilder sslContextProvider(java.security.Provider sslContextProvider)
      The SSLContext Provider to use. null uses the default one. This is only used with SslProvider.JDK.

    • trustManager

      public SslContextBuilder trustManager(java.io.File trustCertCollectionFile)
      Trusted certificates for verifying the remote endpoint's certificate. The file should contain an X.509 certificate collection in PEM format. null uses the system default.

    • trustManager

      public SslContextBuilder trustManager(java.io.InputStream trustCertCollectionInputStream)
      Trusted certificates for verifying the remote endpoint's certificate. The input stream should contain an X.509 certificate collection in PEM format. null uses the system default.

      The caller is responsible for calling InputStream.close() after build() has been called.

    • trustManager

      public SslContextBuilder trustManager(java.security.cert.X509Certificate... trustCertCollection)
      Trusted certificates for verifying the remote endpoint's certificate, null uses the system default.

    • trustManager

      public SslContextBuilder trustManager(java.lang.Iterable<? extends java.security.cert.X509Certificate> trustCertCollection)
      Trusted certificates for verifying the remote endpoint's certificate, null uses the system default.

    • trustManager

      public SslContextBuilder trustManager(javax.net.ssl.TrustManagerFactory trustManagerFactory)
      Trusted manager for verifying the remote endpoint's certificate. null uses the system default.

    • trustManager

      public SslContextBuilder trustManager(javax.net.ssl.TrustManager trustManager)
      A single trusted manager for verifying the remote endpoint's certificate. This is helpful when custom implementation of TrustManager is needed. Internally, a simple wrapper of TrustManagerFactory that only produces this specified TrustManager will be created, thus all the requirements specified in trustManager(TrustManagerFactory trustManagerFactory) also apply here.

    • keyManager

      public SslContextBuilder keyManager(java.io.File keyCertChainFile, java.io.File keyFile)
      Identifying certificate for this host. keyCertChainFile and keyFile may be null for client contexts, which disables mutual authentication.
      Parameters:
      keyCertChainFile - an X.509 certificate chain file in PEM format
      keyFile - a PKCS#8 private key file in PEM format

    • keyManager

      public SslContextBuilder keyManager(java.io.InputStream keyCertChainInputStream, java.io.InputStream keyInputStream)
      Identifying certificate for this host. keyCertChainInputStream and keyInputStream may be null for client contexts, which disables mutual authentication.
      Parameters:
      keyCertChainInputStream - an input stream for an X.509 certificate chain in PEM format. The caller is responsible for calling InputStream.close() after build() has been called.
      keyInputStream - an input stream for a PKCS#8 private key in PEM format. The caller is responsible for calling InputStream.close() after build() has been called.

    • keyManager

      public SslContextBuilder keyManager(java.security.PrivateKey key, java.security.cert.X509Certificate... keyCertChain)
      Identifying certificate for this host. keyCertChain and key may be null for client contexts, which disables mutual authentication.
      Parameters:
      key - a PKCS#8 private key
      keyCertChain - an X.509 certificate chain

    • keyManager

      public SslContextBuilder keyManager(java.security.PrivateKey key, java.lang.Iterable<? extends java.security.cert.X509Certificate> keyCertChain)
      Identifying certificate for this host. keyCertChain and key may be null for client contexts, which disables mutual authentication.
      Parameters:
      key - a PKCS#8 private key
      keyCertChain - an X.509 certificate chain

    • keyManager

      public SslContextBuilder keyManager(java.io.File keyCertChainFile, java.io.File keyFile, java.lang.String keyPassword)
      Identifying certificate for this host. keyCertChainFile and keyFile may be null for client contexts, which disables mutual authentication.
      Parameters:
      keyCertChainFile - an X.509 certificate chain file in PEM format
      keyFile - a PKCS#8 private key file in PEM format
      keyPassword - the password of the keyFile, or null if it's not password-protected

    • keyManager

      public SslContextBuilder keyManager(java.io.InputStream keyCertChainInputStream, java.io.InputStream keyInputStream, java.lang.String keyPassword)
      Identifying certificate for this host. keyCertChainInputStream and keyInputStream may be null for client contexts, which disables mutual authentication.
      Parameters:
      keyCertChainInputStream - an input stream for an X.509 certificate chain in PEM format. The caller is responsible for calling InputStream.close() after build() has been called.
      keyInputStream - an input stream for a PKCS#8 private key in PEM format. The caller is responsible for calling InputStream.close() after build() has been called.
      keyPassword - the password of the keyInputStream, or null if it's not password-protected

    • keyManager

      public SslContextBuilder keyManager(java.security.PrivateKey key, java.lang.String keyPassword, java.security.cert.X509Certificate... keyCertChain)
      Identifying certificate for this host. keyCertChain and key may be null for client contexts, which disables mutual authentication.
      Parameters:
      key - a PKCS#8 private key file
      keyPassword - the password of the key, or null if it's not password-protected
      keyCertChain - an X.509 certificate chain

    • keyManager

      public SslContextBuilder keyManager(java.security.PrivateKey key, java.lang.String keyPassword, java.lang.Iterable<? extends java.security.cert.X509Certificate> keyCertChain)
      Identifying certificate for this host. keyCertChain and key may be null for client contexts, which disables mutual authentication.
      Parameters:
      key - a PKCS#8 private key file
      keyPassword - the password of the key, or null if it's not password-protected
      keyCertChain - an X.509 certificate chain

    • keyManager

      public SslContextBuilder keyManager(javax.net.ssl.KeyManagerFactory keyManagerFactory)
      Identifying manager for this host. keyManagerFactory may be null for client contexts, which disables mutual authentication. Using a KeyManagerFactory is only supported for SslProvider.JDK or SslProvider.OPENSSL / SslProvider.OPENSSL_REFCNT if the used openssl version is 1.0.1+. You can check if your openssl version supports using a KeyManagerFactory by calling OpenSsl.supportsKeyManagerFactory(). If this is not the case you must use keyManager(File, File) or keyManager(File, File, String).

      If you use SslProvider.OPENSSL or SslProvider.OPENSSL_REFCNT consider using OpenSslX509KeyManagerFactory or OpenSslCachingX509KeyManagerFactory.

    • addCredential

      public SslContextBuilder addCredential(OpenSslCredential credential)
      Adds a single OpenSslCredential to this context.

      This is useful for multi-certificate scenarios, such as serving both RSA and ECDSA certificates to support different client capabilities.

      Credential instances are built with the OpenSslCredentialBuilder.

      This is a BoringSSL-specific feature and only works with SslProvider.OPENSSL or SslProvider.OPENSSL_REFCNT. Check OpenSslCredential.isAvailable() to verify that the feature is supported.

      Lifetime: this builder does not retain the credential. The caller must ensure the credential remains alive (refcount > 0) until build() returns. build() will retain its own reference via the constructed SslContext.

      Parameters:
      credential - the credential to add
      Returns:
      this builder for chaining
      See Also:

    • addCredentials

      public SslContextBuilder addCredentials(OpenSslCredential... credentials)
      Adds multiple OpenSslCredentials to this context.

      This is useful for multi-certificate scenarios, such as serving both RSA and ECDSA certificates to support different client capabilities.

      Credential instances are built with the OpenSslCredentialBuilder.

      This is a BoringSSL-specific feature and only works with SslProvider.OPENSSL or SslProvider.OPENSSL_REFCNT. Check OpenSslCredential.isAvailable() to verify that the feature is supported.

      Parameters:
      credentials - the credentials to add
      Returns:
      this builder for chaining
      See Also:

    • addCredentials

      public SslContextBuilder addCredentials(java.lang.Iterable<? extends OpenSslCredential> credentials)
      Adds multiple OpenSslCredentials to this context.

      This is useful for multi-certificate scenarios, such as serving both RSA and ECDSA certificates to support different client capabilities.

      Credential instances are built with the OpenSslCredentialBuilder.

      This is a BoringSSL-specific feature and only works with SslProvider.OPENSSL or SslProvider.OPENSSL_REFCNT. Check OpenSslCredential.isAvailable() to verify that the feature is supported.

      Parameters:
      credentials - the credentials to add
      Returns:
      this builder for chaining
      See Also:

    • keyManager

      public SslContextBuilder keyManager(javax.net.ssl.KeyManager keyManager)
      A single key manager managing the identity information of this host. This is helpful when custom implementation of KeyManager is needed. Internally, a wrapper of KeyManagerFactory that only produces this specified KeyManager will be created, thus all the requirements specified in keyManager(KeyManagerFactory keyManagerFactory) also apply here.

    • ciphers

      public SslContextBuilder ciphers(java.lang.Iterable<java.lang.String> ciphers)
      The cipher suites to enable, in the order of preference. null to use default cipher suites.

    • ciphers

      public SslContextBuilder ciphers(java.lang.Iterable<java.lang.String> ciphers, CipherSuiteFilter cipherFilter)
      The cipher suites to enable, in the order of preference. cipherFilter will be applied to the ciphers before use. If ciphers is null, then the default cipher suites will be used.

    • applicationProtocolConfig

      public SslContextBuilder applicationProtocolConfig(ApplicationProtocolConfig apn)
      Application protocol negotiation configuration. null disables support.

    • sessionCacheSize

      public SslContextBuilder sessionCacheSize(long sessionCacheSize)
      Set the size of the cache used for storing SSL session objects. 0 to use the default value.

    • sessionTimeout

      public SslContextBuilder sessionTimeout(long sessionTimeout)
      Set the timeout for the cached SSL session objects, in seconds. 0 to use the default value.

    • clientAuth

      public SslContextBuilder clientAuth(ClientAuth clientAuth)
      Sets the client authentication mode.

    • protocols

      public SslContextBuilder protocols(java.lang.String... protocols)
      The TLS protocol versions to enable.
      Parameters:
      protocols - The protocols to enable, or null to enable the default protocols.
      See Also:
      • SSLEngine.setEnabledCipherSuites(String[])

    • protocols

      public SslContextBuilder protocols(java.lang.Iterable<java.lang.String> protocols)
      The TLS protocol versions to enable.
      Parameters:
      protocols - The protocols to enable, or null to enable the default protocols.
      See Also:
      • SSLEngine.setEnabledCipherSuites(String[])

    • startTls

      public SslContextBuilder startTls(boolean startTls)
      true if the first write request shouldn't be encrypted.

    • enableOcsp

      @UnstableApi public SslContextBuilder enableOcsp(boolean enableOcsp)
      Enables OCSP stapling. Please note that not all SslProvider implementations support OCSP stapling and an exception will be thrown upon build().
      See Also:

    • secureRandom

      public SslContextBuilder secureRandom(java.security.SecureRandom secureRandom)
      Specify a non-default source of randomness for the JdkSslContext

      In general, the best practice is to leave this unspecified, or to assign a new random source using the default new SecureRandom() constructor. Only assign this something when you have a good reason to.

      Parameters:
      secureRandom - the source of randomness for JdkSslContext

    • endpointIdentificationAlgorithm

      public SslContextBuilder endpointIdentificationAlgorithm(java.lang.String algorithm)
      Specify the endpoint identification algorithm (aka. hostname verification algorithm) that clients will use as part of authenticating servers.

      See Java Security Standard Names for a list of supported algorithms.

      Parameters:
      algorithm - either "HTTPS", "LDAPS", or null (disables hostname verification).
      See Also:
      • SSLParameters.setEndpointIdentificationAlgorithm(String)

    • serverName

      public SslContextBuilder serverName(javax.net.ssl.SNIServerName serverName)
      Add the given server name indication to this client context. This will cause the client to include a Server Name Indication extension with its ClientHello message, as per RFC 6066 section 3.

      Note that only one name per name type can be included in the message. Currently, only the SNIHostName type is supported.

      Parameters:
      serverName - The server name to include in the SNI extension.

    • build

      public SslContext build() throws javax.net.ssl.SSLException
      Create new SslContext instance with configured settings.

      If sslProvider(SslProvider) is set to SslProvider.OPENSSL_REFCNT then the caller is responsible for releasing this object, or else native memory may leak.

      Throws:
      javax.net.ssl.SSLException

    • toArray

      private static <T> T[] toArray(java.lang.Iterable<? extends T> iterable, T[] prototype)