1 files changed, 141 insertions, 0 deletions
diff --git a/spec/tor-spec/opening-streams.md b/spec/tor-spec/opening-streams.md
new file mode 100644
index 0000000..81e1616
--- /dev/null
+++ b/spec/tor-spec/opening-streams.md
@@ -0,0 +1,141 @@
+<a id="tor-spec.txt-6.2"></a>
+
+# Opening streams and transmitting data
+
+## Opening a new stream: The begin/connected handshake {#opening}
+
+To open a new anonymized TCP connection, the OP chooses an open
+circuit to an exit that may be able to connect to the destination
+address, selects an arbitrary StreamID not yet used on that circuit,
+and constructs a RELAY_BEGIN message with a body encoding the address
+and port of the destination host.  The body format is:
+
+```text
+         ADDRPORT [nul-terminated string]
+         FLAGS    [4 bytes, optional]
+
+   ADDRPORT is made of ADDRESS | ':' | PORT | [00]
+```
+
+where  ADDRESS can be a DNS hostname, or an IPv4 address in
+dotted-quad format, or an IPv6 address surrounded by square brackets;
+and where PORT is a decimal integer between 1 and 65535, inclusive.
+
+The ADDRPORT string SHOULD be sent in lower case, to avoid
+fingerprinting.  Implementations MUST accept strings in any case.
+
+The FLAGS value has one or more of the following bits set, where
+"bit 1" is the LSB of the 32-bit value, and "bit 32" is the MSB.
+(Remember that
+[all integers in Tor are big-endian](../intro/conventions.md),
+so
+the MSB of a 4-byte value is the MSB of the first byte, and the LSB
+of a 4-byte value is the LSB of its last byte.)
+
+If FLAGS is absent, its value is 0.  Whenever 0 would be sent for
+FLAGS, FLAGS is omitted from the message body.
+
+```text
+     bit   meaning
+      1 -- IPv6 okay.  We support learning about IPv6 addresses and
+           connecting to IPv6 addresses.
+      2 -- IPv4 not okay.  We don't want to learn about IPv4 addresses
+           or connect to them.
+      3 -- IPv6 preferred.  If there are both IPv4 and IPv6 addresses,
+           we want to connect to the IPv6 one.  (By default, we connect
+           to the IPv4 address.)
+      4..32 -- Reserved. Current clients MUST NOT set these. Servers
+           MUST ignore them.
+```
+
+Upon receiving this message, the exit node resolves the address as
+necessary, and opens a new TCP connection to the target port.  If the
+address cannot be resolved, or a connection can't be established, the
+exit node replies with a RELAY_END message.  (See
+["Closing streams"](./closing-streams.md#closing-streams).)
+Otherwise, the exit node replies with a RELAY_CONNECTED message, whose
+body is in one of the following formats:
+
+```text
+       The IPv4 address to which the connection was made [4 octets]
+       A number of seconds (TTL) for which the address may be cached [4 octets]
+
+    or
+
+       Four zero-valued octets [4 octets]
+       An address type (6)     [1 octet]
+       The IPv6 address to which the connection was made [16 octets]
+       A number of seconds (TTL) for which the address may be cached [4 octets]
+```
+
+Implementations MUST accept either of these formats,
+and MUST also accept an empty RELAY_CONNECTED message body.
+
+Implmentations MAY ignore the address value,
+and MAY choose not to cache it.
+If an implementation chooses to cache the address,
+it SHOULD NOT reuse that address with any other circuit.
+
+> The reason not to cache an address
+> is that the exit might have lied about the actual address of the host,
+> or might have given us a unique address to identify us in the future.
+
+\[Tor exit nodes before 0.1.2.0 set the TTL field to a fixed value.  Later
+versions set the TTL to the last value seen from a DNS server, and expire
+their own cached entries after a fixed interval.  This prevents certain
+attacks.\]
+
+## Transmitting data {#transmitting}
+
+Once a connection has been established, the OP and exit node
+package stream data in RELAY_DATA message, and upon receiving such
+messages, echo their contents to the corresponding TCP stream.
+
+If the exit node does not support optimistic data (i.e. its
+version number is before 0.2.3.1-alpha), then the OP MUST wait
+for a RELAY_CONNECTED message before sending any data.  If the exit
+node supports optimistic data (i.e. its version number is
+0.2.3.1-alpha or later), then the OP MAY send RELAY_DATA messages
+immediately after sending the RELAY_BEGIN message (and before
+receiving either a RELAY_CONNECTED or RELAY_END message).
+
+RELAY_DATA messages sent to unrecognized streams are dropped.  If
+the exit node supports optimistic data, then RELAY_DATA messages it
+receives on streams which have seen RELAY_BEGIN but have not yet
+been replied to with a RELAY_CONNECTED or RELAY_END are queued.
+If the stream creation succeeds with a RELAY_CONNECTED, the queue
+is processed immediately afterwards; if the stream creation fails
+with a RELAY_END, the contents of the queue are deleted.
+
+Relay RELAY_DROP messages are long-range dummies; upon receiving such
+a message, the OR or OP must drop it.
+
+<a id="tor-spec.txt-6.2.1"></a>
+
+## Opening a directory stream
+
+If a Tor relay is a directory server, it should respond to a
+RELAY_BEGIN_DIR message as if it had received a BEGIN message requesting a
+connection to its directory port.  RELAY_BEGIN_DIR message ignore exit
+policy, since the stream is local to the Tor process.
+
+Directory servers may be:
+
+- authoritative directories (RELAY_BEGIN_DIR, usually non-anonymous),
+- bridge authoritative directories (RELAY_BEGIN_DIR, anonymous),
+- directory mirrors (RELAY_BEGIN_DIR, usually non-anonymous),
+- onion service directories (RELAY_BEGIN_DIR, anonymous).
+
+If the Tor relay is not running a directory service, it should respond
+with a REASON_NOTDIRECTORY RELAY_END message.
+
+Clients MUST generate a empty body for RELAY_BEGIN_DIR message;
+relays MUST ignore the the body of a RELAY_BEGIN_DIR message.
+
+In response to a RELAY_BEGIN_DIR message, relays respond either with a
+RELAY_CONNECTED message on success, or a RELAY_END message on failure.
+They MUST send a RELAY_CONNECTED message with an empty body;
+clients MUST ignore the body.
+
+\[RELAY_BEGIN_DIR was not supported before Tor 0.1.2.2-alpha; clients
+SHOULD NOT send it to routers running earlier versions of Tor.\]