Package io.netty.handler.ssl

Class SslContextBuilder

  • public final class SslContextBuilder
extends java.lang.Object
    Builder for configuring a new SslContext for creation.

    • Method Detail

      • 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:
        keyManager(File, File)

      • 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:
        keyManager(InputStream, InputStream)

      • 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:
        keyManager(PrivateKey, X509Certificate[])

      • 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:
        keyManager(File, File, String)

      • 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:
        keyManager(InputStream, InputStream, String)

      • 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
        keyCertChain - the X.509 certificate chain
        keyPassword - the password of the keyFile, or null if it's not password-protected
        See Also:
        keyManager(File, File, String)

      • 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
        keyCertChain - the X.509 certificate chain
        keyPassword - the password of the keyFile, or null if it's not password-protected
        See Also:
        keyManager(File, File, String)

      • 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

      • 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.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.

      • 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.

      • 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.

      • 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