Skip to content

Dat DNS TXT records with optional DNS over HTTPS

Jump to bottom
Alexander Frick edited this page Feb 5, 2024 · 1 revision

Reproduced from the official DEP spec

Motivation

The cryptographic keys which address Dats are secure and global, but not human-readable. This creates a usability problem. Beaker leverages DNS to provide human-readable shortnames which map to Dat's cryptographic addresses.

Users have multiple options for creating a domain-name mapping.

DNS TXT record

The first option is to set a DNS TXT record at the domain which maps to a "key"-addressed Dat URL. The client will lookup this TXT record first and load the resulting Dat. That record should fit the following schema:

datkey={key}

.well-known/dat

The second option is to run an HTTPS server at the domain name which includes a /.well-known/dat resource. That resource should provide a text file with the following schema:

dat://{key}
TTL={time in seconds}

TTL is optional and will default to 3600 (one hour). If set to 0, the entry is not cached.

Resolution process

Resolution of a Dat at dat://{name} follows this process:

  • Client checks its names cache. If a non-expired entry is found, return with the entry.
  • Client issues a DNS TXT request for name. This request should be issued via a secure transport (see "DNS-over-HTTPS").
  • Client iterates all TXT records given (skip if none). If a record's value matches the TXT record schema (see below):
    • If the record includes a non-zero TTL, store the record value in the names cache.
    • Return the record value.
  • Client issues an HTTPS GET request to https://{name}/.well-known/dat.
    • If the server responds with a 404 Not Found status, client stores a null entry in the names cache with a TTL of 3600 and returns a failed lookup.
    • If the server responds with anything other than a 200 OK status, return a failed lookup.
    • If the server responds with a malformed file (see below), return a failed lookup.
    • If the server responds with a well-formed file, store the record value in the names cache (default TTL to 3600 if not provided) and return the record value.

The DNS TXT record must match this schema:

'datkey=' [0-9a-f]{64}

The /.well-known/dat file must match this schema:

'dat://' [0-9a-f]{64} '/'?
( 'TTL=' [0-9]* )?

Note that DNS-record responses may not follow a pre-defined order. Therefore the results of a lookup may be undefined if multiple TXT records exist.

Security and Privacy

Two issues to consider:

  • Security: Can we trust the lookup results for a name?
  • Privacy: Who sees the DNS lookups?

Traditional DNS provides neither security or privacy. All looks occur over plaintext UDP. To provide security, a separate system must authenticate the record. (In the case of HTTPS records, the SSL Certificate provides authentication.)

Dat does not currently have a DNS authentication record (no equivalent to the SSL certificate). Therefore a lookup using UDP can not be secured.

We either use the .well-known lookup described above (which is encrypted via HTTPS) or, in the case of the TXT lookup, we use DNS-over-HTTPS.

Clone this wiki locally