lightning-blips/blip-0032.md

bLIP: 32
Title: Onion Message DNS Resolution
Status: Active
Author: Matt Corallo <blmmesg@bluematt.me>
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]

3. type: 65538 (dnssec_proof)

4. 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/bitcoin/bips/blob/master/bip-0353.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