Suggestion: `sni-certs` folder auto-scan + optional `hostnames`

[DisasteR]

Problem Statement

Current sni-cert blocks require mandatory hostnames + individual file paths, making it cumbersome to manage folders containing many dynamically generated domain.crt/domain.key pairs from PKI agents or automation workflows.

HAProxy's ssl crt /path/ has long supported automatic folder scanning, CN/SAN extraction, and most-specific SNI selection - a production-proven approach for DevOps scalability.

Proposed Solution

1. New sni-certs block for folder auto-scan (within additional-certs)

sni-certs {
    cert-folder "/etc/zentinel/certs/dynamic/"     // Scans *.crt + matching *.key pairs (fullchain .crt)
    reload-mode "interval"                        // "off" | "interval" | "inotify" 
    reload-interval "30s"                         // Only if reload-mode="interval"
}

2. Make hostnames optional in existing sni-cert (auto CN/SAN fallback)

sni-cert {
    cert-file "/premium.crt"                      // CN=*.premium.com SAN=api.example.com  
    key-file "/premium.key"
    // hostnames auto-extracted from CN/SAN if not specified
}

Complete TLS Configuration Example

listener "https" {
    address "0.0.0.0:443"
    protocol "https"
    tls {
        // 1. MANUAL DEFAULT (highest priority if present, blocks ACME)
        cert-file "/etc/zentinel/certs/manual-default.crt"
        key-file "/etc/zentinel/certs/manual-default.key"

        // ACME automatic (fallback/domains-specific, used only if no manual)
        acme {
            email "admin@example.com"
            domains "auto.example.com" "newshop.com"
        }

        additional-certs {
            // PRIORITY 3: SNI-CERT WITH explicit hostnames
            sni-cert {
                hostnames "api.example.com" "direct.api.example.com"
                cert-file "/etc/zentinel/certs/api-explicit.crt"
                key-file "/etc/zentinel/certs/api-explicit.key"
            }

            // PRIORITY 4: SNI-CERT WITHOUT hostnames (auto CN/SAN)
            sni-cert {
                cert-file "/etc/zentinel/certs/premium-auto.crt"    // CN=*.premium.com SAN=www.example.com
                key-file "/etc/zentinel/certs/premium-auto.key"
            }

            // PRIORITY 5: SNI-CERTS FOLDER AUTO-SCAN (NEW)
            sni-certs {
                cert-folder "/etc/zentinel/certs/dynamic/"
                reload-mode "interval"
                reload-interval "30s"
            }
        }
    }
}

/etc/zentinel/certs/dynamic/ folder contents:

api-dynamic.crt      (CN=api.example.com)
premium-dynamic.crt  (CN=*.premium.com, SAN=beta.example.com)
wildcard-dynamic.crt (CN=*.example.com)

SNI Selection Results

Requested SNI	Selected Certificate	Priority	Reason
api.example.com	api-explicit.crt	#3	Exact hostnames match
direct.api.example.com	api-explicit.crt	#3	hostnames pattern match
www.example.com	premium-auto.crt	#4	SNI in SAN of auto sni-cert
app.premium.com	premium-auto.crt	#4	SNI in CN of auto sni-cert
beta.example.com	premium-dynamic.crt	#5	SNI in SAN of folder scan
static.example.com	wildcard-dynamic.crt	#5	*.example.com longest-prefix
shop.auto.example.com	ACME cert	#6	ACME domains match
newshop.com	ACME cert	#6	ACME domains match (no higher)
unknown.com	manual-default.crt	#1	Default manual cert

Processing Priority Order

1. manual cert-file/key-file (blocks everything else including ACME)
2. sni-cert { hostnames SNI in patterns } → explicit priority
3. sni-cert {} SNI in CN/SAN → auto cert CN/SAN  
4. sni-certs folder SNI in CN/SAN → folder auto-scan
5. ACME (SNI in acme.domains only if no higher match)
6. FALLBACK Default manual cert (possible TLS handshake fails on validation)

Detailed Auto CN/SAN Behavior

