Finish revising cell-packet-format.

2 files changed, 27 insertions, 45 deletions

diff --git a/spec/tor-spec/cell-packet-format.md b/spec/tor-spec/cell-packet-format.md
index 5fdfea2..7975af4 100644
--- a/spec/tor-spec/cell-packet-format.md
+++ b/spec/tor-spec/cell-packet-format.md
@@ -138,11 +138,6 @@ to support a command.
 Commands with no value given for **P**
 are supported at least in link protocols 3 and above.
 
-Commands labeled with CircId? = N
-MUST must be sent with their `CircId` field set to 0.
-Commands labeled with CircId? = N
-MUST must be sent with a nonzero `CircId`.
-
 No other command values are allowed.
 Implementations SHOULD NOT send undefined command values.
 Upon receiving an unrecognized command,
@@ -164,48 +159,34 @@ and MAY terminate the channel with an error.
 > under the assumption that the command was sent
 > by a more up-to-date version of Tor.
 
+## Interpreting the fields: Payload {#payload}
 
-The interpretation of `Payload` depends on the type of the cell.
-
-* `VPADDING`/`PADDING`: Payload contains padding bytes.
-* `CREATE`/`CREATE2`:  Payload contains the handshake challenge.
-* `CREATED`/`CREATED2`: Payload contains the handshake response.
-* `RELAY`/`RELAY_EARLY`: Payload contains the relay header and relay body.
-* `DESTROY`: Payload contains a reason for closing the circuit. (see [Tearing down circuits](./tearing-down-circuits.md#tearing-down-circuits))
-
-The cell is padded up to the cell length with padding bytes.
-
-Senders set padding bytes depending on the cell's command:
+The interpretation of Payload depends on the cell's command.
+see the links in the command descriptions above
+for more information on each command.
 
-* `VERSIONS`:  `Payload` MUST NOT contain padding bytes.
-* `AUTHORIZE`: `Payload` is unspecified and reserved for future use.
-* Other variable-length cells:
-  * `Payload` MAY contain padding bytes at the end of the cell.
-  * Padding bytes SHOULD be set to NUL.
-* `RELAY`/`RELAY_EARLY`: `Payload` MUST be padded to `PAYLOAD_LEN` with padding bytes. Padding bytes SHOULD be set to random values.
-* Other fixed-length cells:
-  * `Payload` MUST be padded to `PAYLOAD_LEN` with padding bytes.
-  * Padding bytes SHOULD be set to NUL.
+## Padding fixed-length cell payloads {#payload-padding}
 
-We recommend random padding in `RELAY`/`RELAY_EARLY` cells, so that the cell
-content is unpredictable. See the format of relay cells in [Relay cells](./relay-cells.md#relay-cells)
-for detail.
+Often, the amount of information to be sent
+in a fixed-length cell
+is less than [`PAYLOAD_LEN`] bytes.
+When this happens,
+the sender MUST fill the unused part of the payload
+with zero-valued bytes.
 
-For other cells, TLS authenticates cell content, so randomized padding
-bytes are redundant.
+Recipients MUST ignore padding bytes.
 
-Receivers MUST ignore padding bytes.
-
-`PADDING` cells are currently used to implement connection keepalive.
-If there is no other traffic, ORs and OPs send one another a `PADDING`
-cell every few minutes.
-
-`CREATE`, `CREATE2`, `CREATED`, `CREATED2`, and `DESTROY` cells are used to
-manage circuits; see [Circuit management](./circuit-management.md#circuit-management).
+> [RELAY] and [RELAY_EARLY] cel payloads
+> contain encrypted data,
+> and are always full
+> from the point of the view of the channel layer.
+>
+> The _plaintext_ of these cells' contents may be padded;
+> this uses a [different mechanism](./relay-cells.md#relay-cell-padding)
+> and does not interact with channel payload padding.
 
-`RELAY` cells are used to send commands and data along a circuit; see
-[Application connections and stream management](./streams.md#application-connections-and-stream-management).
+Variable-length cells never have extra space,
+so there is no need to pad their payloads.
+Unless otherwise specified,
+variable-length cells have no padding.
 
-`VERSIONS` and `NETINFO` cells are used to set up connections in link
-protocols v2 and higher; in link protocol v3 and higher, `CERTS`,
-`AUTH_CHALLENGE`, and `AUTHENTICATE` may also be used.  See [Negotiating and initializing channels](./negotiating-channels.md#negotiating).
diff --git a/spec/tor-spec/relay-cells.md b/spec/tor-spec/relay-cells.md
index add1f42..9f1abb2 100644
--- a/spec/tor-spec/relay-cells.md
+++ b/spec/tor-spec/relay-cells.md
@@ -104,11 +104,12 @@ the unencrypted payload is padded with padding bytes. Implementations
 handle padding bytes of unencrypted relay cells as they do padding
 bytes for other cell types; see [Cell Packet format](./cell-packet-format.md#cell-packet-format).
 
-The 'Padding' field is used to make relay cell contents unpredictable, to
+<span id="relay-cell-padding">The
+'Padding' field is used to make relay cell contents unpredictable, to
 avoid certain attacks (see proposal 289 for rationale). Implementations
 SHOULD fill this field with four zero-valued bytes, followed by as many
 random bytes as will fit.  (If there are fewer than 4 bytes for padding,
-then they should all be filled with zero.
+then they should all be filled with zero.</span>
 
 Implementations MUST NOT rely on the contents of the 'Padding' field.