| Internet-Draft | Public Key Hash for Local Domains | December 2024 |
| Wing | Expires 2 July 2025 | [Page] |
This specification eliminates security warnings when connecting to local domains using TLS. Servers use a unique, long hostname which encodes their public key that the client validates against the public key presented in the TLS handshake.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://danwing.github.io/public-key-hash/draft-wing-settle-public-key-hash.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-wing-settle-public-key-hash/.¶
Discussion of this document takes place on the SETTLE mailing list (mailto:settle@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/settle/. Subscribe at https://www.ietf.org/mailman/listinfo/settle/.¶
Source for this draft and an issue tracker can be found at https://github.com/danwing/public-key-hash.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 2 July 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Browsers are progressively requiring secure origins for new capabilities and features ([secure-context]). As secure origins are only obtainable, today, with a certificate signed by a Certification Authority trusted by the client, this leaves out devices and networks which cannot easily obtain such certificates. Such inability is due to network topology (e.g., firewall), lack of domain ownership, or complicated procedures.¶
This draft discusses how a client can authenticate to HTTPS servers belonging to the local domain where the server name is a hash of the server's public key. By doing so, a secure origin can be established. This avoids the need for a certificate signed by a Certification Authority (CA) trusted by the client. This is a relaxed way of "doing HTTPS" for servers on the local domain.¶
Web browsers and other application clients store per-host state using the host name, including cached form data such as passwords, integrated and 3rd party password managers, cookies, and other data. When a name collision occurs (e.g., the same printer.local name on two different networks) the client cannot recognize a different host is being encountered. By creating a unique name, existing client software (browsers, password managers, client libraries) can continue storing origin-specific data for each of unique name.¶
A unique name is created by embedding the hash of the public key into the name itself. This achieves uniqueness and the encoding is also identifiable by the client to assist its validation of the server's public key (Section 4.1). Details on encoding the domain name are in Section 5.¶
Unique host names containing encoded public keys are awkward for users. This section describes how short names can also be advertised by servers and securely validated by clients, so that the short name is presented to users while the unique name is used for the TLS connection.¶
A server already advertising its long name using [DNS-SD] can also advertise its short name. The client needs to validate they are the same server, prior to allowing the user to interact with the short name. The client can do this validation by making two connections: one connection to the long name and another to the short name and verify they both return the same public key and that both TLS handshakes finish successfully (proving the server has possession of the associated private key). Advertising both names enables incremental deployment within a local domain at the expense of user confusion (two names per device, like a human named both "Bob" and "Richard") and on-the-wire inefficiency.¶
NOTE: Also to be considered is including both the unique and short host name in the SubjectAltName field of the server's certificate. This avoids an additional advertisement but has worse incremental deployment characteristics -- legacy software won't notice the other name in the SubjectAltName.¶
The client need only look for matching short name and unique name within the same TLD domain name (that is, if a unique name is advertised with a ".local" domain, the client does not need to look for its accompanying short name within ".internal").¶
To avoid the problems described in Section 2, the TLS data connection always uses the long name. Thus, after the client has validated the short name as described above and a user attempts to connect to the short name (by typing or by some other user interaction), the client instead makes a connection to the unique name. This reduces the integration changes within the client, as clients already separate server-specific data based on the server's hostname (e.g., Cookie Store API, Credential Management API, Web Bluetooth, Storage API, Push API, Notifications API, WebTransport API).¶
When clients connect to such a local domain name or IP address (Section 6) using TLS they examine if the domain name starts with a registered hash identifier in the second label and if the rest of that label consists of an appropriate-length encoded hash. If those conditions apply, the client performs certificate validation as described below.¶
Upon receipt of the server's certificate, the client validates validates the certificate ([RFC9525], [RFC5280], and Section 4.3.4 of [RFC9110] if using HTTPS). When performing such a connection to a local domain, the client might avoid warning about a self-signed certificate because the Certification Authority (CA) signature will certainly not be signed by a trusted CA. Rather, a more subtle indication might be warranted for TLS connections to a local domain, perhaps only the first time or perhaps each time. The client parses the returned certificate and extracts the public key and compares its hash with the hash contained in the hostname. If they match, the TLS session continues. If they do not match, the client might warn the user about the certificate (as is common today) or simply abort the TLS connection.¶
Protection against rogue servers on the local network is discussed in Section 7.1.¶
A server running on a local network (see Section 2) uses a unique host name that includes a hash of its public key. This unique name is encoded as described in Section 5. Existing servers might be configurable with such a hostname, without software changes.¶
Oftentimes, servers operating on a local network already advertise their presence using [DNS-SD] and should continue doing so, advertising their unique name that includes their public key hash and optionally also a shorter nickname (Section 3).¶
The general format is hostname, a period, a digit indicating the hash algorithm, and then the hash of the server's public key as shown in Figure 1. The binary hash output is base32 encoded (Section 6 of [RFC4648]) without trailing "=" padding. Currently only SHA256 hash is defined with the value "0" (Section 8). While base32 encoding is specified as uppercase, implementations should treat uppercase, lowercase, and mixed case the same. (Base32 encoding was chosen instead of base64 or base64url encoding to avoid their illegal hostname characters and their case preservation requirement.)¶
friendly-name = 1*63(ALPHA / DIGIT / "-")
hash-algorithm = DIGIT ; 0=SHA256
base32-digits = "2" / "3" / "4" / "5" / "6" / "7"
hash = 1*62(/ ALPHA / base32-digits )
; 62+1 octet limit from RFC1035
encoded-hostname = friendly-name "."
hash-algorithm
hash
An example encoding is shown in Appendix A.¶
This section defines the domain names and IP addresses considered "local".¶
The following domain name suffixes are considered "local":¶
Additionally, if any host resolves to a local IP address and connection is made to that address, those are also considered "local":¶
TODO: write more on security considerations¶
A client may also want to defend against rogue servers installed on the local domain. This requires legitimate servers be enrolled with a trusted system such as a local domain Certification Authority (e.g., [I-D.sweet-iot-acme]) and that enrollment verified.¶
Because the server's public key is encoded into its domain name, changing the public key would also change its domain name -- thus, its identity as known by client password managers and other configurations in clients (e.g., printer, SMB share, etc.). As such an identity change is extremely disruptive, it needs to be avoided. This means the public/private key pair on a server needs to stay static. The tradeoff is servers are vulnerable to their private keys being stolen and an active attacker intercepting traffic to that server. The alternatives are to continue using unencrypted communication to local servers, which is vulnerable to passive attack, or to condition users to validate self-signed certificates for local servers.¶
New registry for hash type, 0=SHA256. Extensions via IETF Action.¶
Server with private key in PEM format is:¶
-----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCOkTU8TOKW/IZ6 whhyhg+1I4u0jm019z4SVUKAwKyOtFPtoEvRGPdKYUoLaPZmVyN/VTYlubVn7dE8 IYpibwkDhs38DKmyo0vdWjUaopQOaygtLB+PZ12l/XaSCE1cWsl45ShUvktcVR/D DKwv7DWEIZrRTLKy6M+8Ne4x++kKXmwbSj8WsNQ4kU4uFhS+JXHXToZvhvoQLkTs 486XXPn4SJPLyTN62b6KHTLM1vb7RY4i4U7N6hS1UWe7bIxZNZ0vnf4vZ7A6SR7W nM31DoaW5XCBH7CL56MSdn7dmuksRimfNmnsEmvBXZmuQMHnUZghBLMHPC9xmHhT 8q3pSY5jAgMBAAECggEANiAY1vDVob7zi01/HJObCQkatAzSl4drUGiAHAOKP49k wbV2s0bIM7vl8ZkC2u3AM0p1iTMNFQzrv+l38VD4WhdmwodIMeLfHYVu3dLVZPf3 w9aZkMcMfcVRq7VtMV/iV3ygqDOqxr4mldWM1ZDW7HgZn9Z/jX7nxyuuZ9mcquuH Brl8pcUba7666jcz+F9NNjXTPCwfm7ihCPkTeYr1NflQGTR5PJ+D5dywb53iulm1 ZTk2zBXJMujbIyTL0p+MqdEKXci7oQJqf7bQsxsO2ZUD24CmzYldsE6vmYUFxJpw ZbYzO/a/Mv0mXQhcUTWKkJkU78QT2Us7SuSL+IPGSQKBgQDC5iRKtlYulUgxV9gu TmX30R0W7R0nnsEjolNAqUwcIoUMHk8ODXEsp7jVOSFMJhHRMXL+VKYiBsiIV7vk GlTbLRP34HgK54auRF6PTxBfNAkF+FQxl2mzWxj7wi5mg0g+tCJTLereUXULz8+r h5Vqp4BCjcoumlyY0xlLtbr9/wKBgQC7Qx2Lb70XCL5eivdokMh2lRint9cfxC2W fJ6QOnJgsN9XIQGTUAk3cLvmrKg3UOmJXXq+Q6djVB/3Op3+TFzsGS2ORMel9r6o kAHYG/qdairlW9uTDsnwUP8UtE0lidhSXLGIAy71eMDbDg/c/yyrWTvysXf5kAiJ CzTnyvY3nQKBgBt+Va5IbH3jxyxWxQM7Qf0kfaMHTe6R4ZMCShY8C6WIZRZhjCti UA3JlzRU+9J/KFJHVH52OH1iUZWSMsopwMCuaju0aZq4MHKS6Hf04k1bzM4Pyui4 AEwx1KNnMB579IwL4y+ysYgtG4LQDO6YkMZb3KcG03ehhOB2HwJkH33HAoGATOw3 8bQ3v4OG970r/lcjEZsTYqnhA5qJg3yzgdmQbGmbhOX5CLNi5dQ4S3x3KSnilNvC dO/DjcjbzKnWhsSFkzKQhRV50ZH3JbTqHQT5QLqA3nCKVPFJQJ90+ONLoXTrWIHd J1rvakRtLE6tc4GartRcDMib2PcymmDxHZpA4/0CgYEAs0XF1G0gmnef8oEYuwZT c+vr4wnD7YCP1h8nsNSgRHLk1e7k727iHGvruX3qrKsY26RHKi2+i1P6A39I4F5s 3Dme4HGXTyoc/qKp+/GAx5XYVG4c3Z3sdBejkpkhPTSlsSsDOHbjaiFV1zCyEdg5 fOPfIBX8uLc3UtOm0+Gn1IQ= -----END PRIVATE KEY-----¶
and public key in PEM format is:¶
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjpE1PEzilvyGesIYcoYP tSOLtI5tNfc+ElVCgMCsjrRT7aBL0Rj3SmFKC2j2Zlcjf1U2Jbm1Z+3RPCGKYm8J A4bN/AypsqNL3Vo1GqKUDmsoLSwfj2ddpf12kghNXFrJeOUoVL5LXFUfwwysL+w1 hCGa0UyysujPvDXuMfvpCl5sG0o/FrDUOJFOLhYUviVx106Gb4b6EC5E7OPOl1z5 +EiTy8kzetm+ih0yzNb2+0WOIuFOzeoUtVFnu2yMWTWdL53+L2ewOkke1pzN9Q6G luVwgR+wi+ejEnZ+3ZrpLEYpnzZp7BJrwV2ZrkDB51GYIQSzBzwvcZh4U/Kt6UmO YwIDAQAB -----END PUBLIC KEY-----¶
Using the binary format (DER) and hashed using SHA256 gives this hex value:¶
21ebc0d00e98e3cb289738e2c091e532c4ad8240e0365b22067a1449693e5a18¶
Converting that hex value to binary and base32 encoded (without trailing "=") gives:¶
EHV4BUAOTDR4WKEXHDRMBEPFGLCK3ASA4A3FWIQGPIKES2J6LIMA¶
After the hash algorithm identification digit (0 for SHA512/256) is prefixed to that base64url, resulting in:¶
0EHV4BUAOTDR4WKEXHDRMBEPFGLCK3ASA4A3FWIQGPIKES2J6LIMA¶
Finally, if this is a printer named "printer" advertised using ".local", the full FQDN for its unique name would be:¶
printer.0EHV4BUAOTDR4WKEXHDRMBEPFGLCK3ASA4A3FWIQGPIKES2J6LIMA.local¶
and the full FQDN for its short name would be "printer.local".¶
This draft was inspired by a document published by Martin Thomson in 2007; however, this draft takes a different approach by using unique names over the wire.¶
Other systems have also utilized public key hashes in an identifier including Tor and Freenet's Content Hash Key.¶
Thanks to Sridharan Rajagopalan for reviews and feedback.¶