Skip to content

Conversation

@backkem
Copy link
Contributor

@backkem backkem commented Jun 1, 2025

This fixes a specification bug where the hostname formation requires the certificate serial number, but it was not being advertised in mDNS TXT records, making it impossible for clients to form the correct hostname for TLS SNI.

Resolves the discrepancy between hostname formation requirements and mDNS advertisement specifications.

@backkem backkem requested a review from markafoltz June 1, 2025 11:49
This fixes a specification bug where the hostname formation requires the
certificate serial number, but it was not being advertised in mDNS TXT
records, making it impossible for clients to form the correct hostname
for TLS SNI.

Resolves the discrepancy between hostname formation requirements and
mDNS advertisement specifications.
@baylesj baylesj self-requested a review September 25, 2025 23:52
`[A-Za-z0-9+/]`.

: sn
:: The [=certificate serial number=] of the advertising agent, encoded as a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the agent fingerprint insufficent for computing the agent hostname? I also don't see any other reference to TLS SNI in this file, and it's not entirely clear to me why we even need Server Name Indication for this protocol. Can you please provide some additional context?

Copy link
Contributor Author

@backkem backkem Sep 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please see the comment below for an improved motivation/overview.

@backkem
Copy link
Contributor Author

backkem commented Jan 28, 2026

I wanted to add a little overview / extended motivation for this PR as I see it.

TL;DR

The spec requires TLS SNI = agent_hostname, but agent_hostname requires sn (serial number, introduced in #276), which isn't advertised in mDNS. Clients can't connect.

Fix: Add sn to mDNS TXT records.


The Problem

The spec has a dependency chain that breaks at mDNS advertisement:

┌─────────────────────────────────────────────────────────────────────────────┐
│  WHAT THE SPEC REQUIRES                                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. Agent Hostname (lines 240-249)                                          │
│                                                                             │
│     agent_hostname = base64(sn) + "." + instance + "." + domain             │
│                           │                                                 │
│                           └──► Requires: serial number (sn)                 │
│                                                                             │
│  2. TLS Connection (line 296, per RFC 6066)                                 │
│                                                                             │
│     server_name extension (SNI) MUST be set to agent_hostname               │
│                           │                                                 │
│                           └──► Requires: agent_hostname                     │
│                                                                             │
│  3. Certificate (line 378)                                                  │
│                                                                             │
│     CN = agent_hostname                                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  WHAT mDNS ACTUALLY ADVERTISES (lines 161-178)                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│     ┌──────┬────────────────────────────────┐                               │
│     │  fp  │  agent fingerprint             │                               │
│     ├──────┼────────────────────────────────┤                               │
│     │  mv  │  metadata version              │                               │
│     ├──────┼────────────────────────────────┤                               │
│     │  at  │  authentication token          │                               │
│     ├──────┼────────────────────────────────┤                               │
│     │  sn  │  ❌ NOT INCLUDED               │  ◄── THE GAP                  │
│     └──────┴────────────────────────────────┘                               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

What This Looks Like in Practice

BEFORE (broken):

  Advertising Agent                          Listening Agent (Client)
        │                                            │
        │──── mDNS: fp, mv, at ─────────────────────►│
        │                                            │
        │                                            │  Client wants to connect...
        │                                            │  Spec says: set SNI = agent_hostname
        │                                            │  agent_hostname = base64(sn) + ...
        │                                            │
        │                                            │  ❌ But where is sn?
        │                                            │
        X                                            X
                        CONNECTION FAILS


AFTER (with PR #360):

  Advertising Agent                          Listening Agent (Client)
        │                                            │
        │──── mDNS: fp, mv, at, sn ─────────────────►│
        │                                            │
        │                                            │  ✓ Has sn, can compute agent_hostname
        │                                            │
        │◄─── TLS ClientHello (SNI = agent_hostname)─│
        │                                            │
                        CONNECTION SUCCEEDS

Why SNI?

RFC 6066 Section 3 explains that SNI exists for virtual hosting:

"It may be desirable for clients to provide this information to facilitate secure connections to servers that host multiple 'virtual' servers at a single underlying network address."

In OSP context (my opinion): A single device could advertise itself in multiple different contexts (e.g., different applications or origins) while sharing the same IP:port. SNI enables this by allowing distinct hostnames per context - which also alligns with browser origin separation where each context needs its own isolated transport identity.

Without sn in mDNS, clients cannot compute the agent_hostname needed for SNI, breaking this capability.

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.

2 participants