1 files changed, 102 insertions, 0 deletions
diff --git a/spec/tor-spec/creating-circuits.md b/spec/tor-spec/creating-circuits.md
new file mode 100644
index 0000000..deb6b83
--- /dev/null
+++ b/spec/tor-spec/creating-circuits.md
@@ -0,0 +1,102 @@
+<a id="tor-spec.txt-5.3"></a>
+
+# Creating circuits{#creating-circuits}
+
+When creating a circuit through the network, the circuit creator
+(OP) performs the following steps:
+
+1. Choose an onion router as an end node (R_N):
+   * N MAY be 1 for non-anonymous directory mirror, introduction point,
+     or service rendezvous connections.
+   * N SHOULD be 3 or more for anonymous connections.
+   Some end nodes accept streams (see ["Opening streams"](./opening-streams.md)),
+   others are introduction or rendezvous points (see the [Rendezvous Spec](../rend-spec/index.md)).
+
+2. Choose a chain of (N-1) onion routers (R_1...R_N-1) to constitute
+   the path, such that no router appears in the path twice.
+
+3. If not already connected to the first router in the chain,
+   open a new connection to that router.
+
+4. Choose a circID not already in use on the connection with the
+   first router in the chain; send a CREATE/CREATE2 cell along
+   the connection, to be received by the first onion router.
+
+5. Wait until a CREATED/CREATED2 cell is received; finish the
+   handshake and extract the forward key Kf_1 and the backward
+   key Kb_1.
+
+6. For each subsequent onion router R (R_2 through R_N), extend
+   the circuit to R.
+
+To extend the circuit by a single onion router R_M, the OP performs
+these steps:
+
+1. Create an onion skin, encrypted to R_M's public onion key.
+
+2. Send the onion skin in a relay EXTEND/EXTEND2 message along
+   the circuit (see
+   ["EXTEND and EXTENDED messages"](./create-created-cells.md#EXTEND)
+   and ["Routing relay cells"](./routing-relay-cells.md#routing-relay-cells)).
+
+3. When a relay EXTENDED/EXTENDED2 message is received, verify KH,
+   and calculate the shared keys.  The circuit is now extended.
+
+When an onion router receives an EXTEND relay message, it sends a CREATE
+cell to the next onion router, with the enclosed onion skin as its
+body.
+
+When an onion router receives an EXTEND2 relay message, it sends a CREATE2
+cell to the next onion router, with the enclosed HLEN, HTYPE, and HDATA
+as its body. The initiating onion router chooses some circID not yet
+used on the connection between the two onion routers. (But see section
+["Choosing circuit IDs in create  cells"](./create-created-cells.md#choosing-circid))
+
+As special cases, if the EXTEND/EXTEND2 message includes a legacy identity, or
+identity fingerprint of all zeroes, or asks to extend back to the relay
+that sent the extend cell, the circuit will fail and be torn down.
+
+Ed25519 identity keys are not required in EXTEND2 messages, so all zero
+keys SHOULD be accepted. If the extending relay knows the ed25519 key from
+the consensus, it SHOULD also check that key. (See
+[EXTEND and EXTENDED message](./create-created-cells.md#EXTEND))
+
+If an EXTEND2 message contains the ed25519 key of the relay that sent the
+EXTEND2 message, the circuit will fail and be torn down.
+
+When an onion router receives a CREATE/CREATE2 cell, if it already has a
+circuit on the given connection with the given circID, it drops the
+cell. Otherwise, after receiving the CREATE/CREATE2 cell, it completes
+the specified handshake, and replies with a CREATED/CREATED2 cell.
+
+Upon receiving a CREATED/CREATED2 cell, an onion router packs its body
+into an [EXTENDED/EXTENDED2](./create-created-cells.md#EXTEND) relay message, and sends
+that message up the circuit. Upon receiving the EXTENDED/EXTENDED2 relay
+message, the OP can retrieve the handshake material.
+
+(As an optimization, OR implementations may delay processing onions
+until a break in traffic allows time to do so without harming
+network latency too greatly.)
+
+<a id="tor-spec.txt-5.3.1"></a>
+
+## Canonical connections{#canonical-connections}
+
+It is possible for an attacker to launch a man-in-the-middle attack
+against a connection by telling OR Alice to extend to OR Bob at some
+address X controlled by the attacker.  The attacker cannot read the
+encrypted traffic, but the attacker is now in a position to count all
+bytes sent between Alice and Bob (assuming Alice was not already
+connected to Bob.)
+
+To prevent this, when an OR gets an extend request, it SHOULD use an
+existing OR connection if the ID matches, and ANY of the following
+conditions hold:
+
+ - The IP matches the requested IP.
+ - The OR knows that the IP of the connection it's using is canonical
+   because it was listed in the NETINFO cell.
+
+ORs SHOULD NOT check the IPs that are listed in the server descriptor.
+Trusting server IPs makes it easier to covertly impersonate a relay, after
+stealing its keys.