Skip to content

Latest commit

 

History

History
122 lines (92 loc) · 5.44 KB

blip-0032.md

File metadata and controls

122 lines (92 loc) · 5.44 KB
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, BOLT 12 specifies the inclusion of name and domain parts in its invoice_requests.

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 and domain 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