Propagate error from DotNetty TLS handshake failure to Akka.Remote by Arkatufus · Pull Request #7824 · akkadotnet/akka.net

Arkatufus · 2025-09-15T16:16:20Z

Fixes #7823
Supercedes #7821

Summary

Surface TLS handshake failures from DotNetty in Akka.Remote.
Log the actual SSL/private-key error at ERROR and fail outbound associations fast with a clear exception instead of silent disassociations.
Adds unit test.

Changes

DotNetty transport
- Handle TlsHandshakeCompletionEvent in TcpHandlers.UserEventTriggered:
  - Log failure at ERROR with the underlying exception.
  - Notify via UnderlyingTransportError when possible.
  - Close the channel.
- Client association (AssociateInternal)
  - Wait for TLS handshake completion when SSL is enabled.
  - Throw InvalidAssociationException with the TLS failure as inner exception on error.
Tests
- Added DotNettyTlsHandshakeFailureSpec to assert that server logs “TLS handshake failed …” at ERROR when cert lacks a private key and a client connects.

Behavioral impact

On TLS failures:
- Server logs ERROR with the underlying exception (e.g., private key access denied).
- Client Associate now fails fast with InvalidAssociationException containing the TLS error.
No public API changes. Normal operation unaffected.

Arkatufus

Self review

Arkatufus · 2025-09-15T16:18:33Z

src/core/Akka.Remote/Transport/DotNetty/TcpTransport.cs

+        public override void UserEventTriggered(IChannelHandlerContext context, object evt)
+        {
+            if (evt is TlsHandshakeCompletionEvent { IsSuccessful: false } tlsEvent)
+            {
+                var ex = tlsEvent.Exception ?? new Exception("TLS handshake failed.");
+                Log.Error(ex, "TLS handshake failed. Channel [{0}->{1}](Id={2})",
+                    context.Channel.LocalAddress, context.Channel.RemoteAddress, context.Channel.Id);
+
+                // Best-effort surface to higher layers if listener already registered
+                NotifyListener(new UnderlyingTransportError(ex,
+                    $"TLS handshake failed on channel [{context.Channel.LocalAddress}->{context.Channel.RemoteAddress}](Id={context.Channel.Id})"));
+
+                context.CloseAsync();
+                return; // don't pass to next handlers
+            }
+
+            base.UserEventTriggered(context, evt);
+        }


Server side fix, listen for TLS handshake failure event and log/propagate it.

Arkatufus · 2025-09-15T16:19:07Z

src/core/Akka.Remote/Transport/DotNetty/TcpTransport.cs

+        public override void UserEventTriggered(IChannelHandlerContext context, object evt)
+        {
+            if (evt is TlsHandshakeCompletionEvent tlsEvent)
+            {
+                if (tlsEvent.IsSuccessful)
+                {
+                    _tlsHandshakePromise.TrySetResult(true);
+                }
+                else
+                {
+                    var ex = tlsEvent.Exception ?? new Exception("TLS handshake failed.");
+                    _tlsHandshakePromise.TrySetException(ex);
+                }
+            }
+
+            base.UserEventTriggered(context, evt);
+        }


Client side fix, listen for TLS handshake failure and log/propagate it.

Arkatufus · 2025-09-15T17:48:28Z

Server side now logs the error appropriately:

