path: root/spec/glossary.md

# Glossary

The Tor Project

This document aims to specify terms, notations, and phrases related
to Tor, as used in the Tor specification documents and other documentation.

This glossary is not a design document; it is only a reference.

This glossary is a work-in-progress; double-check its definitions before
citing them authoritatively. ;)

<a id="glossary.txt-0"></a>

## Preliminaries

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.

<a id="glossary.txt-1.0"></a>

## Commonly used Tor configuration terms { #configuration }

ORPort  - Onion Router Port
DirPort - Directory Port

<a id="glossary.txt-2.0"></a>

## Tor network components { #network-compoennts }

<a id="glossary.txt-2.1"></a>

## Relays, aka OR (onion router) { #relay}

\[Style guide: prefer the term "Relay"\]

<a id="glossary.txt-2.1.1"></a>

### Specific roles { #roles }

Exit relay: The final hop in an exit circuit before traffic leaves
the Tor network to connect to external servers.

Non-exit relay: Relays that send and receive traffic only to
other Tor relays and Tor clients.

Entry relay: The first hop in a Tor circuit. Can be either a guard
relay or a bridge, depending on the client's configuration.

Guard relay: A relay that a client uses as its entry for a longer
period of time.  Guard relays are rotated more slowly to prevent
attacks that can come from being exposed to too many guards.

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: A relay that downloads cached directory information
from the directory authorities and serves it to clients on demand.
Any relay will act as a directory cache, if its bandwidth is high enough.

Rendezvous point: A relay connecting a client to a hidden service.
Each party builds a three-hop circuit, meeting at the
rendezvous point.

<a id="glossary.txt-2.2"></a>

## Client, aka OP (onion proxy) { #client }

\[Style: the "OP" and "onion proxy" terms are deprecated.\]

<a id="glossary.txt-2.3"></a>

## Authorities { #authorities }

Directory Authority: Nine total in the Tor network, operated by
trusted individuals. Directory authorities define and serve the
consensus document, defining the "state of the network." This document
contains a "router status" section for every relay currently
in the network. Directory authorities also serve router 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: One of a list of directory caches distributed
with the Tor software. (When a client first connects to the network, and
has no directory information, it asks a fallback directory. From then on,
the client can ask any directory cache that's listed in the directory
information it has.)

<a id="glossary.txt-2.4"></a>

## Hidden Service { #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.

<a id="glossary.txt-2.5"></a>

## 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 -

Exit Circuit: A circuit which connects clients to destinations
outside the Tor network. For example, if a client wanted to visit
duckduckgo.com, this connection would require an exit circuit.

Internal Circuit: A circuit whose traffic never leaves the Tor
network. For example, a client could connect to a hidden service via
an internal circuit.

<a id="glossary.txt-2.6"></a>

## Edge connection

```text
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 keys, and other data. Relays send
    descriptors to directory authorities, who vote and publish a
    summary of them in the network consensus.
```

<a id="glossary.txt-3.0"></a>

## Tor network protocols

<a id="glossary.txt-3.1"></a>

## Messages and cells

Cell: A message sent over a channel. Every cell has an associated
command.  A cell may be fixed-length or variable-length, depending on
its command.  Cells are sometimes referred to by their command types:
for example, a cell whose command is `DESTROY` is called a
DESTROY cell.

Relay cell: A cell that tells a relay or client about instructions sent
over a circuit.  The command of a relay cell may be `RELAY` or `RELAY_EARLY`.
If we need to refer to a cell whose command is specifically `RELAY`,
we call it a "RELAY" cell.

Enveloped relay message: The results of decrypting a relay cell:
a relay message plus an associated (optional) StreamID.
(If the StreamID is not present, or zero,
then the relay message is addressed to the circuit itself
rather than to any particular stream on the circuit.)

Relay message: A message sent over a circuit to an individual stream,
or to the circuit itself. Relay messages are sometimes referred to
by their command types: for example, a message whose command is
`DATA` is sometimes called a DATA message.
Sometimes, relay messages are just called "Messages"
if no ambiguity would result.

> Note that when [prop340](proposals/340-packed-and-fragmented.md) is implemented,
> the relationship between relay cells and (enveloped) relay messages
> will no longer be 1:1.

## Link handshake

The link handshake establishes the TLS connection over which two
Tor participants will send Tor cells.  This handshake also
authenticates the participants to each other, possibly using Tor
cells.

<a id="glossary.txt-3.2"></a>

## Circuit handshake

Circuit handshakes establish the hop-by-hop onion encryption
that clients use to tunnel their application traffic.  The
client does a pairwise key establishment handshake with each
individual relay in the circuit.  For every hop except the
first, these handshakes tunnel through existing hops in the
circuit.  Each cell type in this protocol also has a newer
version (with a "2" suffix), e.g., CREATE2.

CREATE cell: First part of a handshake, sent by the initiator.

CREATED cell: Second part of a handshake, sent by the responder.

EXTEND message: (also known as a RELAY_EXTEND message) First part of a
handshake, tunneled through an existing circuit.  The last relay
in the circuit so far will process this message by
decoding it,
and sending the appropriate handshake
in a CREATED cell to the client's chosen next-hop relay.

EXTENDED cell: (also known as a RELAY_EXTENDED message) Second part
of a handshake, tunneled through an existing circuit.  The last
relay in the circuit so far receives the CREATED cell from the
new last-hop relay,
encodes that cell's body in in an EXTENDED message,
and uses a RELAY cell to deliver the message back to the client.
Upon receiving the EXTENDED message,
the client's circuit is one hop longer.

Onion skin: The body of a CREATE/CREATE2 cell or an EXTEND/EXTEND2 message.
It contains the first part of the TAP or ntor key establishment
handshake.

<a id="glossary.txt-3.3"></a>

## Hidden Service Protocol

<a id="glossary.txt-3.4"></a>

## Directory Protocol

<a id="glossary.txt-4.0"></a>

## General network definitions

Leaky Pipe Topology: The ability for the origin of a circuit to address
relay cells 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.

Stream: A single application-level connection or request, multiplexed over
a Tor circuit.  A 'Stream' can currently carry the contents of a TCP
connection, a DNS request, or a Tor directory request.

Channel: A pairwise connection between two Tor relays, or between a
client and a relay. Circuits are multiplexed over Channels. All
channels are currently implemented as TLS connections.