Skip to content

Commit e9edaa2

Browse files
TheBlueMattTheBlueMatt
authored
Merge pull request #32 from TheBlueMatt/2024-02-om-dns-resolution
Define blip-0032, DNSSEC proof querying over onion messages
2 parents b273c85 + af0b621 commit e9edaa2

File tree

2 files changed

+133
-0
lines changed

2 files changed

+133
-0
lines changed

‎blip-0002.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ network split.
3434
* [`init`](#init)
3535
* [`ping`](#ping)
3636
* [`update_add_htlc`](#update_add_htlc)
37+
* [Onion Messages](#onion-messages)
3738

3839
### Feature bits
3940

@@ -48,6 +49,7 @@ bLIPs may reserve feature bits by adding them to the following table:
4849
| --------- | ---------------------- | ------------------------------------------------- | ---------------- | -------------------------------- | -------------------------------- |
4950
| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) |
5051
| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) |
52+
| 258/259 | `dns_resolver` | This node accepts DNSSEC proof requests | N | | [bLIP 32](./blip-0032.md) |
5153

5254
### Messages
5355

@@ -110,6 +112,15 @@ The following table contains extension tlv fields for the `ping` message:
110112
|-------|-----------------------------|--------------------------------|
111113
| 65536 | `tlv_field_name` | Link to the corresponding bLIP |
112114

115+
### Onion Messages
116+
117+
The following table contains tlv fields for use in onion messages as the payload type:
118+
119+
| Type | Name | Link |
120+
|-------|-----------------------------|--------------------------------|
121+
| 65536 | `dnssec_query` | [bLIP 32](./blip-0032.md) |
122+
| 65538 | `dnssec_proof` | [bLIP 32](./blip-0032.md) |
123+
113124
## Copyright
114125

115126
This bLIP is licensed under the CC0 license.

‎blip-0032.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
```
2+
bLIP: 32
3+
Title: Onion Message DNS Resolution
4+
Status: Active
5+
Author: Matt Corallo <[email protected]>
6+
Created: 2024-02-10
7+
License: CC0
8+
```
9+
10+
## Abstract
11+
12+
This bLIP defines a simple protocol by which a node can request a DNSSEC proof of TXT records at a
13+
given domain in the global DNS.
14+
15+
## Copyright
16+
17+
This bLIP is licensed under the CC0 license.
18+
19+
## Specification
20+
21+
Two new onion messages are defined, `dnssec_query` and `dnssec_proof`.
22+
23+
1. type: 65536 (`dnssec_query`)
24+
2. data:
25+
* [`u8`:`domain_name_len`]
26+
* [`domain_name_len*byte`:`domain_name`]
27+
28+
1. type: 65538 (`dnssec_proof`)
29+
2. data:
30+
* [`u8`:`domain_name_len`]
31+
* [`domain_name_len*byte`:`domain_name`]
32+
* [`u16`:`proof_len`]
33+
* [`proof_len*byte`:`proof`]
34+
35+
Nodes which accept and reply to `dnssec_query`-containing onion messages from any sender:
36+
* SHOULD set the `dns_resolver` feature flag in their `node_announcement`.
37+
38+
Senders of a `dnssec_query`-containing onion message:
39+
* MUST set `reply_path` in the `onionmsg_tlv` stream.
40+
* MUST set `domain_name` to a canonical DNS name, i.e. it MUST be entirely printable ASCII and
41+
MUST end in a ".".
42+
43+
Recipients of a `dnssec_query`-containing onion message:
44+
* SHOULD attempt to resolve the given `domain_name` into a TXT record response, considering any
45+
relevant CNAME or DNAME records.
46+
* MAY (but certainly are not required to) validate the required DNSSEC signatures required to
47+
validate the query responses.
48+
* SHOULD attempt to resolve the given `domain_name` into an RFC 9102-formatted DNSSEC proof (a
49+
concatenated series of `AuthenticationChain` records, not including the `ExtSupportLifetime`
50+
field at the start of a `DnssecChainExtension`).
51+
* SHOULD return the RFC 9102-formatted DNSSEC proof proving the resulting TXT records in a
52+
`dnssec_proof`-containing onion message to the sender using the provided `reply_path`.
53+
54+
Senders of a `dnssec_proof`-containing onion message:
55+
* MUST set the `domain_name` to the `domain_name` included in the `dnssec_query`-containing onion
56+
message being responded to.
57+
58+
Recipients of a `dnssec_proof`-containing onion message:
59+
* MUST validate all DNSSEC signatures to ensure any contained records are signed in an unbroken
60+
chain from the DNSSEC root trust anchor.
61+
* MUST NOT rely on any signatures which rely on SHA-1 or RSA keys shorter than 1024 bits but MAY
62+
accept SHA-1 DS records.
63+
* MUST validate the inception and expiration timestamps of all signatures in the proof.
64+
65+
## Discussion
66+
67+
When resolving DNS-based payment instructions, lightning payers wish to resolve DNS names to TXT
68+
records (and associated DNSSEC proofs) in a private way. This bLIP defines a protocol by which
69+
payers can do so utilizing lightning's built-in onion messages, avoiding introducing any
70+
dependencies on native DNS resolution or directly-connected public DNS resolvers.
71+
72+
### Overall Lightning Name Resolution Protocol
73+
74+
The overall DNS-based lightning payment instruction resolution protocol is broken across three
75+
separate documents as parts are relevant to different stakeholders. The protocol was originally
76+
sketched in a mailing list post by Bastien at
77+
<https://lists.linuxfoundation.org/pipermail/lightning-dev/2023-November/004204.html>
78+
79+
First of all, the DNSSEC name resolution is defined in a BIP as it is generic across Bitcoin
80+
payment instructions. A current draft may be found at
81+
<https://github.com/TheBlueMatt/bips/blob/2024-02-dns-payment-instructions/bip-XXXX.mediawiki>.
82+
83+
Secondly, this document describes a method of fetching DNSSEC proofs without exiting the lightning
84+
network.
85+
86+
Finally, a forthcoming bLIP will define a method to include the `user` part of the human-readable
87+
name used to look up an `offer` in the `invoice_request`.
88+
89+
#### Payer Protocol
90+
91+
A payer wishing to use these protocols to pay human-readable `user`-`domain` pairs first needs to
92+
be configured with resolver(s) implementing this bLIP. The payer could alternatively find such
93+
nodes by searching the lightning gossip network for nodes announcing the `dns_resolver` feature.
94+
95+
To look up payment instructions given a `user`, `domain` pair, a payer sends their configured
96+
resolver a `dnssec_query`-containing onion message with a `domain_name` of
97+
`user`.user._bitcoin-payment.`domain`.
98+
99+
Upon receipt of the responding `dnssec_proof` the payer validates the `proof` against the DNSSEC
100+
root trust anchor and if it passes parses any TXT records which
101+
`user`.user._bitcoin-payment.`domain` resolves to as a `bitcoin:` URI.
102+
103+
From there, a lightning payer will search for (case-insensitive) the `lno` query parameter in the
104+
resulting URI. If it finds an `lno` query parameter, its value should contain a full offer, which
105+
the payer can simply pay.
106+
107+
In order to allow for a static offer receiving funds on behalf of many users, the payer should
108+
include the `user` from their original query in the `invoice_request` they send the recipient.
109+
110+
#### Recipient Configuration
111+
112+
Recipient configuration is quite straightforward. For a recipient owning their own domain with a
113+
personal offer, they simply add a TXT record at `user`.user._bitcoin-payment.`domain` with the
114+
contents `bitcoin:?lno=OFFER`.
115+
116+
Alternatively, for recipients which do not wish to publish a unique offer for all possible payees,
117+
a wildcard record may be provisioned as *.user._bitcoin-payment.`domain` with the same contents.
118+
The node receiving the `invoice_request` can use the `user` field to determine for which user the
119+
payment is intended and generate an `invoice` specific to that `user`.
120+
121+
## Reference Implementation
122+
* LDK-based resolver: <https://git.bitcoin.ninja/index.cgi?p=lightning-resolver;a=summary>

0 commit comments

Comments
 (0)