TLS/SNI support for plugins?

[BSAB96]

I've been using HFS as the public entry point for several self-hosted services, and I've been really impressed with how capable the reverse-proxy plugin is.

While working on this setup, I ran into one area where plugins, as far as I can tell, currently cannot help: TLS certificate selection.

If I understand correctly, because the TLS handshake happens before the HTTP request is routed, the reverse-proxy plugin does not currently get an opportunity to present a hostname-specific certificate.

Is there currently any mechanism for plugins to participate in certificate selection via SNI, or would this require changes within HFS itself?

If there is not currently a way to do this, would exposing that capability to plugins be something you would consider?

That would allow the reverse-proxy plugin, or another plugin, to handle TLS certificates for specific hostnames where a different certificate is needed.

A simple example is a Minecraft subdomain. The Minecraft service itself needs the hostname to remain DNS-only / grey-clouded in Cloudflare, because Cloudflare's normal free proxy does not support Minecraft TCP traffic. However, because that hostname still points to the same public IP, browser requests to that subdomain can still hit HFS on ports 80/443.

In that case, HFS presents the default Cloudflare Origin Certificate, which is fine for Cloudflare-proxied hostnames, but invalid for direct browser access. This results in a browser certificate warning before HFS or the reverse-proxy plugin can route or reject the request.

Being able to select certificates by hostname through SNI, or expose SNI certificate selection to plugins, would allow HFS to remain the public entry point while still handling mixed certificate scenarios cleanly.

[rejetto]

You are right, certificate selection happens during the TLS handshake, before HFS receives an HTTP request.
I didn't actually ever consider having multiple certificates.
If you are using letsencrypt, embedded or not in HFS, it allows you to have multiple domains with the same certificate.
Should I assume that you already have your certificates and you just need to use them?

[BSAB96]

Thanks — yes, that is basically right.

In my case, HFS can stay exactly as it is for normal single-certificate setups. I do not think the existing behaviour needs changing.

My setup is slightly unusual because I am mixing:

• a Cloudflare Origin wildcard certificate for Cloudflare-proxied hostnames
• selected DNS-only / grey-cloud hostnames that need direct browser-trusted certificates, such as Let's Encrypt

So yes, I can generate or provide the certificates myself. The missing part is mainly the ability for HFS, or a plugin, to choose which existing certificate to present based on the SNI hostname during the TLS handshake.

For most users, one certificate covering multiple domains is probably enough. In my case, the problem only appears because some hostnames must stay behind Cloudflare while others have to connect directly to the origin.

So the ideal feature would be:

• keep the current/default certificate behaviour exactly as it is
• optionally allow hostname-specific certificate overrides
• possibly expose that selection to plugins if that fits HFS better architecturally

[rejetto]

Provided that you already have your secondary certificate (or many), it seems possible for a plugin to add the support for it.
I don't think it should be the job for reverse-proxy, tho, because one may want to do that even without proxying.
So, in case, it should be a separate plugin.
I'm also considering adding such capability to HFS itself, but only if it's not worsening the UX for most users.

That said, HFS already has a lower-level plugin path for this. A backend plugin can access the HTTPS server through api.onServer() and, for HTTPS servers, use Node’s server.addContext(hostname, secureContext) to register hostname-specific certificates for SNI.

Example shape:

exports.init = function(api) {
    const fs = api.require('fs')
    const tls = api.require('tls')
    api.onServer(server => {
        server.addContext('minecraft.example.com', tls.createSecureContext({
            cert: fs.readFileSync('/path/to/cert.pem'),
            key: fs.readFileSync('/path/to/key.pem'),
        }))
    })
}

[BSAB96]

Thanks, that's exactly the information I was looking for.

I agree that this makes more sense as a separate plugin rather than part of the reverse-proxy plugin, since the issue is really TLS/SNI rather than proxying itself.

I'll have a go at writing a small backend plugin that registers additional SNI contexts using api.onServer() and server.addContext().

My thought would be to leave HFS' existing certificate handling exactly as it is. The certificate configured in Options → HTTPS would remain the default certificate, with the plugin simply adding optional hostname-specific certificate mappings where required.

The use case would be:

keep the existing/default HFS certificate unchanged
add optional hostname-specific certificate mappings
use a Cloudflare Origin Certificate as the default certificate
use a browser-trusted certificate (such as Let's Encrypt) for selected DNS-only hostnames
fall back to the default HFS certificate for anything without a specific mapping

That should solve my use case cleanly while keeping the plugin entirely optional. Users who only require a single certificate can simply continue using HFS exactly as they do today.

[rejetto]

i'm already writing a plugin, so if you want you can save the effort

[BSAB96]

Wow ok, thank you very much!

[rejetto]

ok i published the plugin but i cannot test it.
would you do it? it's called multi-cert

[BSAB96]

I’ll happily test it on my setup once it’s installed on my HFS.

If useful, I can also provide feedback on the plugin UX or test wildcard/exact hostname mappings.

[BSAB96]

Already looks promising, have to head off for a while but shall let you know how it goes once I can sit down at my pc again.

Thank you very much for this as well, anything I can do to support in the future id be more than happy to 👍

[BSAB96]

I can confirm that after sorting out my certificate again, it was instant! check was only for one site specifically, so far that is working perfectly fine. I will look into wildcard usage next but based on what im seeing for most needs this is perfect as it is :)

[rejetto]

very well! 🎉