Skip to content

Commit

Permalink
Simplify language and fix spelling
Browse files Browse the repository at this point in the history
Include example algorithm.
  • Loading branch information
da2x committed Feb 18, 2019
1 parent 84e6270 commit cadd265
Showing 1 changed file with 15 additions and 13 deletions.
28 changes: 15 additions & 13 deletions proposals/0005-dns.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Resolution of a Dat at `dat://{name}` should follow this process:

- 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 TXT record schema (see below):
- Caache the record as described below.
- Cache the record as described below.
- 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.
Expand All @@ -114,27 +114,29 @@ Note that DNS-record responses may not follow a pre-defined order. Therefore the

Name cache lookup process:

Name cache entries has four qualifies: origin (domain name : port), Dat key, first seen timestamp, and expiration timestamp. Timestamps are in seconds since the Unix epoch.
Name cache entries have four qualifiers: origin (domain name : port), Dat key, first seen timestamp, and expiration timestamp. Timestamps are in seconds since the Unix epoch.

- Client must check if the origin is in the cache.
- If the origin is not in the cache, client must perform resolution for the origin using the method described above.
- If the domain doesn't resolve, the cache lookup returns a failed lookup.
- If the domain resolves, add the origin; Dat key; set the current time as first seen timestap, and set the expiration timestamp to exactly 30 minutes.
- If the origin is in the cache, client must check if the expiration timestamp is now or in the future.
- If the domain resolves: cache the origin and Dat key; set the current time as first seen timestap, and set the expiration timestamp to exactly 30 minutes.
- If the origin is in the cache, the client must check the expiration timestamp.
- If it's now or in the future, return the cached Dat key.
- Clients may oppertunisticly asyncronously renew cached entries that are ten minutes or less from expiring.
- Clients may opportunistically asyncronously renew cached entries that are ten minutes or less from expiring.
- If it's in the past, the client must resolve the origin using the method described above.
- If the resolution fails due to a server error (HTTP status code 5XX) or connection time out, and the expiration time is less than one week ago, return the cached Dat key.
- If the resolution fails due to a server error (HTTP status code 5XX) or a connection time out, or the server is unreachable, and the expiration time is less than one week ago, return the cached Dat key.
- If the resoluton fails for any other reason or the expiration time is more than one week ago, then the name record should be deleted from the cache and return a failed lookup.
- If the resolution succeeded then the client must compare the previously cached Dat key to the newly resolved Dat key.
- If the two keys differ, then the cached key is replaced; set the current time to the first seen timestamp, and set the expiration timestamp to exactly 30 minutes.
- If the two keys are identical, renew the cache expiration timestamp using the following criteria:
- First number: Subtract the first seen timestamp from the current time and multiply by two; add the resulting number to the current timestamp. Second number: add the resolved TTL to the current time.
- Client sets the expiration timestamp to the smaller of the two resulting numbers.
- Client should enforce a minimum expiration time of 30 minutes and a maximum of 6 months.
- Return the resolved Dat key.
- If the two keys differ, then the cached key is replaced: set the current time to the first seen timestamp, and set the expiration timestamp to exactly 30 minutes.
- If the two keys are identical, renew the cache expiration timestamp using the following algorithm:

`currentTime + max(30min, min(TTL, min(6months, (currentTime - firstSeen) * 2)))`
- Compare these two numbers and choose the smaller. First number: Subtract the first seen timestamp from the current time and multiply by two; add the resulting number to the current timestamp. Second number: add the resolved TTL to the current time.
- Adjust the number to be at least 30 minutes in the future and no more than 6 months.
- Set the resulting number as the new expiration timestamp.
- Return the resolved Dat key.
- Client should remove expired entries 30 days after expiration.
- After six months, client may set the first seen timestamp to the beginning of the Unix epoch.
- Client may discard the first seen timestamp by setting it to 0 after six months.

# Security and Privacy
[security-and-privacy]: #security-and-privacy
Expand Down

0 comments on commit cadd265

Please sign in to comment.