RATIS-2638. Add a TLS handshake failure listener by HTHou · Pull Request #1561 · apache/ratis · GitHub

What changes were proposed in this pull request?

Add an optional generic ServerCredentials configuration to ratis-grpc. Applications can register credentials through GrpcConfigKeys.Server.setCredentials(...), and Ratis passes them directly to NettyServerBuilder.forAddress(...). This supports custom credential implementations without specializing the configuration API for one use case.

This pull request also adds TlsHandshakeFailureServerCredentials.create(GrpcTlsConfig, Consumer<TlsHandshakeFailureServerCredentials.Event>) for applications that need to observe inbound gRPC TLS handshake failures. Ratis reports the original cause and the physical local and remote socket addresses. The callback runs on a transport event-loop thread and must not block. Listener failures are isolated from the TLS failure and channel-closing behavior. Ratis does not perform audit logging or require callers to persist the exception; applications may use only the endpoint information when that is sufficient for their audit policy.

The TLS handshake failure credentials wrap the shaded gRPC protocol negotiator inside Ratis. They report TLS and ALPN negotiation failures at most once per physical connection and ignore channel closure without an SSLException. Configured server credentials apply to SERVER, CLIENT, and ADMIN server endpoints, including shared ports. When no credentials are configured, the existing server creation and SslContext paths remain unchanged.

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/RATIS-2638

How was this patch tested?

Added TestRaftServerWithGrpc#testTlsHandshakeFailureListener, which verifies that a valid TLS request does not trigger the listener and that a plaintext connection to the TLS port reports one inbound failure with the expected local and remote addresses.

Also ran:

mvn -pl ratis-test -am -Dtest=TestRaftServerWithGrpc#testTlsHandshakeFailureListener -Dsurefire.failIfNoSpecifiedTests=false test
mvn -B -fae -DskipTests checkstyle:check
mvn -pl ratis-grpc -DskipTests clean compile spotbugs:check

@HTHou , thanks for working on this!

I only have a comment on the conf so far. We should try to make it more general to support any ServerCredentials.

This part of the grpc code is new to me. Will need some time to review the other code.

NettyServerBuilder forAddress(SocketAddress address, ServerCredentials creds)

Since the forAddress parameter is ServerCredentials, let's use ServerCredentials as the class. Then, it will also support other ServerCredentials.

    String CREDENTIALS_PARAMETER = PREFIX + ".credentials";
    Class<ServerCredentials> CREDENTIALS_CLASS = ServerCredentials.class;
    static ServerCredentials credentials(Parameters parameters) {
      return parameters == null ? null
          : parameters.get(CREDENTIALS_PARAMETER, CREDENTIALS_CLASS);
    }
    static void setCredentials(Parameters parameters, ServerCredentials listener) {
      parameters.put(CREDENTIALS_PARAMETER, listener, CREDENTIALS_CLASS);
    }

Thanks for the suggestion. Updated in 058baf3: the parameter now stores a generic ServerCredentials via GrpcConfigKeys.Server.setCredentials(...), and GrpcServicesImpl passes it directly to NettyServerBuilder.forAddress(...). The TLS listener is exposed through TlsHandshakeFailureServerCredentials.create(...), and the test registers that implementation through the generic credentials configuration, so other ServerCredentials implementations are supported as well.

@HTHou , thanks for the update! Please see the comments inlined and also https://issues.apache.org/jira/secure/attachment/13084161/1561_review.patch

Move the LOG to above if-statement.

      if (serverCredentials != null) {
        LOG.info("Setting server credentials for {}", address);
        nettyServerBuilder = NettyServerBuilder.forAddress(address, serverCredentials);
      } else {
        nettyServerBuilder = NettyServerBuilder.forAddress(address);
        if (sslContext != null) {
          LOG.info("Setting sslContext for {}", address);
          nettyServerBuilder.sslContext(sslContext);
        }
      }

Updated in 64ca1d7. The log statements are now inside the corresponding serverCredentials and sslContext branches.

Let's move it as an inner class TlsHandshakeFailureServerCredentials.Event.

Updated in 64ca1d7. The event is now the nested TlsHandshakeFailureServerCredentials.Event, and the standalone event class has been removed.

Let's use Consumer<TlsHandshakeFailureEvent> instead of adding a new interface.

Updated in 64ca1d7. create(...) now accepts Consumer<TlsHandshakeFailureServerCredentials.Event>, and the standalone listener interface has been removed. I kept the non-blocking transport event-loop requirement in the API documentation.

It seems better to pass the executor, instead of the offloadExecutorPool.

Updated in 64ca1d7. Negotiator now passes its acquired executor to ServerTlsHandler, avoiding a second getObject() call while retaining the existing returnObject() lifecycle.

