Rewrite DNS TXT record schema in the DNS DEP

1 files changed, 26 insertions, 6 deletions

diff --git a/proposals/0000-dns.md b/proposals/0000-dns.md
index 5c3b1ce..2e0b6b7 100644
--- a/proposals/0000-dns.md
+++ b/proposals/0000-dns.md
@@ -19,7 +19,7 @@ Dat's data structures (HyperCore, HyperDB, and HyperDrive) are addressed using
 cryptographic keys. In the context of Web browsers, a URL scheme is used which
 is structured as `'dat://' {key} '/' {path...}`.
 
-This DEP describes an additional protocol Dats using DNS short names.
+This DEP describes an additional protocol for addressing Dats using DNS short names.
 
 
 # Motivation
@@ -56,7 +56,17 @@ key:    dat://87ed2e3b160f261a032af03921a3bd09227d0a4cde73466c17114816cae43336/
 
 Users have multiple options for creating a domain-name mapping.
 
-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.
+## DNS TXT record
+[usage-dns-txt-record]: #usage-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
+[usage-wellknown-dat]: #usage-wellknown-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:
 
@@ -75,14 +85,20 @@ Resolution of a Dat at `dat://{name}` should follow 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"](#dns-over-https)).
- - Client iterates all TXT records given (skip if none). If a record's value matches the RegExp `^dat:\/\/[0-9a-f]{64}\/?$`:
-   - If the record includes a non-zero TTL, store the entry in the names cache.
-   - Return the entry.
+ - 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 entry in the names cache (default TTL to `3600` if not provided) and return the entry.
+   - 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:
 
@@ -91,6 +107,9 @@ The `/.well-known/dat` file must match this schema:
 ( '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
 [security-and-privacy]: #security-and-privacy
 
@@ -145,4 +164,5 @@ Whereas traditional DNS leaks name lookups to everyone on the network, DNS-over-
 [changelog]: #changelog
 
 - 2018-04-27: First complete draft submitted for review
+- 2018-05-07: Add "Security and Privacy" section and rewrite DNS TXT record schema.