• sni-certs { cert-folder }: Scans folder for <name>.crt + <name>.key pairs, parses each .crt CN/SAN → builds hostname→cert index
• sni-cert without hostnames: Parses single cert CN/SAN → indexes that cert for those hostnames
• sni-cert WITH hostnames: 1) SNI matches pattern → use cert (priority), 2) OR SNI in CN/SAN → use cert anyway

Benefits: Zero-config PKI folders, full ACME compatibility, HAProxy-like simplicity, production-ready reload modes (kill -HUP + inotify/interval).

Alternatives Considered

No response

Where does this belong?

Configuration option

Manifesto Alignment

• This feature can be bounded (has clear limits)
• This feature can be observed (metrics, logs)
• This feature can fail safely (explicit failure modes)
• This feature does not add implicit behavior

Checklist

• I have searched existing issues for duplicates
• I have read the Manifesto

[raffaelschneider]

Hey @DisasteR

First off, thanks for the detailed proposal, the SNI selection table and priority model are really well structured. :)

Tbh, we're interested in both features. A few thoughts and questions though:

On the manifesto alignment / implicit behavior

We think this can stay within bounds. The folder path is explicitly declared in config, so the source of truth is explicit, what's implicit is only which hostnames route where, since that's derived from cert contents rather than stated in config. That's a meaningful distinction from, say, silently discovering certs from a default path. That said, we'd want to make sure this is observable enough to not become a debugging black hole: on startup and reload, we should log every cert loaded, the CN/SAN extracted, and the resulting hostname→cert mapping. A mismatch between "what I dropped in the folder" and "what Zentinel is serving" needs to be diagnosable without guesswork.

Questions on the design

1. Tie-breaking within a tier: If two folder-scanned certs both match a given SNI (e.g. overlapping SANs, or two wildcards at the same depth), what should happen? First-found-wins (filesystem order) is fragile. We'd lean toward erroring on ambiguity at load time, thoughts?

