From cadd2651b7a5f20dcd3732527c3fab2db0278fa7 Mon Sep 17 00:00:00 2001 From: Daniel Aleksandersen Date: Mon, 18 Feb 2019 20:01:49 +0100 Subject: [PATCH] Simplify language and fix spelling Include example algorithm. --- proposals/0005-dns.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/proposals/0005-dns.md b/proposals/0005-dns.md index 83e5a3c..e223937 100644 --- a/proposals/0005-dns.md +++ b/proposals/0005-dns.md @@ -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. @@ -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