Interface SslSocketConfigurator (2.2.0) 

public interface SslSocketConfigurator

A callback interface allowing users to programmatically configure active SSLSocket parameters (e.g., named groups, cipher suites, application protocols) before the TLS handshake starts.

Exposing this hook allows users to customize advanced TLS capabilities that are not configurable via standard JVM system properties, or require custom security provider APIs (e.g., Conscrypt or BouncyCastle). Typical use cases include:

  • Enabling Post-Quantum Cryptography (PQC) hybrid curves (e.g., X25519MLKEM768).
  • Configuring Application-Layer Protocol Negotiation (ALPN) for HTTP/2.
  • Restricting cipher suites or protocol versions dynamically based on environment.

JDK Version and Provider Compatibility Matrix for PQC

  • JDK 27+: PQC algorithms are supported natively by default. No custom configurator or security provider is required.
  • JDK 20-26: Callers can configure named groups natively using standard JRE JSSE APIs (via SSLParameters.setNamedGroups(String[])), as shown in the JDK 20+ example below.
  • JDK 8-19: The standard JRE does not expose APIs to set named groups. Callers must register a custom security provider (like Conscrypt JNI or BouncyCastle) and configure sockets using the provider-specific APIs demonstrated in the examples below.

Conscrypt Configuration Example


 builder.setSslSocketConfigurator(new SslSocketConfigurator() {
   @Override
   public void configure(SSLSocket socket) {
     if (org.conscrypt.Conscrypt.isConscrypt(socket)) {
       org.conscrypt.Conscrypt.setNamedGroups(socket, new String[] {"X25519MLKEM768", "X25519"});
     }
   }
 });

BouncyCastle Configuration Example


 builder.setSslSocketConfigurator(new SslSocketConfigurator() {
   @Override
   public void configure(SSLSocket socket) {
     if (socket instanceof org.bouncycastle.jsse.BCSSLSocket) {
       org.bouncycastle.jsse.BCSSLSocket bcSocket = (org.bouncycastle.jsse.BCSSLSocket) socket;
       org.bouncycastle.jsse.BCSSLParameters bcParams = bcSocket.getParameters();
       bcParams.setNamedGroups(new String[] {"X25519MLKEM768", "X25519"});
       bcSocket.setParameters(bcParams);
     }
   }
 });

JDK 20+ Standard JSSE Configuration Example

Note: This example requires compilation and runtime environment running JDK 20+.


 builder.setSslSocketConfigurator(new SslSocketConfigurator() {
   @Override
   public void configure(SSLSocket socket) {
     javax.net.ssl.SSLParameters parameters = socket.getSSLParameters();
     parameters.setNamedGroups(new String[] {"X25519MLKEM768", "X25519"});
     socket.setSSLParameters(parameters);
   }
 });

Methods

configure(SSLSocket sslSocket)

public abstract void configure(SSLSocket sslSocket)

Configures the active TLS socket parameters before the handshake starts.

Parameter
Name Description
sslSocket SSLSocket

the newly created SSLSocket connection