2. Malformed/missing pairs: When a .crt exists without a matching .key, or a cert fails to parse, should we skip it with a warning, or refuse to start? Our instinct is skip + warn for folder scans (since they're more dynamic), but hard-error for explicit sni-cert blocks. Does that match your expectation?

3. Reload semantics: For interval mode, is the intent to do a full rescan + diff, or only pick up new files? A full rescan handles deletions and replacements cleanly but is worth calling out. Also, should a bad cert discovered mid-reload poison the entire reload (atomic rollback) or just be skipped?

4. inotify portability: inotify is Linux-only. We could offer "watch" as the mode name and use the platform-appropriate mechanism (kqueue on macOS/BSD), or just support "interval" initially and add filesystem watching later. Do you have a preference?

5. Priority numbering: The manual default cert appears as both the highest-priority item (Welcome to Sentinel Discussions! #1) and the fallback (ci: bump actions/upload-pages-artifact from 3 to 4 #6 in the selection table for unknown.com). We read this as: manual default is the fallback when no SNI-specific match is found, not the highest priority override. Could you clarify the intended behavior, should a manual default cert override an SNI-specific match, or only serve as fallback?

Scope-wise, we'd probably split this into two PRs:

• First: make hostnames optional in sni-cert with CN/SAN auto-extraction (smaller, self-contained)
• Second: sni-certs folder scan + reload modes (larger, builds on the first)

Looking forward to your input on the above before we start on this.

[DisasteR]

Hello @raffaelschneider,

Thank you for your detailed feedback and thoughtful questions. Here are my thoughts on each point. These are just suggestions based on my experience - your expertise on the codebase should guide the final decisions.

---

1. Tie-breaking within a tier

My thinking: Longest match SNI + deterministic tie-breaking

Based on my production experience, a flexible approach would be practical.

Context

Certificate overlaps occur regularly for legitimate reasons:

• Certificate rotation (old + new coexist temporarily)
• A/B testing of new PKI chains
• Certificates from different CAs for varied client compatibility
• Multi-tenant with certificate-based isolation

It seems to me that strict errors on overlaps could be constraining in these scenarios. Explicit config via hostnames in sni-cert already exists for cases requiring strict control.

Suggested behavior

Perhaps something like:

1. Longest match SNI/hostname
   Exact match > Wildcard (*.example.com) > Default

2. If multiple certificates match at the same specificity level:
   Deterministic selection (reproducible across reloads)

Observability

For debugging, it would be helpful to see in logs details such as:

• Requested SNI
• Selected certificate (path + serial/fingerprint)
• Other matching certificates (tie-break candidates)
• Reason for selection

Possible log example:

debug: SNI match with tie-breaking
  sni: api.example.com
  selected: api-v1.crt (serial=001)
  also_matched: api-v2.crt (serial=002) [tie-break]

This would help me:

• Understand which certificate was selected
• Detect unintentional overlaps
• Adjust my configuration as needed

Tie-breaking method

I would suggest serial number (lexicographic order) because:

• Stable and reproducible
• Intrinsic to the certificate (filesystem-independent)
• Easy to verify with openssl x509 -in cert.crt -serial -noout

Other approaches could work:

• Fingerprint SHA-256 (also stable)

You mentioned that first-found-wins (filesystem order) is fragile, which seems consistent to me. Random would also be unpredictable.

Optional configuration?

A tie-break-mode parameter doesn't seem necessary initially. A sane default behavior would suffice, with the possibility to add configuration later if the need emerges.

Suggestion: CLI test command

For debugging, a CLI command could be useful:

zentinel test-sni api.example.com
# Shows: Which certificate would be selected + why (exact/wildcard/default)

This would allow verifying SNI resolution without making an actual TLS request.

---

2. Malformed/missing pairs

My thinking: Skip + log (best-effort)

Production flexibility seems important to me, though I understand the argument for strict validation.

Typical use case

example Scenario:

/certs/
  api.crt          ← Old certificate (expires in 2h)
  api.key
  api-new.crt      ← New certificate
  api-new.key      ← Not yet present

In this case, being able to continue with api.crt while api-new.key is being deployed would avoid downtime.

Suggested behavior

For sni-certs folder scan: Skip + log (best-effort)

Logs could include details such as:

• Path of problematic certificate (cert + key)
• Failure reason (missing key, parse error, permissions, expiration)
• Source (folder scan)
• Timestamp

This would facilitate rapid problem identification without blocking the loading of other valid certificates.

Summary at startup/reload

A global summary would also be useful:

• Total certificates found
• Successfully loaded count
• Failed count

---

3. Reload semantics

My thinking: Full rescan + diff + atomic swap

Your approach seems solid to me.

Suggested behavior

At each reload, perhaps:

1. Scan all certificates (explicit + folder)
2. Calculate diff vs current state
3. Build complete new resolver
4. Atomic swap
5. Log changes

Diff logging

It would be practical to see what changed. Logs could include:

• Affected hostname
• Change type (added/removed/updated)
• Certificate paths (old and/or new)
• Timestamp

This would help me with auditing and verifying changes.

Error handling during mid-reload

Two possible approaches:

Option A (best-effort): Skip invalid certificates, load the rest

• Continue with valid certificates
• Logs could include:
  • Path of problematic certificate
  • Failure reason
  • Timestamp
  • Impact (which hostnames affected)
• Allows corrections without downtime

Option B (atomic): Complete rollback if any error

• Keeps the old complete configuration
• More conservative but may block legitimate reloads

I would lean toward Option A for production flexibility, but Option B offers more consistency guarantees. You judge better than I the security vs availability tradeoffs for Zentinel. Perhaps making this configurable.

---

4. inotify portability

My thinking: watch mode multi-OS with fallback to interval

Your progressive approach seems well thought out to me.

Suggested configuration

Perhaps something like:

sni-certs {
    cert-folder "/etc/zentinel/certs/dynamic/"
    reload-mode "watch"       // "off" | "interval" | "watch"
    reload-interval "30s"     // Fallback if watch unavailable
}

Suggested behavior

watch mode:

• Attempt native filesystem watcher (inotify/kqueue/etc.)
• If success → use watch
• If failure → fallback to interval + warning

interval mode: Direct polling
off mode: Manual reload only (SIGHUP)

Observability

Logs could include details such as:

• Monitored folder path
• Method used (inotify/kqueue/interval/polling)
• If fallback: reason + interval used
• Watcher status (active/error)

This would facilitate diagnosing reload issues without having to guess the active mode.

---

5. Priority numbering - Clarification

My thinking: Default = Fallback

The term "priority" was indeed confusing. Here's my understanding of the algorithm.

Current ACME behavior reminder

Currently in Zentinel:

• If cert-file + key-file configured → manual certificates used
• If ACME configured → ACME certificates stored and used as fallback or for specified domains
• Manual certificates have priority over ACME if present

Suggested SNI resolution algorithm

If SNI provided in TLS handshake:
  1. Apply LONGEST MATCH on specific certificates:
     - sni-cert with explicit hostnames
     - sni-cert without hostnames (auto CN/SAN)
     - sni-certs folder scan

  2. If multiple certificates match at same level → tie-breaking

  3. If no match in specific certificates:
     → Check ACME domains (if configured)

  4. If still no match → use default/fallback certificate

If NO SNI in handshake:
  → Always use default/fallback certificate

Default/fallback certificate:
  - cert-file + key-file if configured
  - Otherwise ACME certificate for first domain
  - Otherwise error (no certificate available)

Resolution order:

1. Specific certificates (sni-cert, sni-certs) with longest match
2. ACME (if match on configured domains, only if no specific match)
3. Default/fallback

Specificity rules (Longest Match)

Specificity level (most specific to least specific):
1. Exact match: "api.example.com"
2. Wildcard: "*.example.com" (single-level only)
3. Default/Fallback

Within same level → tie-breaking

Example configuration

listener "https" {
    address "0.0.0.0:443"
    protocol "https"

    tls {
        // DEFAULT/FALLBACK CERTIFICATE
        cert-file "/etc/zentinel/certs/default.crt"
        key-file "/etc/zentinel/certs/default.key"

        additional-certs {
            // Explicit hostnames
            sni-cert {
                hostnames "api.example.com" "*.api.example.com"
                cert-file "/certs/api.crt"
                key-file "/certs/api.key"
            }

            // Auto CN/SAN extraction
            sni-cert {
                cert-file "/certs/premium.crt"
                key-file "/certs/premium.key"
            }

            // Folder scan
            sni-certs {
                cert-folder "/certs/dynamic/"
                reload-mode "watch"
                reload-interval "30s"
            }
        }

        // ACME (additional domains)
        acme {
            domains "auto.example.com" "shop.example.com"
        }
    }
}

Resolution table

SNI requested	Match found	Certificate used	Reason
api.example.com	Exact	api.crt	Explicit hostname
v2.api.example.com	Wildcard	api.crt	*.api.example.com
sub.v2.api.example.com	None	default.crt	Wildcard single-level only
app.premium.com	Wildcard	premium.crt	*.premium.com extracted from CN/SAN
beta.example.com	Exact	beta.crt (folder)	Found in folder scan
auto.example.com	Exact	ACME cert	ACME domain
unknown.com	None	default.crt	Fallback
(no SNI)	N/A	default.crt	Fallback

All certificates would be treated the same way with the longest match algorithm (no artificial "priority tiers").

---

Additional points

Backward compatibility

Making hostnames optional directly would seem cleaner to me:

// Syntax unchanged
sni-cert {
    hostnames "api.example.com"
    cert-file "/cert.crt"
    key-file "/key.key"
}

// New - auto extraction
sni-cert {
    cert-file "/cert.crt"
    key-file "/key.key"
}

But an auto_extract flag could be preferable if the breaking change is problematic.

Metrics

For monitoring, these metrics could be added (consistent format with existing metrics like zentinel_requests_total, zentinel_tls_handshake_duration_seconds):

# Gauge - Number of loaded certificates by source
zentinel_tls_certificates_loaded{source="explicit|folder|acme"}

# Counter - Certificate loading errors
zentinel_tls_certificates_load_errors_total{source="explicit|folder|acme",reason="missing_key|parse_error|..."}

# Gauge - Timestamp of last successful reload
zentinel_tls_reload_last_success_timestamp_seconds

# Counter - Total number of reloads
zentinel_tls_reload_total{status="success|error"}

Not urgent, just an idea to complement existing observability.

---

Summary of my suggestions

Aspect	My proposal
Tie-breaking	Longest match + deterministic (accept overlaps)
Malformed certs	Skip + log (best-effort for folder scan)
Reload	Full rescan + diff + atomic
Portability	watch multi-OS + fallback interval
Priority	Default = Fallback (unified longest match)
Observability	Detailed logs for debugging

These are just my suggestions based on my view of things - not necessarily the best options. Your expertise on the codebase and production needs should guide the final design. Happy to adjust based on what makes most sense for Zentinel.

[raffaelschneider]

Thanks for the follow-up @DisasteR.

A few of these points are helpful, the priority clarification (default = fallback, not override) answers what we were asking, and watch as a platform-agnostic mode name makes sense over inotify.

On tie-breaking: we're not fully convinced that silently accepting overlaps is the right default. Ambiguous cert selection has security implications beyond debugging inconvenience, if two certs match the same SNI and the "wrong" one gets served, that's a TLS trust issue, not just a log line. We'll probably start strict (error on ambiguity within the same source) and relax later if real-world usage demands it.

For the rest (malformed cert handling, reload semantics, backward compat), we're aligned and will sort out the details during implementation. No need to over-design it upfront.

[DisasteR]

Thanks @raffaelschneider for the feedback!

Your point on tie-breaking makes complete sense - the security implications are indeed more serious than I initially considered. Starting strict is the right call.

Perhaps a middle ground for later: keep the strict default (error on ambiguity), but add a global opt-in parameter for those who explicitly need overlap tolerance?

tls {
    cert-file "/etc/zentinel/certs/default.crt"
    key-file "/etc/zentinel/certs/default.key"
    allow-sni-overlaps false  // Default: strict, error on ambiguity (global)

    additional-certs {
        sni-cert { ... }
        sni-certs { cert-folder "/certs/" ... }
    }
}

This way:

• Safe by default (your preference, security-first)
• Flexibility when needed (for advanced users who understand the trade-offs)

[raffaelschneider]

Thanks @DisasteR

That works for me. Strict by default with an explicit opt-in keeps things aligned with how we think about security in Zentinel: no silent decisions, no ambiguous state unless you've deliberately asked for it.

If we go with allow-sni-overlaps, we'd want the tie-breaking to be deterministic and logged, not just "accepted." Your serial number suggestion is reasonable, we'll sort out the exact mechanism during implementation. The key constraint is that an operator enabling this flag should still be able to trace exactly which cert was selected and why.

On implementation, we're planning to split this into two PRs as mentioned earlier:

PR 1: Optional hostnames in sni-cert (CN/SAN auto-extraction)

• Make hostnames optional in the config parser
• Add CN/SAN extraction from the certificate at load time
• Log every extracted hostname mapping on startup
• Error on ambiguity (two certs resolving to the same SNI)
• Update config validation and docs

PR 2: sni-certs folder scan + reload

• New sni-certs block with cert-folder, reload-mode, reload-interval
• reload-mode options: off, interval, watch (platform-native with interval fallback)
• Full rescan + diff + atomic swap on reload
• Skip + warn for malformed/unpaired certs in folder scans
• Metrics: zentinel_tls_certificates_loaded, zentinel_tls_reload_total, etc.
• allow-sni-overlaps flag (default false)

We'll start on PR 1 soon. Thanks again for the thorough proposal, this was a productive discussion. :)

[DisasteR]

Hi @raffaelschneider,

Quick follow-up on PR #118 which was merged! 🎉

I posted some feedback on the PR about the hostnames behavior just before the merge (literally 1 second before!). Since the timing was so tight, I wanted to reference it here in case it wasn't seen.

The feedback raises a potential inconsistency where explicit hostnames replace certificate SAN entries rather than complement them, which might not match the original intent from our discussion.

No rush - just wanted to make sure it's on your radar if any follow-up adjustments are needed.

Thanks!