io.netty.handler.ssl

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.

Method Summary

Modifier and Type	Method and Description
SslContextBuilder	applicationProtocolConfig(ApplicationProtocolConfig apn) Application protocol negotiation configuration.
SslContext	build() Create new SslContext instance with configured settings.
SslContextBuilder	ciphers(java.lang.Iterable<java.lang.String> ciphers) The cipher suites to enable, in the order of preference.
SslContextBuilder	ciphers(java.lang.Iterable<java.lang.String> ciphers, CipherSuiteFilter cipherFilter) The cipher suites to enable, in the order of preference.
SslContextBuilder	clientAuth(ClientAuth clientAuth) Sets the client authentication mode.
SslContextBuilder	enableOcsp(boolean enableOcsp) Enables OCSP stapling.
static SslContextBuilder	forClient() Creates a builder for new client-side SslContext.
static SslContextBuilder	forServer(java.io.File keyCertChainFile, java.io.File keyFile) Creates a builder for new server-side SslContext.
static SslContextBuilder	forServer(java.io.File keyCertChainFile, java.io.File keyFile, java.lang.String keyPassword) Creates a builder for new server-side SslContext.
static SslContextBuilder	forServer(java.io.InputStream keyCertChainInputStream, java.io.InputStream keyInputStream) Creates a builder for new server-side SslContext.
static SslContextBuilder	forServer(java.io.InputStream keyCertChainInputStream, java.io.InputStream keyInputStream, java.lang.String keyPassword) Creates a builder for new server-side SslContext.
static SslContextBuilder	forServer(javax.net.ssl.KeyManagerFactory keyManagerFactory) Creates a builder for new server-side SslContext.
static SslContextBuilder	forServer(java.security.PrivateKey key, java.lang.String keyPassword, java.security.cert.X509Certificate... keyCertChain) Creates a builder for new server-side SslContext.
static SslContextBuilder	forServer(java.security.PrivateKey key, java.security.cert.X509Certificate... keyCertChain) Creates a builder for new server-side SslContext.
SslContextBuilder	keyManager(java.io.File keyCertChainFile, java.io.File keyFile) Identifying certificate for this host.
SslContextBuilder	keyManager(java.io.File keyCertChainFile, java.io.File keyFile, java.lang.String keyPassword) Identifying certificate for this host.
SslContextBuilder	keyManager(java.io.InputStream keyCertChainInputStream, java.io.InputStream keyInputStream) Identifying certificate for this host.
SslContextBuilder	keyManager(java.io.InputStream keyCertChainInputStream, java.io.InputStream keyInputStream, java.lang.String keyPassword) Identifying certificate for this host.
SslContextBuilder	keyManager(javax.net.ssl.KeyManagerFactory keyManagerFactory) Identifying manager for this host.
SslContextBuilder	keyManager(java.security.PrivateKey key, java.lang.String keyPassword, java.security.cert.X509Certificate... keyCertChain) Identifying certificate for this host.
SslContextBuilder	keyManager(java.security.PrivateKey key, java.security.cert.X509Certificate... keyCertChain) Identifying certificate for this host.
SslContextBuilder	protocols(java.lang.String... protocols) The TLS protocol versions to enable.
SslContextBuilder	sessionCacheSize(long sessionCacheSize) Set the size of the cache used for storing SSL session objects.
SslContextBuilder	sessionTimeout(long sessionTimeout) Set the timeout for the cached SSL session objects, in seconds.
SslContextBuilder	sslContextProvider(java.security.Provider sslContextProvider) The SSLContext Provider to use.
SslContextBuilder	sslProvider(SslProvider provider) The SslContext implementation to use.
SslContextBuilder	startTls(boolean startTls) true if the first write request shouldn't be encrypted.
SslContextBuilder	trustManager(java.io.File trustCertCollectionFile) Trusted certificates for verifying the remote endpoint's certificate.
SslContextBuilder	trustManager(java.io.InputStream trustCertCollectionInputStream) Trusted certificates for verifying the remote endpoint's certificate.
SslContextBuilder	trustManager(javax.net.ssl.TrustManagerFactory trustManagerFactory) Trusted manager for verifying the remote endpoint's certificate.
SslContextBuilder	trustManager(java.security.cert.X509Certificate... trustCertCollection) Trusted certificates for verifying the remote endpoint's certificate, null uses the system default.

Methods inherited from class java.lang.Object

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

Method Detail

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:

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

keyInputStream - an input stream for a PKCS#8 private key in PEM format

See Also:

keyManager(InputStream, InputStream)

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:

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

keyInputStream - an input stream for a PKCS#8 private key in PEM format

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(javax.net.ssl.KeyManagerFactory keyManagerFactory)

Creates a builder for new server-side SslContext.

Parameters:

keyManagerFactory - non-null factory for server's private key

See Also:

keyManager(KeyManagerFactory)

sslProvider

public SslContextBuilder sslProvider(SslProvider provider)

The SslContext implementation to use. 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.

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(javax.net.ssl.TrustManagerFactory trustManagerFactory)

Trusted manager for verifying the remote endpoint's certificate. null uses the system default.

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

keyInputStream - an input stream for a PKCS#8 private key in PEM format

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

keyInputStream - an input stream for a PKCS#8 private key in PEM format

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(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).

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[])

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:

OpenSsl.isOcspSupported()

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