From af0b62187a7284e1c3e54d6bafa4b73a74436a74 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Sat, 10 Feb 2024 22:37:48 +0000 Subject: [PATCH] Define blip-0032, DNSSEC proof querying over onion messages --- blip-0002.md | 11 +++++ blip-0032.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 blip-0032.md diff --git a/blip-0002.md b/blip-0002.md index 5efcc35..15ad52f 100644 --- 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 new file mode 100644 index 0000000..03782e0 --- /dev/null +++ b/blip-0032.md @@ -0,0 +1,122 @@ +``` +bLIP: 32 +Title: Onion Message DNS Resolution +Status: Active +Author: Matt Corallo +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 + + +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 +. + +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: