Skip to content

[FEATURE] Add enhanced logging for TLS handshake failures in mutual_tls authentication #6942

Description

@divakarsingh

Is your feature request related to a problem? Please describe.

When mutual_tls authentication is enabled (#6916), operators cannot easily distinguish
TLS handshake failures caused by client certificate rejections from network-level connection
issues. Armeria logs handshake failures at WARN level with minimal context.

Describe the solution you'd like

Add structured logging for TLS handshake failures when mutual_tls is configured, including:

  • Client IP address
  • Failure reason (e.g., "certificate not trusted", "no client certificate presented",
    "certificate expired")
  • Subject DN of the rejected certificate (if available)

This would allow operators to quickly identify:

  • Clients connecting without certificates
  • Clients using expired certificates
  • Clients signed by an untrusted CA

Implementation could use Armeria's ServerBuilder.childChannelPipelineCustomizer() to add
a Netty handler that listens for SslHandshakeCompletionEvent failures and emits a
structured log with the relevant details.

Additional context

Identified during review of #6916. Armeria's default WARN logging provides basic visibility
but does not include enough context to diagnose client-side misconfigurations.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Fields

No fields configured for issues without a type.

Projects

Status
Unplanned

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions