Revise cell command tables.

1 files changed, 83 insertions, 32 deletions

diff --git a/spec/tor-spec/cell-packet-format.md b/spec/tor-spec/cell-packet-format.md
index 39e6009..5fdfea2 100644
--- a/spec/tor-spec/cell-packet-format.md
+++ b/spec/tor-spec/cell-packet-format.md
@@ -81,34 +81,89 @@ its `CircID` is set to 0.
 
 ## Interpreting the fields: Command {#command}
 
-The `Command` field of a fixed-length cell holds one of the following
-values:
-
-| Value | Identifier          | Description                             |
-|-------|---------------------|---------------------------------------  |
-| 0     | `PADDING`           | Padding (See [Link padding](./flow-control.md#link-padding)) |
-| 1     | `CREATE`            | Create a circuit (See [`CREATE` and `CREATED` cells](./create-created-cells.md#CREATE)) |
-| 2     | `CREATED`           | Acknowledge create  (See [`CREATE` and `CREATED` cells](./create-created-cells.md#CREATE))      |
-| 3     | `RELAY`             | End-to-end data (See [Routing relay cells](./routing-relay-cells.md#routing-relay-cells) and [Relay cells](./relay-cells.md#relay-cells))    |
-| 4     | `DESTROY`           | Stop using a circuit (See [Tearing down circuits](./tearing-down-circuits.md#tearing-down-circuits))     |
-| 5     | `CREATE_FAST`       | Create a circuit, no KP (See [`CREATE` and `CREATED` cells](./create-created-cells.md#CREATE)) |
-| 6     | `CREATED_FAST`      | Circuit created, no KP (See [`CREATE` and `CREATED` cells](./create-created-cells.md#CREATE))  |
-| 8     | `NETINFO`           | Time and address info (See [`NETINFO` cells](./negotiating-channels.md#NETINFO-cells))    |
-| 9     | `RELAY_EARLY`       | End-to-end data; limited (See [Handling `RELAY_EARLY` cells](./relay-early.md#handling-relay-early-cells)) |
-| 10    | `CREATE2`           | Extended CREATE cell (See [`CREATE` and `CREATED` cells](./create-created-cells.md#CREATE))     |
-| 11    | `CREATED2`          | Extended CREATED cell (See [`CREATE` and `CREATED` cells](./create-created-cells.md#CREATE))    |
-| 12    | `PADDING_NEGOTIATE` | Padding negotiation (See [Flow control](./flow-control.md#flow-control))      |
-
-Variable-length command values are:
-
-| Value | Identifier       | Description                           |
-|-------|------------------|-------------------------------------- |
-| 7     | `VERSIONS`       | Negotiate proto version (See [Negotiating versions with `VERSIONS` cells](./negotiating-channels.md#VERSIONS-cells))   |
-| 128   | `VPADDING`       | Variable-length padding (See [Flow control](./flow-control.md#flow-control)) |
-| 129   | `CERTS`          | Certificates (See [`CERTS cells`](./negotiating-channels.md#CERTS-cells))            |
-| 130   | `AUTH_CHALLENGE` | Challenge value (See [`AUTH_CHALLENGE` cells](./negotiating-channels.md#AUTH-CHALLENGE-cells))         |
-| 131   | `AUTHENTICATE`   | Client authentication (See [`AUTHENTICATE` cells](./negotiating-channels.md#AUTHENTICATE-cells))   |
-| 132   | `AUTHORIZE`      | Client authorization (Not yet used)   |
+The `Command` field of a fixed-length cell
+holds one of the following values:
+
+| Value |C|P| Identifier          | Description                             |
+|-------|-|-|---------------------|---------------------------------------  |
+| 0     |N| | `PADDING`           | [Link Padding][PADDING]                 |
+| 1     |Y| | `CREATE`            | [Create circuit][CREATE] (deprecated)   |
+| 2     |Y| | `CREATED`           | [Acknowledge CREATE][CREATED] (deprecated) |
+| 3     |Y| | `RELAY`             | [End-to-end data][RELAY]                |
+| 4     |Y| | `DESTROY`           | [Destroy circuit][DESTROY]              |
+| 5     |Y| | `CREATE_FAST`       | [Create circuit, no public key][CREATE_FAST] |
+| 6     |Y| | `CREATED_FAST`      | [Acknowledge CREATE_FAST][CREATED_FAST] |
+| 8     |N| | `NETINFO`           | [Time and address info][NETINFO]        |
+| 9     |Y| | `RELAY_EARLY`       | [End-to-end data; limited][RELAY_EARLY] |
+| 10    |Y| | `CREATE2`           | [Create circuit][CREATE2]               |
+| 11    |Y| | `CREATED2`          | [Acknowledge CREATED2][CREATED2]        |
+| 12    |Y|5| `PADDING_NEGOTIATE` | [Padding negotiation][PADDING_NEGOTIATE] |
+
+
+[PADDING]: ./flow-control.md#link-padding
+[CREATE]: ./create-created-cells.md#CREATE
+[CREATED]: ./create-created-cells.md#CREATE
+[RELAY]: ./routing-relay-cells.md#routing-relay-cells
+[DESTROY]: ./tearing-down-circuits.md#tearing-down-circuits
+[CREATE_FAST]: ./create-created-cells.md#create_fast
+[CREATED_FAST]: ./create-created-cells.md#create_fast
+[NETINFO]: ./negotiating-channels.md#NETINFO-cells
+[RELAY_EARLY]: ./relay-early.md#handling-relay-early-cells
+[CREATE2]: ./create-created-cells.md#CREATE
+[CREATED2]: ./create-created-cells.md#CREATE
+[PADDING_NEGOTIATE]: ./flow-control.md#link-padding
+
+The variable-length `Command` values are:
+
+| Value |C|P| Identifier       | Description                            |
+|-------|-|-|------------------|----------------------------------------|
+| 7     |N| | `VERSIONS`       | [Negotiate link protocol][VERSIONS]    |
+| 128   |N| | `VPADDING`       | [Variable-length padding][VPADDING]    |
+| 129   |N| | `CERTS`          | [Certificates][CERTS]                  |
+| 130   |N| | `AUTH_CHALLENGE` | [Challenge value][AUTH_CHALLENGE]      |
+| 131   |N| | `AUTHENTICATE`   | [Authenticate initiator][AUTHENTICATE] |
+| 132   |N|n/a| `AUTHORIZE`  | (Reserved)                             |
+
+[VERSIONS]: ./negotiating-channels.md#VERSIONS-cells
+[VPADDING]: ./flow-control.md#link-padding
+[CERTS]: ./negotiating-channels.md#CERTS-cell
+[AUTH_CHALLENGE]: ./negotiating-channels.md#AUTH-CHALLENGE-cells
+[AUTHENTICATE]: ./negotiating-channels.md#AUTHENTICATE-cells
+
+In the tables above,
+**C**=Y indicates that a command must have a nonzero CircId, and
+**C**=N indicates that a command must have a zero CircId.
+Where given, **P** is the first link protocol version
+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,
+an implementation MAY silently drop the cell
+and MAY terminate the channel with an error.
+
+> Extensibility note:
+>
+> When we add new cell command types,
+> we define a new link protocol version
+> to indicate support for that command.
+>
+> Therefore, implementations can now safely assume
+> that other correct implementations
+> will never send them an unrecognized cell command.
+>
+> Historically, before the link protocol was not versioned,
+> implementations would drop cells with unrecognized commands,
+> under the assumption that the command was sent
+> by a more up-to-date version of Tor.
+
 
 The interpretation of `Payload` depends on the type of the cell.
 
@@ -118,10 +173,6 @@ The interpretation of `Payload` depends on the type of the cell.
 * `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))
 
-Upon receiving any other value for the command field, an OR must
-drop the cell.  Since more cell types may be added in the future, ORs
-should generally not warn when encountering unrecognized commands.
-
 The cell is padded up to the cell length with padding bytes.
 
 Senders set padding bytes depending on the cell's command: