Note: This document was split out of the Local Peer-to-Peer API specification. It is an early, unofficial draft that sets a direction. Open questions are marked as issues.
Local HTTPS is a work in progress. [Issue #34]
1. Introduction
This section is non-normative.
Browsers can’t reach a NAS, printer or TV on the local network over HTTPS without a public name, a certificate authority and an internet connection. Local HTTPS uses ordinary X.509 certificate path validation [RFC5280] instead, with two differences from the Web PKI:
-
Trust anchors are added by the user through a trust ceremony, such as Local Peer-to-Peer authentication, instead of a root program. Each anchor is limited to a namespace under
.local. -
Requests from a page are scoped to the anchors for devices that the page was granted.
The origin model, CORS, the Origin header and Local Network Access are unchanged.
2. Local trust anchors
Local HTTPS uses the local trust store of Local Peer-to-Peer, one per user profile, separate from the Web PKI root store. Its trust anchors, here called local trust anchors, are added through a trust ceremony as defined there. For Local HTTPS, each anchor’s scope is a namespace, kept as name constraints in the trust store entry, as in [RFC5914]:
-
for a single peer, the name it advertises and the names under it;
-
for a vouching party, the namespace the user accepted in the trust ceremony.
-
A device that advertises its services under
nasis an anchor fornas.localand*.nas.local. -
A referee, such as a home hub that vouches for other devices, is an anchor for
*.home.local.
The namespace comes from the name the device advertises, and is trusted only once the ceremony has authenticated the device. Anchors with the same key merge, as defined by Local Peer-to-Peer. Anchors with different keys MUST NOT both be able to certify a host: the most specific namespace that contains a host decides which anchor may certify it, as with DNS delegation, and a trust ceremony MUST NOT add an anchor that would change which key certifies a host already in use, such as a known peer or a host with site data. So at most one key can certify a given host.
Define how the ceremony conveys and confirms the namespace, for devices and for referees.
Rotating an anchor key needs a proof of continuity, which is out of scope.
3. Local origins
A local host is a host that is a domain under local., which is resolved by Multicast DNS and never by global DNS [RFC6762].
A URL targets a local origin if its host is a local host within the namespace of one of the request’s applicable anchors. If its scheme is http, the user agent upgrades it to https, as for a known HSTS host. For any other URL, behaviour is unchanged.
Should other special-use local domains, such as home.arpa [RFC8375], be included?
3.1. Validation
The user agent finds the address of a local origin through discovery, which is untrusted, as DNS is. It sends the host in SNI and validates the certificate path [RFC5280] with:
-
the anchor with the most specific namespace that contains the host as the trust anchor;
-
that namespace and, for a request from a page, its peer grant as initial name constraints;
-
the host as the reference identifier, matched against the subjectAltName [RFC9525].
Certificate errors for a local origin MUST NOT be overridable. Leaves and intermediates can be short-lived and rotate freely.
Should the user agent also authenticate as a client? The requesting origin would still only be asserted.
3.2. Upgrade signal
A device might signal that it supports Local HTTPS, and which anchor it chains to, so that the user agent can try the upgrade or offer the matching trust ceremony. Such a signal would only be a hint and MUST NOT add an anchor or affect validation.
Define whether and how a device signals support. Candidates are tied to HTTP or TLS, for example a response header on http: in the spirit of HSTS and Alt-Svc, or the certificate chain presented when an https: connection is attempted. The IETF SETTLE working group may define one.
4. Scopes
The applicable anchors for a request are:
-
for a navigation the user initiated, such as from the address bar or a bookmark, every anchor in the local trust store;
-
for a request from an origin, only the anchors that origin holds a peer grant for, through acquire a local peer grant.
A peer grant covers part of a namespace, by default one device and its services, such as nas.local and *.nas.local. It acts as an extra name constraint, so a page granted one device can’t reach another device under the same referee.
The user agent MUST NOT resolve, connect to or probe a local host for a page outside its applicable anchors.
Which scope applies to navigations that a page starts?
Is a peer grant keyed by origin or by top-level site?
5. Origins, Fetch and Local Network Access
A local origin has the usual tuple, for example (https, nas.local, 443), and is a secure context. Because at most one key can certify a host, the tuple is unambiguous within a profile. A different nas device fails validation, and an unpaired http://nas.local is a different origin.
When a local trust anchor is removed, the user agent MUST clear site data for all hosts in its namespace.
Requests to local origins are ordinary requests [FETCH]: servers apply CORS based on the Origin header, and WebTransport servers check Origin [WEBTRANSPORT]. A peer grant satisfies the Local Network Access permission for the hosts it covers only. CSP is not extended: connect-src https://*.local works.
Note: Unlike "Expanding what HTTPS means", this doesn’t add the server’s key to the origin tuple; allowing at most one key per host already makes names unambiguous.
6. User interface
For a top-level local origin, the user agent SHOULD show a "paired device" indicator with the host, and the referee if any (for example "via Home"), outside the content area.
The user agent MUST NOT show a name supplied by the device unless it obtained the name after the trust ceremony authenticated the device.
7. Examples
This section is non-normative.
print.nas.local and media.nas.local. A page granted the NAS can use both.
*.home.local. The hub issues a device intermediate for *.nas.home.local, which issues service leaves. New devices work without pairing each one.
*.matter.local.
8. Security and privacy considerations
-
Only the key is verified. A valid path proves that the server holds a certificate chaining to an anchor the user accepted for that namespace, and nothing more.
-
URLs are per user.
https://nas.localmay mean a different device, or nothing, for another user. -
No probing. Pages can’t reach or detect devices outside their applicable anchors.
-
Key theft. A stolen anchor key compromises its namespace until the user removes the anchor. A compromised referee controls every name under it, hence explicit consent and a visible indicator. A referee never widens a page’s grants.
-
Linkability. A paired device can recognize the same browser across sites. That is inherent to pairing.