Merge pull request #32 from TheBlueMatt/2024-02-om-dns-resolution

Define blip-0032, DNSSEC proof querying over onion messages
lightning · Jun 3, 2024 · e9edaa2 · e9edaa2
2 parents b273c85 + af0b621
commit e9edaa2
Show file tree

Hide file tree

Showing 2 changed files with 133 additions and 0 deletions.
diff --git a/blip-0002.md b/blip-0002.md
@@ -34,6 +34,7 @@ network split.
   * [`init`](#init)
   * [`ping`](#ping)
   * [`update_add_htlc`](#update_add_htlc)
+* [Onion Messages](#onion-messages)
 
 ### Feature bits
 
@@ -48,6 +49,7 @@ bLIPs may reserve feature bits by adding them to the following table:
 | ---------   | ---------------------- | ------------------------------------------------- | ---------------- | -------------------------------- | -------------------------------- |
 | 54/55       | `keysend`              | A form of spontaneous payment                     | N                | `var_onion_optin`                | [bLIP 3](./blip-0003.md)         |
 | 256/257     | `hosted_channels`      | This node accepts requests for hosted channels    | IN               |                                  | [bLIP 17](./blip-0017.md)        |
+| 258/259     | `dns_resolver`         | This node accepts DNSSEC proof requests           | N                |                                  | [bLIP 32](./blip-0032.md)        |
 
 ### Messages
 
@@ -110,6 +112,15 @@ The following table contains extension tlv fields for the `ping` message:
 |-------|-----------------------------|--------------------------------|
 | 65536 | `tlv_field_name`            | Link to the corresponding bLIP |
 
+### Onion Messages
+
+The following table contains tlv fields for use in onion messages as the payload type:
+
+| Type  | Name                        | Link                           |
+|-------|-----------------------------|--------------------------------|
+| 65536 | `dnssec_query`              | [bLIP 32](./blip-0032.md)      |
+| 65538 | `dnssec_proof`              | [bLIP 32](./blip-0032.md)      |
+
 ## Copyright
 
 This bLIP is licensed under the CC0 license.
diff --git a/blip-0032.md b/blip-0032.md
@@ -0,0 +1,122 @@
+```
+bLIP: 32
+Title: Onion Message DNS Resolution
+Status: Active
+Author: Matt Corallo <[email protected]>
+Created: 2024-02-10
+License: CC0
+```
+
+## Abstract
+
+This bLIP defines a simple protocol by which a node can request a DNSSEC proof of TXT records at a
+given domain in the global DNS.
+
+## Copyright
+
+This bLIP is licensed under the CC0 license.
+
+## Specification
+
+Two new onion messages are defined, `dnssec_query` and `dnssec_proof`.
+
+1. type: 65536 (`dnssec_query`)
+2. data:
+    * [`u8`:`domain_name_len`]
+    * [`domain_name_len*byte`:`domain_name`]
+
+1. type: 65538 (`dnssec_proof`)
+2. data:
+    * [`u8`:`domain_name_len`]
+    * [`domain_name_len*byte`:`domain_name`]
+    * [`u16`:`proof_len`]
+    * [`proof_len*byte`:`proof`]
+
+Nodes which accept and reply to `dnssec_query`-containing onion messages from any sender:
+ * SHOULD set the `dns_resolver` feature flag in their `node_announcement`.
+
+Senders of a `dnssec_query`-containing onion message:
+ * MUST set `reply_path` in the `onionmsg_tlv` stream.
+ * MUST set `domain_name` to a canonical DNS name, i.e. it MUST be entirely printable ASCII and
+   MUST end in a ".".
+
+Recipients of a `dnssec_query`-containing onion message:
+ * SHOULD attempt to resolve the given `domain_name` into a TXT record response, considering any
+   relevant CNAME or DNAME records.
+ * MAY (but certainly are not required to) validate the required DNSSEC signatures required to
+   validate the query responses.
+ * SHOULD attempt to resolve the given `domain_name` into an RFC 9102-formatted DNSSEC proof (a
+   concatenated series of `AuthenticationChain` records, not including the `ExtSupportLifetime`
+   field at the start of a `DnssecChainExtension`).
+ * SHOULD return the RFC 9102-formatted DNSSEC proof proving the resulting TXT records in a
+   `dnssec_proof`-containing onion message to the sender using the provided `reply_path`.
+
+Senders of a `dnssec_proof`-containing onion message:
+ * MUST set the `domain_name` to the `domain_name` included in the `dnssec_query`-containing onion
+   message being responded to.
+
+Recipients of a `dnssec_proof`-containing onion message:
+ * MUST validate all DNSSEC signatures to ensure any contained records are signed in an unbroken
+   chain from the DNSSEC root trust anchor.
+ * MUST NOT rely on any signatures which rely on SHA-1 or RSA keys shorter than 1024 bits but MAY
+   accept SHA-1 DS records.
+ * MUST validate the inception and expiration timestamps of all signatures in the proof.
+
+## Discussion
+
+When resolving DNS-based payment instructions, lightning payers wish to resolve DNS names to TXT
+records (and associated DNSSEC proofs) in a private way. This bLIP defines a protocol by which
+payers can do so utilizing lightning's built-in onion messages, avoiding introducing any
+dependencies on native DNS resolution or directly-connected public DNS resolvers.
+
+### Overall Lightning Name Resolution Protocol
+
+The overall DNS-based lightning payment instruction resolution protocol is broken across three
+separate documents as parts are relevant to different stakeholders. The protocol was originally
+sketched in a mailing list post by Bastien at
+<https://lists.linuxfoundation.org/pipermail/lightning-dev/2023-November/004204.html>
+
+First of all, the DNSSEC name resolution is defined in a BIP as it is generic across Bitcoin
+payment instructions. A current draft may be found at
+<https://github.com/TheBlueMatt/bips/blob/2024-02-dns-payment-instructions/bip-XXXX.mediawiki>.
+
+Secondly, this document describes a method of fetching DNSSEC proofs without exiting the lightning
+network.
+
+Finally, a forthcoming bLIP will define a method to include the `user` part of the human-readable
+name used to look up an `offer` in the `invoice_request`.
+
+#### Payer Protocol
+
+A payer wishing to use these protocols to pay human-readable `user`-`domain` pairs first needs to
+be configured with resolver(s) implementing this bLIP. The payer could alternatively find such
+nodes by searching the lightning gossip network for nodes announcing the `dns_resolver` feature.
+
+To look up payment instructions given a `user`, `domain` pair, a payer sends their configured
+resolver a `dnssec_query`-containing onion message with a `domain_name` of
+`user`.user._bitcoin-payment.`domain`.
+
+Upon receipt of the responding `dnssec_proof` the payer validates the `proof` against the DNSSEC
+root trust anchor and if it passes parses any TXT records which
+`user`.user._bitcoin-payment.`domain` resolves to as a `bitcoin:` URI.
+
+From there, a lightning payer will search for (case-insensitive) the `lno` query parameter in the
+resulting URI. If it finds an `lno` query parameter, its value should contain a full offer, which
+the payer can simply pay.
+
+In order to allow for a static offer receiving funds on behalf of many users, the payer should
+include the `user` from their original query in the `invoice_request` they send the recipient.
+
+#### Recipient Configuration
+
+Recipient configuration is quite straightforward. For a recipient owning their own domain with a
+personal offer, they simply add a TXT record at `user`.user._bitcoin-payment.`domain` with the
+contents `bitcoin:?lno=OFFER`.
+
+Alternatively, for recipients which do not wish to publish a unique offer for all possible payees,
+a wildcard record may be provisioned as *.user._bitcoin-payment.`domain` with the same contents.
+The node receiving the `invoice_request` can use the `user` field to determine for which user the
+payment is intended and generate an `invoice` specific to that `user`.
+
+## Reference Implementation
+* LDK-based resolver: <https://git.bitcoin.ninja/index.cgi?p=lightning-resolver;a=summary>