Problem

When TLS/SSL handshake failures occur in Akka.Remote, the error messages can be generic and unhelpful for diagnosing the actual root cause. Currently, CryptographicException errors from SslStream operations don't provide specific details about what went wrong during certificate validation.

The test suite acknowledges this limitation:

// DotNettySslSupportSpec.cs:251-253
// TODO: this error message is not correct, but wanted to keep this assertion here in case someone else
// wants to fix it in the future.
//Assert.Equal("The specified network password is not correct.", realException.Message);

Current Behavior

When certificate issues occur during TLS handshakes:

• Generic CryptographicException messages are surfaced
• Certificate chain validation errors appear as: `RemoteCertificateChainErrors`
• Specific failure reasons (missing intermediate CAs, wrong Extended Key Usage, expired certs, etc.) are not clearly communicated
• Users must resort to external diagnostic tools to determine the actual problem

Desired Behavior

Certificate validation failures should provide actionable error messages that include:

1. Certificate chain validation failures: Specify which part of the chain failed and why (missing intermediate CA, untrusted root, etc.)
2. Extended Key Usage issues: Clearly indicate if the certificate lacks required EKUs (e.g., "Client Authentication" for mutual TLS)
3. Certificate access problems: Distinguish between certificate not found vs. private key access denied
4. Policy errors: Map SslPolicyErrors enum values to human-readable explanations

Technical Context

The mutual TLS implementation in `DotNettyTransport.cs` uses `SslStream` with custom certificate validation callbacks:

// Lines 419-440: Server-side mutual TLS validation
userCertificateValidationCallback: (sender, certificate, chain, errors) =>
{
    if (certificate == null)
    {
        Log.Warning("Mutual TLS: Client connection rejected - no client certificate provided");
        return false;
    }

    if (Settings.Ssl.SuppressValidation)
    {
        return true;
    }

    if (errors != SslPolicyErrors.None)
    {
        Log.Warning("Mutual TLS: Client certificate validation failed with errors: {0}", errors);
        return false;
    }

    return true;
}

The `errors` parameter contains `SslPolicyErrors` flags, but these are logged as-is without detailed interpretation.

Suggested Implementation

1. Enhance certificate validation callback: Parse the `X509Chain` object to extract specific chain status errors
2. Add chain status interpretation: Map `X509ChainStatusFlags` to detailed error messages
3. Improve exception wrapping: Catch `CryptographicException` and `AuthenticationException` during handshake and wrap with descriptive messages
4. Update test expectations: Enable the commented assertion in `DotNettySslSupportSpec.cs:253`

Example enhanced error message:

SSL/TLS handshake failed: Certificate chain validation error
  - Chain status: PartialChain
  - Details: The certificate chain was issued by an authority that is not trusted. 
    Missing intermediate CA certificate(s) in LocalMachine\CA store.
  - Certificate: CN=example.com, Thumbprint=ABC123...
  - Suggestion: Install all intermediate CA certificates from your certificate provider

Benefits

• Faster troubleshooting for production SSL/TLS issues
• Reduced support burden from unclear certificate errors
• Better user experience during certificate configuration
• Easier migration to mutual TLS (users can identify exact certificate requirements)

Related Areas

• `DotNettyTransport.cs`: Lines 350-450 (TLS handler setup)
• `DotNettyTransportSettings.cs`: Lines 373-410 (`ValidateCertificate` method)
• `DotNettySslSupportSpec.cs`: Line 253 (test assertion)

Acceptance Criteria

• Certificate chain validation errors include specific `X509ChainStatus` details
• Error messages distinguish between different `SslPolicyErrors` values
• Private key access errors provide clear actionable guidance
• Test in `DotNettySslSupportSpec.cs` passes with correct error message assertion
• Documentation updated with common certificate error scenarios and resolutions