[ERROR][09/15/2025 17:45:52.318Z][Thread 0207][TcpServerHandler (akka://ServerSystem)] TLS handshake failed. Channel [[::ffff:127.0.0.1]:52428->[::ffff:127.0.0.1]:52431](Id=091aa123)
Cause: System.AggregateException: One or more errors occurred. ---> System.NotSupportedException: The server mode SSL must use a certificate with the associated private key.
   at System.Net.Security.SslState.InternalEndProcessAuthentication(LazyAsyncResult lazyResult)
   at System.Net.Security.SslState.EndProcessAuthentication(IAsyncResult result)
   at System.Threading.Tasks.TaskFactory`1.FromAsyncCoreLogic(IAsyncResult iar, Func`2 endFunction, Action`1 endAction, Task`1 promise, Boolean requiresSynchronization)
   --- End of inner exception stack trace ---
---> (Inner Exception #0) System.NotSupportedException: The server mode SSL must use a certificate with the associated private key.
   at System.Net.Security.SslState.InternalEndProcessAuthentication(LazyAsyncResult lazyResult)
   at System.Net.Security.SslState.EndProcessAuthentication(IAsyncResult result)
   at System.Threading.Tasks.TaskFactory`1.FromAsyncCoreLogic(IAsyncResult iar, Func`2 endFunction, Action`1 endAction, Task`1 promise, Boolean requiresSynchronization)<---

The client side logs the error appropriately:

[ERROR][09/15/2025 17:45:52.320Z][Thread 0218][TcpClientHandler (akka://ClientSystem)] TLS handshake failed. Channel [[::ffff:127.0.0.1]:52431->[::ffff:127.0.0.1]:52428](Id=61619740)
Cause: System.IO.IOException: Channel is closed
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at System.Runtime.CompilerServices.ConfiguredTaskAwaitable.ConfiguredTaskAwaiter.GetResult()
   at Akka.Remote.Transport.DotNetty.TcpTransport.<AssociateInternal>d__1.MoveNext() in D:\git\akkadotnet\akka.net\src\core\Akka.Remote\Transport\DotNetty\TcpTransport.cs:line 259
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at System.Runtime.CompilerServices.ConfiguredTaskAwaitable.ConfiguredTaskAwaiter.GetResult()
   at Akka.Remote.Transport.DotNetty.TcpTransport.<AssociateInternal>d__1.MoveNext() in D:\git\akkadotnet\akka.net\src\core\Akka.Remote\Transport\DotNetty\TcpTransport.cs:line 259

Aaronontheweb

LGTM

Propagate error from DotNetty TLS handshake failure to Akka.Remote

01e6054

Arkatufus commented Sep 15, 2025

View reviewed changes

Aaronontheweb approved these changes Sep 15, 2025

View reviewed changes

Aaronontheweb added akka-remote dotnetty labels Sep 15, 2025

Aaronontheweb enabled auto-merge (squash) September 15, 2025 19:01

Aaronontheweb disabled auto-merge September 15, 2025 19:40

Aaronontheweb merged commit f595a84 into akkadotnet:v1.5 Sep 15, 2025
9 of 11 checks passed

This was referenced Sep 15, 2025

Exception inside DotNetty TLS handler isn't propagated to Akka.Remote #7823

Closed

Fix missing error when SSL private key is missing #7821

Closed

Arkatufus mentioned this pull request Sep 22, 2025

Update RELEASE_NOTES.md for 1.5.50 release #7837

Merged

This was referenced Oct 1, 2025

Bump Akka.TestKit.Xunit2 from 1.5.49 to 1.5.51 petabridge/akka-bootcamp#410

Closed

Bump Akka.Cluster.TestKit from 1.5.47 to 1.5.51 akkadotnet/Akka.MultiNodeTestRunner#325

Merged

Bump Akka.Streams from 1.5.40 to 1.5.51 Aaronontheweb/Alpakka#889

Closed

This was referenced Nov 6, 2025

Bump Akka.Persistence.Query from 1.4.43 to 1.5.55 Arkatufus/Akka.Persistence.Azure#76

Closed

Bump Akka.Persistence.TCK from 1.4.43 to 1.5.55 Arkatufus/Akka.Persistence.Azure#77

Closed

This was referenced Nov 26, 2025

Bump Akka.Streams from 1.5.42 to 1.5.56 Aaronontheweb/Akka.Streams.Benchmark#70

Closed

Bump Akka.TestKit.Xunit2 from 1.5.47 to 1.5.56 petabridge/Akka.Cluster.Chunking#187

Closed

This was referenced Dec 12, 2025

Bump Akka.Streams from 1.5.42 to 1.5.57 Aaronontheweb/Akka.Streams.Benchmark#71

Closed

Bump Akka.TestKit.Xunit2 from 1.5.47 to 1.5.57 petabridge/Akka.Cluster.Chunking#190

Open

This was referenced Jan 9, 2026

Bump Akka.Streams from 1.5.42 to 1.5.58 Aaronontheweb/Akka.Streams.Benchmark#72

Closed

Bump Akka from 1.5.31 to 1.5.58 Aaronontheweb/akka.net-log-trace-correlation-POC#8

Merged

dependabot bot mentioned this pull request Jan 27, 2026

Bump Akka.Streams from 1.5.42 to 1.5.59 Aaronontheweb/Akka.Streams.Benchmark#73

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Propagate error from DotNetty TLS handshake failure to Akka.Remote#7824

Propagate error from DotNetty TLS handshake failure to Akka.Remote#7824
Aaronontheweb merged 1 commit intoakkadotnet:v1.5from
Arkatufus:1.5/Fix-missing-DotNetty-TLS-exceptions

Arkatufus commented Sep 15, 2025 •

edited

Loading

Uh oh!

Arkatufus left a comment

Uh oh!

Arkatufus Sep 15, 2025

Uh oh!

Arkatufus Sep 15, 2025 •

edited

Loading

Uh oh!

Arkatufus commented Sep 15, 2025

Uh oh!

Aaronontheweb left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Arkatufus commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Behavioral impact

Uh oh!

Arkatufus left a comment

Choose a reason for hiding this comment

Uh oh!

Arkatufus Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

Arkatufus Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Arkatufus commented Sep 15, 2025

Uh oh!

Aaronontheweb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Arkatufus commented Sep 15, 2025 •

edited

Loading

Arkatufus Sep 15, 2025 •

edited

Loading