How about using asException()?

Updated in 64ca1d7. The ALPN negotiation failure now uses Status.asException().

It is better to use AtomicBoolean and compareAndSet:

      if (failureReported.compareAndSet(false, true)) {
        return;
      }

Updated in 64ca1d7. failureReported is now an AtomicBoolean. I used if (!failureReported.compareAndSet(false, true)) { return; } so that the first failure reaches the listener and subsequent reports are skipped.

Include the protocol string in the exception:

      final String protocol = sslHandler.applicationProtocol();
      if (!sslContext.applicationProtocolNegotiator().protocols().contains(protocol)) {
        final Exception cause = Status.UNAVAILABLE
            .withDescription("Failed protocol negotiation: Unable to find compatible protocol for " + protocol)

Updated in 64ca1d7. The negotiated protocol is captured and included in the ALPN failure description.

+1 the change looks good.

HTHou force-pushed the codex/RATIS-2638 branch from a2338ec to 49bb081 Compare August 24, 2026 09:30

HTHou changed the title RATIS-2638. Add a TLS handshake failure listener for gRPC servers RATIS-2638. Add a gRPC server builder creation hook Aug 24, 2026

RATIS-2638. Add a TLS handshake failure listener

d16bacd

HTHou force-pushed the codex/RATIS-2638 branch from 49bb081 to d16bacd Compare August 24, 2026 10:44

HTHou changed the title RATIS-2638. Add a gRPC server builder creation hook RATIS-2638. Add a TLS handshake failure listener Aug 24, 2026

szetszwo reviewed Aug 27, 2026

View reviewed changes

RATIS-2638. Support configurable server credentials

058baf3

szetszwo reviewed Aug 27, 2026

View reviewed changes

RATIS-2638. Address TLS handshake listener review comments

64ca1d7

szetszwo approved these changes Aug 28, 2026

View reviewed changes

szetszwo merged commit df1fc70 into apache:master Aug 28, 2026
16 checks passed

HTHou deleted the codex/RATIS-2638 branch August 30, 2026 04:41

+              public interface TlsHandshakeFailureListener {
+                /**
+                 * Invoked on a transport event-loop thread. Implementations must not block and should hand off
+                 * expensive work to another thread.
+                 */
+                void onFailure(TlsHandshakeFailureEvent event);
+              }

+                    final ChannelHandler grpcNegotiationHandler =
+                        InternalProtocolNegotiators.grpcNegotiationHandler(grpcHandler);
+                    final ChannelHandler tlsHandler = new ServerTlsHandler(grpcNegotiationHandler, grpcHandler,
+                        sslContext, listener, offloadExecutorPool);

+                        .contains(sslHandler.applicationProtocol())) {
+                      final RuntimeException cause = Status.UNAVAILABLE
+                          .withDescription("Failed protocol negotiation: Unable to find compatible protocol")
+                          .asRuntimeException();

+                    if (!sslContext.applicationProtocolNegotiator().protocols()
+                        .contains(sslHandler.applicationProtocol())) {
+                      final RuntimeException cause = Status.UNAVAILABLE
+                          .withDescription("Failed protocol negotiation: Unable to find compatible protocol")

+                  String TLS_HANDSHAKE_FAILURE_LISTENER_PARAMETER = PREFIX + ".tls.handshake.failure.listener";
+                  Class<TlsHandshakeFailureListener> TLS_HANDSHAKE_FAILURE_LISTENER_CLASS =
+                      TlsHandshakeFailureListener.class;

+              import java.util.Objects;
+              /** Information about a failed TLS handshake. */
+              public final class TlsHandshakeFailureEvent {

+                    if (failureReported) {
+                      return;
+                    }
+                    failureReported = true;

RATIS-2638. Add a TLS handshake failure listener by HTHou · Pull Request #1561 · apache/ratis · GitHub

Uh oh!

RATIS-2638. Add a TLS handshake failure listener - #1561

RATIS-2638. Add a TLS handshake failure listener#1561szetszwo merged 3 commits intoapache:masterapache/ratis:masterfrom HTHou:codex/RATIS-2638HTHou/ratis:codex/RATIS-2638Copy head branch name to clipboard

Conversation

HTHou commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes were proposed in this pull request?

What is the link to the Apache JIRA

How was this patch tested?

Uh oh!

szetszwo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

szetszwo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

szetszwo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

RATIS-2638. Add a TLS handshake failure listener#1561
szetszwo merged 3 commits into
apache:masterfrom
HTHou:codex/RATIS-2638

HTHou commented Aug 24, 2026 •
edited
Loading