[tor-commits] [torspec/master] adds more descriptive subsections, changes section organization

[nickm at torproject.org]

commit f6149b3d2c3c587d21fb196cc1fc8f3b2dc698a5
Author: Chelsea H. Komlo <chelsea.komlo at gmail.com>
Date:   Tue Mar 14 16:12:57 2017 -0500

    adds more descriptive subsections, changes section organization
---
 glossary.txt | 105 +++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 88 insertions(+), 17 deletions(-)

diff --git a/glossary.txt b/glossary.txt
index ba4baeb..9f1bdc0 100644
--- a/glossary.txt
+++ b/glossary.txt
@@ -15,24 +15,76 @@ This glossary is not a design document; it is only a reference.
       "OPTIONAL" in this document are to be interpreted as described in
       RFC 2119.
 
-0.1 Commonly used Tor configuration terms
+1.0 Commonly used Tor configuration terms
 
    ORPort  - Onion Router Port
    DirPort - Directory Port
 
-0.2 Tor network components
+2.0 Tor network components
 
-   Relay, aka OR (onion router)  -
-     Exit relay
-     Non-exit relay
-     Guard relay
-   Client, aka OP (onion proxy)
+   2.1 Relay, aka OR (onion router)
 
-   Bridge  -
+    2.1.1 Specific roles
 
-   Circuit: An established path through the network, where cryptographic keys
-   are negotiated using the ntor protocol with each hop. Circuits can differ
-   in length depending on their purpose. See also Leaky Pipe Topology.
+      Exit relay: The final hop in an exit circuit before traffic leaves
+      the Tor network to connect to external servers.
+
+      Non-exit relay: Relays which send and receive traffic only to
+      other Tor relays.
+
+      Entry relay: The first hop in a Tor circuit. Can be either a guard
+      relay or a bridge, with bridges taking precedant.
+
+      Guard relay: Currently only used as entry relays. Guard relays
+      are rotated more slowly to prevent enumeration attacks.
+
+      Bridge: A relay intentionally not listed in the public Tor
+      consensus, with the purpose of circumventing entities (such as
+      governments or ISPs) seeking to block clients from using Tor.
+      Currently, bridges are used only as entry relays.
+
+      Directory cache: On bootstrap, clients will query a directory
+      authority for the latest consensus. However, later consensus
+      fetches can be made to directory caches, which can be any relay in
+      the network.
+
+      Rendezvous point: A relay connecting a client to a hidden service.
+      Each party will build a three-hop circuit, meeting at the
+      rendezvous point.
+
+   2.2 Client, aka OP (onion proxy)
+
+   2.3 Authorities:
+
+    Directory Authority: Nine total in the Tor network, operated by
+    trusted individuals. Directory authorities define and serve the
+    consensus document, i.e, the "state of the network," which contains
+    router statuses for all relays currently in the network. Directory
+    authorities also serve server descriptors, extra info documents,
+    microdescriptors, and the microdescriptor consensus,
+
+    Bridge Authority: One total. Similar in responsibility to directory
+    authorities, but for bridges.
+
+    Fallback Directory Mirror: On bootstrap, a client will first attempt
+    to fetch the consensus document from fallback directory mirrors,
+    a relay selected for this role due to its stability and longevity
+    on the network.
+
+   2.4 Hidden Service:
+
+   A hidden service is a server that will only accept incoming
+   connections via the hidden service protocol. Connection
+   initiators will not be able to learn the IP address of the hidden
+   service, allowing the hidden service to receive incoming connections,
+   serve content, etc, while preserving its location anonymity.
+
+   2.5 Circuit:
+
+   An established path through the network, where cryptographic keys
+   are negotiated using the ntor protocol or TAP (Tor Authentication
+   Protocol (deprecated) with each hop. Circuits can differ in length
+   depending on their purpose. See also Leaky Pipe Topology.
 
     Origin Circuit -
 
@@ -44,15 +96,34 @@ This glossary is not a design document; it is only a reference.
     network. For example, a client could connect to a hidden service via
     an internal circuit.
 
-   Stream
-   Edge connection:
+   2.6 Edge connection:
 
-   TLS connection:
+   2.7 Consensus: The state of the Tor network, published every hour,
+     decided by a vote from the network's directory authorities. Clients
+     fetch the consensus from directory authorities, fallback
+     directories, or directory caches.
 
+   2.8 Descriptor: Each descriptor represents information about one
+    relay in the Tor network. The descriptor includes the relay's IP
+    address, public key fingerprint, along with other data. Relays send
+    descriptors to directory authorities, who will vote and publish a
+    summary of them in the network consensus.
+
+3.0 Tor network protocols
    Link handshake
    Circuit handshake
+   Hidden Service Protocol
+   Directory Protocol
+
+
+4.0 General network definitions
+
+   Leaky Pipe Topology: The ability for packets to be addressed to any
+   hop in the path of a circuit. In Tor, the destination hop is
+   determined by using the recognized field of relay cells.
 
-   Leaky Pipe Topology: The ability for packets to be addressed to any hop
-   in the path of a circuit. The destination hop is determined by using the
-   recognized field of relay cells.
+   Stream: In the Tor network specifically, TCP streams are multiplexed
+   over circuits.
 
+   TLS connection: All pairwise connections in the Tor network are made
+   over TLS.