Lab Spec: NET-101 TCP Three-Way Handshake Replay Interactive

This document specifies the educational scenario, packet sequence, per-step pedagogy, and engineering integration contract for the Phase-1 TCP handshake replay interactive. The engineering team implements against this spec. The curriculum team validates the per-step callouts. This spec does not implement anything.

§1. Educational scenario

When a browser opens a connection to a web server, the first thing TCP does is negotiate the connection itself. Before TLS begins, before an HTTP byte moves, TCP runs the three-way handshake: three packets, a few milliseconds, two endpoints agreeing on where each side's byte stream starts.

This interactive presents that exchange using a real three-packet capture (fundamentals-tcp-3way.pcap) of a client connecting to port 22. No application data. No TLS overhead. Just the handshake, in isolation. The student steps through each packet one at a time and watches the field values and state annotations update.

The scenario is deliberately minimal. Port 22 (SSH) was chosen because the port number itself carries no meaning in the handshake -- any well-known port would produce an identical exchange shape. Students who ask "why port 22?" should discover that the answer is: because a server was listening there. The handshake looks identical for port 80, port 443, or any other TCP destination.

Why this interactive, at this point in the course. Week 6 is where students first encounter TCP's sequence-number mechanics. The week-6 lecture introduces the arithmetic (SYN consumes one sequence number; ACK number = peer's ISN + 1) and the state machine (CLOSED - LISTEN - SYN_SENT - SYN_RCVD - ESTABLISHED). Lab 6-1 asks students to read those same fields by opening the capture in pcap-tools and filling in a table manually.

This replay interactive sits between the lecture and the manual lab. It gives students an annotated step-through before they try to find the fields on their own. A student who steps through the replay once can do Lab 6-1 with confidence because the fields they need are the ones the replay highlighted.

Relationship to the static diagram. The static TCP handshake sequence diagram shipped with the week-6 lecture (net-101-wk6-tcp-handshake.mermaid, website/assets/diagrams/net-101-tcp-handshake.svg) shows the same three-packet exchange as a sequence diagram with annotated sequence and acknowledgment numbers. This interactive is that diagram with a Step button: the same sequence, the same numbers, with real wire bytes behind each arrow.

§2. Learning objectives

After stepping through the replay, a student can:

1. Identify which flags are set on each of the three packets (SYN only; SYN and ACK; ACK only) and explain why each combination is correct.
2. Verify the acknowledgment-number arithmetic: ACK in packet 2 = seq in packet 1 + 1; ACK in packet 3 = seq in packet 2 + 1.
3. Explain why each ISN is a large random value rather than zero or a small counter.
4. Name both endpoints' TCP state after each packet is played (SYN_SENT, SYN_RCVD, ESTABLISHED).
5. Distinguish the two separate byte streams established by the handshake (client-to-server and server-to-client) and explain that each stream has its own ISN.
6. Connect the window-size and MSS option fields to flow-control and path-MTU behavior (forward pointers for Week 7).

§3. Fixture and packet sequence

§3.1 Fixture source

This fixture is already in the manifest and already rendered by pcap-tools. No new binary is needed for this interactive. The engineering work is adding the replay-mode UI extension.

§3.2 Packet sequence -- exact field values

The values below are the actual wire values from the fixture. All arithmetic examples in the chapter prose and the week-6 lecture use these same numbers.

Packet 1: SYN -- client initiates

Packet 2: SYN-ACK -- server responds

Packet 3: ACK -- client completes handshake

§3.3 Sequence-number arithmetic verification

The two arithmetic relationships that the replay must make visible:

Packet 1 carries:  seq = 2712847316  (client ISN)

Packet 2 carries:  ack = 2712847317  = 2712847316 + 1
                                       (client ISN + 1; SYN consumed one seq number)
                   seq = 1432778632  (server ISN, independent random choice)

Packet 3 carries:  seq = 2712847317  = 2712847316 + 1
                                       (client's own sequence advances after SYN consumed it)
                   ack = 1432778633  = 1432778632 + 1
                                       (server ISN + 1; SYN-ACK consumed one seq number)

Both ISNs are the same values shown in the worked example in week-6 lecture Section 2 and in the chapter prose. Students who did the reading will recognize 0xa1b2c3d4 and 0x55667788.

§4. Per-step pedagogy

The replay presents five states: initial (before any packet), after packet 1, after packet 2, after packet 3, and a summary screen. Each state has a defined callout text, a set of highlighted fields, an arithmetic annotation where applicable, and a security observation where applicable.

The engineering team renders these callouts verbatim. The curriculum team owns the text.

§4.0 Initial state (before any packet is played)

Screen title: "TCP Three-Way Handshake -- Ready"

State annotation:

Callout text:

A TCP connection starts with both sides in defined states: the client has no connection open (CLOSED); the server is waiting for incoming connections (LISTEN). The server entered LISTEN when the application bound port 22 -- the moment sshd started and called bind() then listen() on the socket. The client is CLOSED because it has not yet called connect().

The three packets in this capture are the entire negotiation. Step through them one at a time.

Highlighted fields: none (no packet selected yet)

§4.1 Step 1: SYN -- client initiates

Packet index: 1

State annotation (after this packet is played):

Note for engineering: both endpoints' states update together when the packet is played. The server transitions to SYN_RCVD because it received the SYN and is about to send the SYN-ACK.

Highlighted fields:

• tcp.flags -- highlight the SYN bit; call attention to the absence of ACK
• tcp.seq -- the client's ISN
• tcp.ack -- the zero value; note ACK flag is not set
• tcp.options.mss -- the MSS option
• tcp.window_size -- client's receive window
• tcp.dstport -- destination port identifies the target application

Callout text:

The client sends a SYN segment. This is the client calling out: "I want to start a TCP connection, and I am numbering my bytes starting from 2712847316."

SYN flag only. ACK is not set. The client has nothing to acknowledge yet -- the server has not sent anything. Because ACK is not set, the acknowledgment number field (which reads 0) carries no meaning and the server ignores it.

The initial sequence number (ISN) is 2712847316 (0xa1b2c3d4). The kernel picked this value randomly. It is not zero, not one, not a predictable counter. The reason: if ISNs were predictable, an attacker who knew the port pair could forge a packet with the correct sequence number and inject data into the connection without being on the network path. Random ISNs are the defense.

MSS = 1460. The Maximum Segment Size option tells the server: "do not send me TCP segments with more than 1460 bytes of payload in a single segment." 1460 is the standard value for Ethernet with no additional overhead (1500-byte MTU minus 20-byte IP header minus 20-byte TCP header).

Window size = 64240. The client's receive buffer can hold 64240 bytes right now. The server may not send more than this without waiting for an acknowledgment.

After this packet, the client waits in SYN_SENT. It will stay there until the SYN-ACK arrives.

Arithmetic box (inline in UI):

Client ISN: 2712847316  (0xa1b2c3d4)
Next packet's ack must be: 2712847316 + 1 = 2712847317

§4.2 Step 2: SYN-ACK -- server responds

Packet index: 2

State annotation (after this packet is played):

Note for engineering: the client transitions to ESTABLISHED here because receiving the SYN-ACK is the trigger -- the client sends the ACK (packet 3) simultaneously with the state transition. Show client as ESTABLISHED to make the "after receiving SYN-ACK, the client is done" point visible.

Highlighted fields:

• tcp.flags -- highlight both SYN and ACK bits
• tcp.seq -- the server's ISN
• tcp.ack -- the acknowledgment of the client's SYN; show the +1 arithmetic
• tcp.options.mss -- server's MSS announcement

Callout text:

The server replies with a SYN-ACK. This is the only packet type in a normal TCP exchange that has both SYN and ACK set at once.

Two flags, two meanings.

• ACK = 1 means: "I received your SYN. Your ISN was 2712847316. I expect your next byte to be 2712847317." The acknowledgment number 2712847317 is the client's ISN + 1. The +1 is because SYN is a one-byte placeholder that advances the sequence number even though no application data was carried.
• SYN = 1 means: "I am also starting my own byte stream, and I am numbering it starting from 1432778632." The server chooses its own ISN independently of the client's.

Server's ISN is 1432778632 (0x55667788). Again, randomly chosen by the kernel. The two ISNs have no mathematical relationship to each other.

Server's MSS = 1460 and window = 65535. The server is announcing its own receive constraints, just as the client did in the SYN. Both sides now know each other's MSS and initial window size.

The client receives this SYN-ACK, verifies that the ACK number is its ISN + 1, and immediately sends the final ACK (packet 3). At that point the client's state becomes ESTABLISHED. The server, however, is still in SYN_RCVD -- it has sent its SYN-ACK but has not yet received confirmation that the client got it.

Arithmetic box (inline in UI):

Client ISN was:           2712847316  (0xa1b2c3d4)
Server's ACK number:      2712847317  = 2712847316 + 1  [SYN consumed one seq number]
Server ISN:               1432778632  (0x55667788)
Next packet's ack must be: 1432778632 + 1 = 1432778633

§4.3 Step 3: ACK -- client completes the handshake

Packet index: 3

State annotation (after this packet is played):

Highlighted fields:

• tcp.flags -- ACK only; no SYN, no PSH, no FIN
• tcp.seq -- client's sequence number after SYN consumed one number
• tcp.ack -- acknowledgment of the server's SYN
• tcp.len -- zero; no payload

Callout text:

The client sends a pure ACK. No data. No more SYN flags. This is the handshake's closing stroke.

ACK only. The SYN phase is over for the client. There is nothing to synchronize. There is nothing to push. There is no data yet. The sole purpose of this packet is to confirm: "I received your SYN-ACK."

Sequence number = 2712847317 (0xa1b2c3d5). The client's sequence number advanced by 1 after the SYN -- the SYN "used up" byte number 2712847316. The client's actual application data, when it arrives, will start at 2712847317.

ACK number = 1432778633 (0x55667789). The server's ISN was 1432778632. Its SYN consumed that number. The client acknowledges: "I received everything through your byte 1432778632; send me 1432778633 next."

Payload length = 0. No application data yet. A real SSH connection would next send the SSH protocol banner (an ASCII string identifying the server's SSH version). That exchange happens over the established TCP connection, not during the handshake.

The server receives this ACK. At that moment both sides are ESTABLISHED. The TCP connection is open. Both endpoints share:

• The client's starting sequence number (2712847317)
• The server's starting sequence number (1432778633)
• Each other's MSS (1460)
• Each other's current window size

Arithmetic box (inline in UI):

Server ISN was:           1432778632  (0x55667788)
Client's ACK number:      1432778633  = 1432778632 + 1  [SYN-ACK's SYN consumed one seq number]

Both sides are now ESTABLISHED.

§4.4 Summary screen (after step 3)

Screen title: "Handshake Complete"

State annotation:

Callout text:

The three-way handshake is complete. Three packets. Both sides agreed on sequence numbers.

What each side now knows:

Item	Value
Client -> Server stream starts at	2712847317
Server -> Client stream starts at	1432778633
MSS (both directions)	1460 bytes
Client's receive window	64240 bytes
Server's receive window	65535 bytes

Why three packets, not two? Two might seem sufficient: SYN (client announces its ISN), SYN-ACK (server announces its ISN and confirms client's). The third packet (the ACK) is the client confirming it received the server's ISN. Without the ACK, the server never knows whether its SYN-ACK arrived. If the SYN-ACK was dropped, the server would wait indefinitely for data, not knowing the client gave up. The third packet closes the loop.

Security note. Both 2712847316 and 1432778632 were chosen by their respective kernels at random. If you replay this handshake and capture it yourself, you will see different ISNs. This is correct behavior: each new connection starts with fresh random numbers. An attacker who intercepts this capture cannot use its ISNs to forge packets into a future connection on the same port pair.

What comes next. Load fundamentals-http-get.pcap in pcap-tools. Apply tcp.flags.syn == 1. You will find a different ISN -- proof that each connection starts fresh.

Replay controls: "Step Back" returns to step 3. "Replay from start" resets to §4.0.

§5. TCP state machine annotation

§5.1 State transition table (both endpoints, per packet played)

§5.2 What students derive from these states

The state machine table answers questions the lecture poses but the static sequence diagram cannot show:

• Why is the server still SYN_RCVD after packet 2? Because the server sent a SYN-ACK but has not yet received the ACK. Until that ACK arrives, the server does not know whether the client got the SYN-ACK. The server keeps a half-open connection entry and will resend the SYN-ACK if the ACK does not arrive within a timeout.

• Why does the client become ESTABLISHED before the server? Because the client received the server's SYN-ACK and knows the handshake succeeded from its side. The server needs one more packet (the ACK) before it can be sure.

• What would happen if packet 3 were lost? The server would stay in SYN_RCVD, retransmit the SYN-ACK, and eventually time out. This is the condition SYN-flood attacks exploit: an attacker sends many SYN packets with spoofed source addresses, forcing the server to maintain many SYN_RCVD entries while no ACKs arrive. SYN cookies are the defense (week-6 reflection prompt 5).

§5.3 States not shown in this capture (forward pointer)

The states after ESTABLISHED (FIN_WAIT_1, FIN_WAIT_2, TIME_WAIT, CLOSE_WAIT, LAST_ACK, CLOSED) are covered in Lab 6-2 and the week-6 lecture Section 4. The TCP state machine diagram in the lecture notes is the authoritative reference. This replay covers only the handshake arc.

§6. Engineering integration contract

This section specifies what the engineering team must build. Everything in §4 and §5 is content. Everything in §6 is structure.

§6.1 UI requirements

The replay mode is an extension of the existing pcap-tools UI. It does not replace the standard table + detail + hex view; it adds a "Replay" toggle that activates when the loaded capture has a replay_mode field in its manifest entry.

Replay panel layout:

+---------------------------+---------------------------+
| Step controls             | State machine panel       |
| [<< Start] [< Prev] [>]   | Client: SYN_SENT          |
| Step 1 of 3: SYN          | Server: SYN_RCVD          |
+---------------------------+---------------------------+
| Callout text (§4.x text)                              |
|                                                       |
+-------------------------------------------------------+
| Arithmetic box (§4.x arithmetic, when present)        |
+-------------------------------------------------------+
| Packet detail pane (standard pcap-tools view)         |
| Highlighted fields per §4.x spec                      |
+-------------------------------------------------------+

Behavioral requirements:

1. On load with replay_mode present: start in §4.0 (initial state). Show "Start replay" button.
2. Step forward: advance one packet. Update state machine panel, callout text, arithmetic box, highlighted fields. Do NOT auto-advance.
3. Step backward: retreat one packet. All annotations revert.
4. Replay reset: return to §4.0 state.
5. After step 3: show §4.4 summary screen. "Step forward" is disabled. "Replay" button resets.
6. Standard pcap-tools view (packet table, detail pane, hex view) is visible throughout. The highlighted fields listed in §4.x are visually distinguished (e.g., yellow background on the field row in the detail pane).
7. The arithmetic box is a fixed-width monospace block. Show only for steps where §4.x defines an arithmetic annotation.
8. No external CDN loads. All assets hosted on academy domain (per visual-learner memo §4.5 doctrine).
9. Keyboard navigation: left/right arrow keys step back/forward.

Device tier: desktop-primary. On viewports narrower than 768px, collapse the state machine panel below the step controls. The replay must be usable on desktop; mobile is not required but should not break.

Persistence: step position is NOT persisted across sessions. The replay is a teaching tool, not a graded artifact. No localStorage save/load needed for this resource.

§6.2 Annotation overlay file

Create pcap-tools/backend/tutor/prompts/overlays/tcp-3way-replay-context.md with the following content. This is what the AI tutor loads when a student is in the TCP handshake replay and asks the tutor a question.

TCP THREE-WAY HANDSHAKE REPLAY CONTEXT (NET-101, Week 6)

This student is stepping through the fundamentals-tcp-3way.pcap replay
interactive in pcap-tools. The capture contains exactly 3 packets:

  Pkt 1: 192.0.2.10:49200 -> 192.0.2.20:22  SYN      seq=2712847316  ack=0
  Pkt 2: 192.0.2.20:22    -> 192.0.2.10:49200 SYN+ACK seq=1432778632  ack=2712847317
  Pkt 3: 192.0.2.10:49200 -> 192.0.2.20:22  ACK      seq=2712847317  ack=1432778633

Key mechanics being taught:
1. SYN flag only in packet 1: client announces ISN; ACK flag off; ack field invalid.
2. SYN+ACK in packet 2: server announces its own ISN AND acknowledges client's ISN.
   Acknowledgment arithmetic: ack_2 = 2712847316 + 1 = 2712847317 (SYN consumed 1 seq).
3. ACK only in packet 3: no data; closes the loop; both sides reach ESTABLISHED.
   Acknowledgment arithmetic: ack_3 = 1432778632 + 1 = 1432778633 (SYN-ACK's SYN consumed 1 seq).

State machine:
  Initial:           client=CLOSED    server=LISTEN
  After packet 1:    client=SYN_SENT  server=SYN_RCVD
  After packet 2:    client=ESTABLISHED  server=SYN_RCVD
  After packet 3:    client=ESTABLISHED  server=ESTABLISHED

ISNs are random (0xa1b2c3d4 / 0x55667788) to prevent TCP session hijacking.
Both ISNs are the same values shown in the week-6 lecture worked example.
MSS = 1460 (standard Ethernet; MTU 1500 - 20 IP - 20 TCP = 1460).
Window sizes: client 64240, server 65535.

Socratic questions you may pose:
- Packet 2's ACK is 2712847317. Where does the +1 come from?
- The server is still in SYN_RCVD after packet 2 is sent. Why?
- Why would a two-way handshake (SYN, then data) be insufficient?
- If the client's ISN were always 0, what would an attacker be able to do?
- Packet 3 has payload length 0. Is this usual for the third packet? Could it carry data?
- What display filter shows only the SYN packets in this capture?

Reading anchors:
- Stevens TCP/IP Illustrated Ch 18 (connection establishment and termination)
- Week-6 lecture Section 2 (sequence-number arithmetic) and Section 3 (three-way handshake)
- Lab 6-1 asks students to fill in the same field values they see in this replay

Security depth (Week 6 reflection prompt territory):
- Random ISNs: defend against session hijacking and blind injection attacks
- SYN_RCVD holding state: the target of SYN-flood attacks; SYN cookies are the defense
- Third-packet ACK: prevents the server from being half-open indefinitely

§6.3 Manifest extension

Add a replay_mode field to the existing net-101-fund-tcp-3way manifest entry in pcap-tools/fixtures/curated-12-manifest.json:

"replay_mode": {
  "type": "tcp_handshake_3way",
  "step_count": 3,
  "annotation_overlay": "tcp-3way-replay-steps",
  "state_machine": "tcp_client_server",
  "initial_client_state": "CLOSED",
  "initial_server_state": "LISTEN",
  "steps": [
    {
      "step": 1,
      "packet_index": 0,
      "title": "SYN -- client initiates",
      "state_client_after": "SYN_SENT",
      "state_server_after": "SYN_RCVD",
      "highlight_fields": ["tcp.flags", "tcp.seq", "tcp.ack", "tcp.options.mss", "tcp.window_size", "tcp.dstport"],
      "show_arithmetic": true,
      "arithmetic_left": "Client ISN: 2712847316 (0xa1b2c3d4)",
      "arithmetic_right": "Next ack must be: 2712847317"
    },
    {
      "step": 2,
      "packet_index": 1,
      "title": "SYN-ACK -- server responds",
      "state_client_after": "ESTABLISHED",
      "state_server_after": "SYN_RCVD",
      "highlight_fields": ["tcp.flags", "tcp.seq", "tcp.ack", "tcp.options.mss"],
      "show_arithmetic": true,
      "arithmetic_left": "Server ack = 2712847316 + 1 = 2712847317",
      "arithmetic_right": "Server ISN: 1432778632 (0x55667788)"
    },
    {
      "step": 3,
      "packet_index": 2,
      "title": "ACK -- handshake completes",
      "state_client_after": "ESTABLISHED",
      "state_server_after": "ESTABLISHED",
      "highlight_fields": ["tcp.flags", "tcp.seq", "tcp.ack", "tcp.len"],
      "show_arithmetic": true,
      "arithmetic_left": "Client ack = 1432778632 + 1 = 1432778633",
      "arithmetic_right": "Both sides: ESTABLISHED"
    }
  ]
}

§6.4 What the engineering brief must NOT change

These constraints are curriculum decisions, not implementation choices. The engineering brief inherits them.

1. Callout text is verbatim. The text in §4.x is the authored curriculum content. The engineering team renders it; they do not rewrite it. If the text requires HTML (for the monospace arithmetic box), the engineering team wraps it; they do not alter the prose.
2. Packet values are exact. The ISNs, ACK numbers, port numbers, and window sizes in §3.2 are from the real fixture. If those values do not match what pcap-tools parses, the fixture has been modified and the spec must be re-verified.
3. State transitions are as specified in §5.1. The client transitions to ESTABLISHED after packet 2 (not after packet 3). This is a pedagogical choice: it shows the asymmetry (client is done before server is done) that motivates the need for packet 3.
4. The security callouts in §4.3 and §4.4 are retained. The ISN-randomness security observation is tied to week-6 reflection prompt 1. Removing it breaks the lecture-interactive-lab cohesion.

§7. Cross-references

§7.1 Chapter and lab cross-references

§7.2 Static diagram counterpart

The static TCP handshake sequence diagram (net-101-wk6-tcp-handshake.mermaid, ranked #2 in the visual-learner memo §3) is the same content as this replay in non-interactive form. The two should use consistent labels, consistent seq/ack annotation format, and consistent color coding (if the static diagram uses a color for the SYN arrow, the replay should use the same color when highlighting that packet).

The static diagram is the reference for the lecture notes HTML. This replay is the reference for pcap-tools. They co-exist; neither replaces the other.

§8. Authoring notes

Voice register. The callout text in §4 is written at the NET-101 student register: motivated beginner with no prior network background, working through the course in order. It assumes the student has read the week-6 lecture but has not yet done Lab 6-1. Technical vocabulary (ISN, SYN, ACK, ESTABLISHED) is used without apology but is always explained on first use within each callout.

No metaphors. The callout text does not use "handshake as a greeting" or other anthropomorphizing analogies. TCP is a protocol; it sends packets with flags and sequence numbers. The mechanics explain themselves.

Arithmetic is the anchor. Every callout returns to the arithmetic. The pedagogy works when students can verify 2712847317 = 2712847316 + 1 with their own arithmetic. All other concepts (random ISNs, state machine, MSS negotiation) are secondary to making that verification feel concrete.

Security anchors are earned, not asserted. The security callouts in §4.1 and §4.4 name the attack (session hijacking / SYN flood) and point to week-6 reflection prompts. They do not assert "this is secure" without explaining why. The student who follows the pointer to Stevens Ch 18 and the week-6 reflection prompts will build the full picture.

Em-dash and blacklist clean. This document uses no em-dashes, no en-dashes used as pauses, and none of the phrase-blacklist terms (load-bearing, leverage, delve, by construction, journey, comprehensive-as-filler, robust-as-filler). Standard per editor-guide discipline.

Lab spec authored 2026-05-13 under R-INTERACTIVE-NET-101-TCP-HANDSHAKE-AUTHOR-2026-05-13. Engineering follow-on should author the pcap-tools extension brief referencing this document as the content contract. Curriculum review: verify callout text against Stevens Ch 18 and the week-6 lecture worked example before the engineering brief is issued.