diff options
Diffstat (limited to 'spec/dir-spec/directory-cache-operation.md')
-rw-r--r-- | spec/dir-spec/directory-cache-operation.md | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/spec/dir-spec/directory-cache-operation.md b/spec/dir-spec/directory-cache-operation.md new file mode 100644 index 0000000..14f9a9c --- /dev/null +++ b/spec/dir-spec/directory-cache-operation.md @@ -0,0 +1,167 @@ +<a id="dir-spec.txt-4"></a> + +# Directory cache operation + +All directory caches implement this section, except as noted. + +<a id="dir-spec.txt-4.1"></a> + +## Downloading consensus status documents from directory authorities { #download-ns-from-auth } + +All directory caches try to keep a recent +network-status consensus document to serve to clients. A cache ALWAYS +downloads a network-status consensus if any of the following are true: + +- The cache has no consensus document. +- The cache's consensus document is no longer valid. + +Otherwise, the cache downloads a new consensus document at a randomly +chosen time in the first half-interval after its current consensus +stops being fresh. (This time is chosen at random to avoid swarming +the authorities at the start of each period. The interval size is +inferred from the difference between the valid-after time and the +fresh-until time on the consensus.) + +```text + [For example, if a cache has a consensus that became valid at 1:00, + and is fresh until 2:00, that cache will fetch a new consensus at + a random time between 2:00 and 2:30.] +``` + +Directory caches also fetch consensus flavors from the authorities. +Caches check the correctness of consensus flavors, but do not check +anything about an unrecognized consensus document beyond its digest and +length. Caches serve all consensus flavors from the same locations as +the directory authorities. + +<a id="dir-spec.txt-4.2"></a> + +## Downloading server descriptors from directory authorities { #download-desc-from-auth } + +Periodically (currently, every 10 seconds), directory caches check +whether there are any specific descriptors that they do not have and that +they are not currently trying to download. Caches identify these +descriptors by hash in the recent network-status consensus documents. + +If so, the directory cache launches requests to the authorities for these +descriptors. + +If one of these downloads fails, we do not try to download that descriptor +from the authority that failed to serve it again unless we receive a newer +network-status consensus that lists the same descriptor. + +Directory caches must potentially cache multiple descriptors for each +router. Caches must not discard any descriptor listed by any recent +consensus. If there is enough space to store additional descriptors, +caches SHOULD try to hold those which clients are likely to download the +most. (Currently, this is judged based on the interval for which each +descriptor seemed newest.) + +\[XXXX define recent\] + +<a id="dir-spec.txt-4.3"></a> + +## Downloading microdescriptors from directory authorities { #download-md-from-auth } + +Directory mirrors should fetch, cache, and serve each microdescriptor +from the authorities. + +The microdescriptors with base64 hashes `<D1>`, `<D2>`, `<D3>` are available +at: + +`http://<hostname>/tor/micro/d/<D1>-<D2>-<D3>[.z]` + +`<Dn>` are base64 encoded with trailing =s omitted for size and for +consistency with the microdescriptor consensus format. -s are used +instead of +s to separate items, since the + character is used in +base64 encoding. + +Directory mirrors should check to make sure that the microdescriptors +they're about to serve match the right hashes (either the hashes from +the fetch URL or the hashes from the consensus, respectively). + +(NOTE: Due to squid proxy url limitations at most 92 microdescriptor hashes +can be retrieved in a single request.) + +<a id="dir-spec.txt-4.4"></a> + +## Downloading extra-info documents from directory authorities { #download-ei-from-auth } + +Any cache that chooses to cache extra-info documents should implement this +section. + +Periodically, the Tor instance checks whether it is missing any extra-info +documents: in other words, if it has any server descriptors with an +extra-info-digest field that does not match any of the extra-info +documents currently held. If so, it downloads whatever extra-info +documents are missing. Caches download from authorities. We follow the +same splitting and back-off rules as in section 4.2. + +<a id="dir-spec.txt-4.5"></a> + +## Consensus diffs { #diffs } + +Instead of downloading an entire consensus, clients may download +a "diff" document containing an ed-style diff from a previous +consensus document. Caches (and authorities) make these diffs as +they learn about new consensuses. To do so, they must store a +record of older consensuses. + +(Support for consensus diffs was added in 0.3.1.1-alpha, and is +advertised with the DirCache protocol version "2" or later.) + +<a id="dir-spec.txt-4.5.1"></a> + +### Consensus diff format { #diff-format } + +Consensus diffs are formatted as follows: + +The first line is "network-status-diff-version 1" NL + +The second line is + +"hash" SP FromDigest SP ToDigest NL + +where FromDigest is the hex-encoded SHA3-256 digest of the _signed +part_ of the consensus that the diff should be applied to, and +ToDigest is the hex-encoded SHA3-256 digest of the _entire_ +consensus resulting from applying the diff. (See 3.4.1 for +information on that part of a consensus is signed.) + +The third and subsequent lines encode the diff from FromDigest to +ToDigest in a limited subset of the ed diff format, as specified +in appendix E. + +<a id="dir-spec.txt-4.5.2"></a> + +### Serving and requesting diffs { #diff-requests } + +When downloading the current consensus, a client may include an +HTTP header of the form + +X-Or-Diff-From-Consensus: HASH1, HASH2, ... + +where the HASH values are hex-encoded SHA3-256 digests of the +_signed part_ of one or more consensuses that the client knows +about. + +If a cache knows a consensus diff from one of those consensuses +to the most recent consensus of the requested flavor, it may +send that diff instead of the specified consensus. + +Caches also serve diffs from the URIs: + +```text +/tor/status-vote/current/consensus/diff/<HASH>/<FPRLIST>.z +/tor/status-vote/current/consensus-<FLAVOR>/diff/<HASH>/<FPRLIST>.z +``` + +where FLAVOR is the consensus flavor, defaulting to "ns", and +FPRLIST is +-separated list of recognized authority identity +fingerprints as in appendix B. + +<a id="dir-spec.txt-4.6"></a> + +## Retrying failed downloads { #retry-as-cache } + +See section 5.5 below; it applies to caches as well as clients. |