Subject: [quicwg/base-drafts] Rearrange Packet Types section and references (#2203)

From: Mike Bishop <[email-masked]>
Date: Mon, 17 Dec 2018 16:21:11 -0800

Fixes #2165, #2157, and probably some others as well.  Trying to fix one thing wound up pulling on some other pieces as well, so this is larger than I intended.

Key changes are:
- Added discussion of 0-RTT Protected Packets, which were mysteriously absent, to Section 17
- Moved discussion of starting packet numbers for each space from the Initial Packet definition to the existing Packet Numbers section (17.1)
- Moved Short Header packets to end of 17 (from 17.3 to 17.8) to get all the long-header packet types together
- Removed the non-invariant fields (Length, Packet Number, Payload) from the definition of the Long Header and made them type-specific fields for those packets which contain them; this reduces explanation for packet types which don't
- Reordered forward references in Section 10 so the references in each paragraph are to sequential sections, with some text updates to accommodate the new order

If a comparison of the output doc is more useful than the Markdown diff, try [the output diff](https://tools.ietf.org/rfcdiff?url1=https://quicwg.github.io/base-drafts/draft-ietf-quic-transport.txt&url2=https://quicwg.github.io/base-drafts/transport/packet-types/draft-ietf-quic-transport.txt) or the [resulting document](https://quicwg.github.io/base-drafts/transport/packet-types/draft-ietf-quic-transport.html).
You can view, comment on, or merge this pull request online at:

  https://github.com/quicwg/base-drafts/pull/2203

-- Commit Summary --

  * Move packet number discussion
  * Rearrange Section 17
  * Update Section 12
  * Version negotiation doesn't "appear to" use the long header, it actually does

-- File Changes --

    M draft-ietf-quic-transport.md (443)

-- Patch Links --

https://github.com/quicwg/base-drafts/pull/2203.patch
https://github.com/quicwg/base-drafts/pull/2203.diff

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203

---

From: Nick Banks <[email-masked]>
Date: Tue, 18 Dec 2018 14:23:47 +0000 (UTC)

nibanks commented on this pull request.

Everything looks good besides the one comment/question I had on the starting packet number.

> @@ -2658,7 +2663,7 @@ level and can only be acknowledged in Handshake packets.
 
 This enforces cryptographic separation between the data sent in the different
 packet sequence number spaces.  Each packet number space starts at packet number
-0.  Subsequent packets sent in the same packet number space MUST increase the
+1.  Subsequent packets sent in the same packet number space MUST increase the

Why was this changed from `0` to `1`? Other places in the text still say packet numbers start at `0`.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#pullrequestreview-186091071

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 21:32:03 +0000 (UTC)

MikeBishop commented on this pull request.

Bah, my editor sometimes does this and I don't catch it.  Let me correct that.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r242713124

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 13:32:47 -0800

@MikeBishop pushed 1 commit.

dd515b6e7dd99980facb1402ebe184f8056817df  Why does this keep changing?

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/506b387f7be997e4fbf467aa612d0b67a748cd47..dd515b6e7dd99980facb1402ebe184f8056817df

---

From: ianswett <[email-masked]>
Date: Tue, 18 Dec 2018 13:40:45 -0800

ianswett commented on this pull request.

> @@ -2602,10 +2600,17 @@ each packet sent, see {{packet-numbers}} for details.
 
 ## Coalescing Packets {#packet-coalesce}
 
-A sender can coalesce multiple QUIC packets into one UDP datagram.  This can
-reduce the number of UDP datagrams needed to complete the cryptographic
-handshake and starting sending data.  Receivers MUST be able to process
-coalesced packets.
+Initial ({{packet-initial}}), 0-RTT Protected ({{packet-0rtt}}), and Handshake
+({{packet-handshake}}) packets contain a Length field, which determines the end
+of the packet.  The Length field covers both the Packet Number and Payload
+fields, both of which are confidentiality protected and initially of unknown
+length. The length of the Payload field is learned once header protection is
+removed.
+
+Using the Length field, a sender can coalesce multiple QUIC packets into one UDP
+datagram.  This can reduce the number of UDP datagrams needed to complete the
+cryptographic handshake and starting sending data.  Receivers MUST be able to
+process coalesced packets.
 
 Coalescing packets in order of increasing encryption levels (Initial, 0-RTT,
 Handshake, 1-RTT) makes it more likely the receiver will be able to process all

2 lines below: ", so it can only be the last packed included in a UDP datagram."

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#pullrequestreview-186295045

---

From: ianswett <[email-masked]>
Date: Tue, 18 Dec 2018 21:51:55 +0000 (UTC)

This adds a lot of duplicate text.  Can we avoid that, so we don't make a change in one spot and miss the other 3 spots?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#issuecomment-448384124

---

From: janaiyengar <[email-masked]>
Date: Tue, 18 Dec 2018 13:56:43 -0800

janaiyengar commented on this pull request.

Hah! 0 _is_ special :-)

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r242720659

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 15:32:03 -0800

I think the way we would get there is to make Initial/Handshake/0-RTT subsections of one section that defines some common fields after the long header.  The "longer" header?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#issuecomment-448411850

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 15:36:14 -0800

@MikeBishop pushed 2 commits.

ec3b889b8085abb5ce58f93dc5e19eb0cbab2567  Ian's requested change
7ba873e8504a35bd8da009967f211c7b535a8301  Merge remote-tracking branch 'origin/master' into transport/packet-types

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/dd515b6e7dd99980facb1402ebe184f8056817df..7ba873e8504a35bd8da009967f211c7b535a8301

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 23:57:25 +0000 (UTC)

1373a0917951dc4353cb1e5a4f9666ee18108b15  Group common headers into a section

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/7ba873e8504a35bd8da009967f211c7b535a8301..1373a0917951dc4353cb1e5a4f9666ee18108b15

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 16:00:10 -0800

f43f3ac6851870ac5138c984a7c11fc69382703c  Correct figure caption

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/1373a0917951dc4353cb1e5a4f9666ee18108b15..f43f3ac6851870ac5138c984a7c11fc69382703c

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 16:04:57 -0800

Done -- dubbed it the "Extended Long Header."

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#issuecomment-448418700

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 16:29:41 -0800

I think it's actually that it's `\d+\.` at the beginning of the line, and it's trying to normalize a numbered list.  I've considered trying to either insert or delete a word in that sentence, but....

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r242755724

---

From: Martin Thomson <[email-masked]>
Date: Tue, 18 Dec 2018 20:54:12 -0800

martinthomson commented on this pull request.

>  The following packet types are defined:
 
 | Type | Name                          | Section                     |
 |-----:|:------------------------------|:----------------------------|
 |  0x0 | Initial                       | {{packet-initial}}          |
-|  0x1 | 0-RTT Protected               | {{packet-protected}}        |
+|  0x1 | 0-RTT Protected               | {{packet-0rtt}}        |

I think that this is right, but counting is hard.

```suggestion
|  0x1 | 0-RTT Protected               | {{packet-0rtt}}             |
```

+See Sections 2.3 of {{!TLS13}} for a discussion of 0-RTT data and its
+limitations.

You should move the 0-RTT packet numbers section to here and remove the TODO.

> @@ -3338,6 +3342,52 @@ then a packet containing a 16-bit value of 0x9b32 will be decoded as 0xa82f9b32.
 Example pseudo-code for packet number decoding can be found in
 {{sample-packet-number-decoding}}.
 
+### Starting Packet Numbers

I don't think that we need this still, but absent analysis, this can be moved under the Initial packet section.

-~~~
+~~~~~

```suggestion
~~~
```

> @@ -3795,119 +3819,84 @@ Handshake encryption level is discarded - and no longer retransmitted - when
 Handshake protection keys are discarded.

-## Retry Packet {#packet-retry}
-
-A Retry packet uses a long packet header with a type value of 0x3. It carries
-an address validation token created by the server. It is used by a server that
-wishes to perform a stateless retry (see {{validate-handshake}}).
+## Short Header Packet {#short-header}

I'm assuming that the diff here looks terrible because it's moved text, not changed text.

> +: The length of the remainder of the packet (that is, the Packet Number and
+  Payload fields) in bytes, encoded as a variable-length integer
+  ({{integer-encoding}}).
+
+Packet Number:
+
+: The packet number field is 1 to 4 bytes long. The packet number has
+  confidentiality protection separate from packet protection, as described in
+  Section 5.4 of {{QUIC-TLS}}. The length of the packet number field is encoded
+  in the plaintext packet number. See {{packet-encoding}} for details.
+
+Payload:
+
+: The payload of the packet.
+
+### Initial Packet {#packet-initial}

I think that we should use h2 for this.  The section is a mix of "here is a common format" and "here is a specific instance of a common format", but I think that's tolerable.  We would then have something like:

```
17. Packet Formats
    17.1. Packet Number Encoding and Decoding
    17.2. Long Header Packets <-- note the extra 's'
    17.3. Version Negotiation Packet
    17.4. Retry Packet
    17.5. Extended Long Header Packets
    17.6. Initial Packet
        17.6.1. Abandoning Initial Packets
        17.6.2. Starting Packet Numbers
    17.7. 0-RTT Protected Packet <-- extra 'Packet'
        17.7.1. 0-RTT Packet Numbers
    17.8. Handshake Packet
    17.9. Short Header Packets <-- extra 's'
```

Does that work?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#pullrequestreview-186385869

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 22:01:18 -0800

I understand the desire not to move subsections below h3, but the mix of "format" and "instance" really just doesn't flow for me.  But it does kind of match the rest of the document with the "grouped sections" motif, so maybe it's at least consistent.

(It's already contorted enough that VN is a long header packet, but not from this version and therefore absent from the type table.)

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r242799094

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 22:03:14 -0800

Yep.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r242799311

---

From: Mike Bishop <[email-masked]>
Date: Wed, 19 Dec 2018 06:03:24 +0000 (UTC)

f3f691f0cff15ba280f97cc7407dd513daef9889  Update draft-ietf-quic-transport.md

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/f43f3ac6851870ac5138c984a7c11fc69382703c..f3f691f0cff15ba280f97cc7407dd513daef9889

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 22:03:40 -0800

e315b4d745c6e135a9d3b3732000f55da95f9db2  Update draft-ietf-quic-transport.md

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/f3f691f0cff15ba280f97cc7407dd513daef9889..e315b4d745c6e135a9d3b3732000f55da95f9db2

---

From: ianswett <[email-masked]>
Date: Wed, 19 Dec 2018 09:03:40 -0800

This version of QUIC uses the long packet header (see {{long-header}}) during
-connection establishment and the short header (see {{short-header}}) once 1-RTT
-keys have been established.
+connection establishment.  Packets that carry the long header are Initial

```suggestion
 connection establishment.  Packets that start with the long header are Initial
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#pullrequestreview-186651176

---

From: ianswett <[email-masked]>
Date: Wed, 19 Dec 2018 09:04:09 -0800

Or just "with the long header" as you say below.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r242998547

---

From: ianswett <[email-masked]>
Date: Wed, 19 Dec 2018 09:27:16 -0800

I believe Token is initial(and Retry) only?

> @@ -2602,15 +2600,21 @@ each packet sent, see {{packet-numbers}} for details.

-A sender can coalesce multiple QUIC packets into one UDP datagram.  This can
-reduce the number of UDP datagrams needed to complete the cryptographic
-handshake and starting sending data.  Receivers MUST be able to process
-coalesced packets.
+Packets using the Extended Long Header ({{extended-long-header}}) contain a
+Length field, which determines the end of the packet.  The Length field covers

```suggestion
 Length field, which determines the end of the packet.  The Length includes
```

Agreed, I'd remove this.  In the Packet Number section we say that packet numbers start at 0, but are we intending to require they start at 0, because I can't find any normative language.

```suggestion
|  0x1 | 0-RTT                         | {{packet-0rtt}}             |
```

Everywhere else in the doc, we call them 0-RTT, not 0-RTT Protected, so I'd suggest dropping Protected here.

> +  protected as they are for other packets with the long header, because Retry
+  packets don't contain a protected payload.  These bits instead encode the
+  length of the Original Destination Connection ID field.  The length uses the
+  same encoding as the DCIL and SCIL fields.
+
+Original Destination Connection ID:
+
+: The Original Destination Connection ID contains the value of the Destination
+  Connection ID from the Initial packet that this Retry is in response to. The
+  length of this field is given in ODCIL.
+
+Retry Token:
+
+: An opaque token that the server can use to validate the client's address.
+
+<!-- Break this stuff up a little, maybe into "Sending Retry" and "Processing

+1

> @@ -3674,7 +3707,37 @@ Token Length:
 
 Token:
 
-: The value of the token.
+: The value of the token that was previously provided in a Retry packet or

I thought only Initial packets have Tokens?

> @@ -2602,15 +2600,21 @@ each packet sent, see {{packet-numbers}} for details.

-A sender can coalesce multiple QUIC packets into one UDP datagram.  This can
-reduce the number of UDP datagrams needed to complete the cryptographic
-handshake and starting sending data.  Receivers MUST be able to process
-coalesced packets.
+Packets using the Extended Long Header ({{extended-long-header}}) contain a

Above you talk about packet types that use the long header and here you talk about packets with a length, but I don't see anywhere you list out which packet types use the extended long header, and not just the long header.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#pullrequestreview-186651662

---

From: Mike Bishop <[email-masked]>
Date: Wed, 19 Dec 2018 10:57:00 -0800

In this format, they're the subsections of the ELH section.  We'd probably have to be more explicit if we take the non-indented layout @martinthomson proposes.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r243035444

---

From: Mike Bishop <[email-masked]>
Date: Wed, 19 Dec 2018 11:49:18 -0800

Token:

You're right, this fell in during the ELH combination.  So Initial packets *are* different because of the Token fields, which means that only 0-RTT and Handshake have the same ELH format.  Are we sure it's worth not simply having an explicit list of fields for those two?  That makes me more inclined to just revert the ELH change entirely and make each long-header packet type stand alone.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r243052578

---

From: Mike Bishop <[email-masked]>
Date: Wed, 19 Dec 2018 12:09:31 -0800

6bacca6a3b8c31bccdded4cdb4a6484136b482d9  Merge remote-tracking branch 'origin/master' into transport/packet-types
5d2511561a31360bdeb2a30fc46e862e65fc27d3  Rearrange to eliminate ELH

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/e315b4d745c6e135a9d3b3732000f55da95f9db2..5d2511561a31360bdeb2a30fc46e862e65fc27d3

---

From: Mike Bishop <[email-masked]>
Date: Wed, 19 Dec 2018 12:23:07 -0800

@MikeBishop pushed 3 commits.

8c004b03e4bd75645aaf9648d6a6e05d9fada367  Review comments
7e016a340bc677ba0367b82ce6d16ff90547a9da  0-RTT, not 0-RTT Protected
8fec9863c71287fa7dd7b1b8e6ff9c647d3839b0  Move packet number discussions

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/5d2511561a31360bdeb2a30fc46e862e65fc27d3..8fec9863c71287fa7dd7b1b8e6ff9c647d3839b0

---

From: Mike Bishop <[email-masked]>
Date: Wed, 19 Dec 2018 12:25:12 -0800

03f8fb768bc74c5c869807c936750c2df9fe678c  Seriously, stop.

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203/files/8fec9863c71287fa7dd7b1b8e6ff9c647d3839b0..03f8fb768bc74c5c869807c936750c2df9fe678c

---

From: Mike Bishop <[email-masked]>
Date: Wed, 19 Dec 2018 12:29:32 -0800

Since this happened again, I reworded the sentence so the line doesn't start with a digit. 🙄

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/2203#discussion_r243064711