Skip to content

Add ssl_peer_metadata option to expose client certificate details - #245

Open
lhuet wants to merge 2 commits into
logstash-plugins:mainfrom
lhuet:feature/tls-peer-metadata-main
Open

lhuet wants to merge 2 commits into
logstash-plugins:mainfrom
lhuet:feature/tls-peer-metadata-main

Conversation

@lhuet

@lhuet lhuet commented Nov 4, 2026

Copy link
Copy Markdown

What

Adds an opt-in ssl_peer_metadata option (boolean, default false). When mutual TLS is used, the details of the client certificate are added to [@metadata] of the events, like the ssl_peer_metadata enrichment of the beats input.

Requires ssl_client_authentication to be optional or required (a ConfigurationError is raised otherwise).

Fields

ECS v1/v8 ECS disabled
[@metadata][tls_peer][status] [@metadata][tls_peer][status]
[@metadata][input][http][tls][client][subject] [@metadata][tls_peer][subject]
[@metadata][input][http][tls][version_protocol] [@metadata][tls_peer][protocol]
[@metadata][input][http][tls][cipher] [@metadata][tls_peer][cipher_suite]
[@metadata][input][http][tls][client][x509][subject][common_name] [@metadata][tls_peer][subject_cn]
[@metadata][input][http][tls][client][issuer] [@metadata][tls_peer][issuer_dn]
[@metadata][input][http][tls][client][x509][serial_number] [@metadata][tls_peer][serial]
[@metadata][input][http][tls][client][not_before] / [not_after] [@metadata][tls_peer][not_before] / [not_after]
[@metadata][input][http][tls][client][hash][sha256] [@metadata][tls_peer][fingerprint_sha256]
[@metadata][input][http][tls][client][x509][alternative_names] [@metadata][tls_peer][sans]

status is verified when the client presented a certificate, unverified otherwise (only possible with optional). Names follow the beats input; the ECS ones use tls.client.*, under [@metadata][input][http] like the other ECS fields of this plugin. Note that x509.alternative_names is not in the official ECS spec.

How

The certificate is not reachable from the Ruby side (the Java IMessageHandler only receives remote address, headers and body). TlsPeerInfo (Java) reads the peer certificate from the SSLSession, once per connection, and MessageProcessor hands it over as tls_peer_* pseudo-headers. The Ruby side moves them out of the headers and into [@metadata].

  • Extraction only happens when ssl_peer_metadata is enabled (passed down to NettyHttpServer; existing constructors are kept).
  • Request headers named tls_peer_* / Tls-Peer-* sent by a client are always discarded, so the values cannot be forged.
  • Invalid or expired client certificates are rejected during the TLS handshake as before; nothing changes there.

Tests

  • Java: TlsPeerInfoTest.
  • Specs: values for ECS disabled and v1, forged headers ignored, client without certificate (optional), option disabled, config validation.
  • Also checked by hand on Logstash 9.5.6 (valid certificate, no certificate, expired certificate, forged header; ECS disabled and v1).
  • 4 additional_codecs specs fail locally with and without this change (Logstash 8.19.24 and 9.5.6 cores).

CHANGELOG.md / version are left to /pr_prepare.

Relates to logstash-plugins/logstash-integration-logstash#22. A backport to 3.x follows (Logstash 8.19).

I have signed the Elastic CLA.

This change was developed with the help of Claude Code and reviewed by me.

🤖 Generated with Claude Code

lhuet and others added 2 commits November 4, 2026 15:52
When mutual TLS is used, add the details of the client certificate
(status, subject, issuer, serial, validity, protocol, cipher suite,
common name, SHA-256 fingerprint, SANs) to `[@metadata]`, aligned with
the field names of the beats input. Requests headers prefixed with
`tls_peer_` are discarded so the values cannot be forged by a client.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…nabled

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Changelog and Version Management

No changelog or version changes detected. You can either update them manually or use a comment command to update them automatically on merge:

/pr_prepare release:<patch|minor|major> — bump version + update changelog
/pr_prepare changelog:add — changelog entry only (no version bump)

/pr_prepare release:patch
- Add the changelog entry here
  - (Additional details can be provided in multiple lines, respecting markdown formatting)

Omit the entry line to use the PR title. If multiple commands are posted, the last one wins.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant