The WebSocket Protocol

A WebSocket connection is a TCP connection (usually inside TLS) that starts life as an HTTP/1.1 request, switches protocol with Upgrade: websocket, and from then on carries frames instead of HTTP messages. Three properties explain why chat, videoconference signalling and games all use it:

What it does not give you: ordering across connections, delivery acknowledgements, reconnection, message types or rooms. TCP gives in-order, reliable delivery on one connection, with the head-of-line blocking that implies for games (see Networking Fundamentals); everything else is application protocol, as in Chatterbox. The URL schemes are ws:// (port 80) and wss:// (port 443, TLS); production traffic always uses wss://.

The client sends an ordinary HTTP/1.1 GET with a handful of required headers. The server answers 101 Switching Protocols and, after that blank line, both sides speak frames. This is the exact exchange captured from the raw-socket client later on this page, against a ws server that allow-lists the origin:

The headers have precise roles:

The Sec- prefix matters: a page’s JavaScript cannot set any header starting with it, so a cross-origin page cannot forge a handshake with fetch() or XMLHttpRequest. The browser WebSocket API also cannot add arbitrary headers such as Authorization, which is why Chatterbox authenticates with a cookie or a one-time ticket and not with a bearer header (see Authentication and Authorization).

After the handshake every message is sent as one or more frames. The header is two bytes for short messages and grows to 14 bytes. The figure shows the layout in 32-bit rows, as RFC 6455 draws it.

The fields, in order:

Control frames (opcodes 8 to 10) have two extra rules: the payload length must be 125 or less, so they always use the 7-bit form, and they must not be fragmented.

Every frame sent from a client to a server must be masked with a fresh 32-bit key, and every frame sent from a server to a client must not be. The payload byte at position i is XOR-ed with byte i mod 4 of the key. Applying the same operation again restores the original, so the receiver uses the same loop. A server must close the connection (code 1002) when it receives an unmasked client frame, and a client must do the same for a masked server frame.

The purpose is not confidentiality, because the key travels in the clear next to the data. The purpose is to defeat cache-poisoning attacks through intermediaries. A malicious page could otherwise open a WebSocket and send bytes that look like an HTTP request, for example GET /app.js followed by headers, through a transparent proxy that does not understand the upgrade. The proxy would see what looks like a new request on that connection, fetch the attacker’s chosen URL and cache the answer under the victim site’s URL. Masking with a key the script cannot choose or predict means the attacker cannot control the exact bytes on the wire, so it cannot craft such a request. Two consequences:

The cost is a XOR pass over every client payload, which servers do in optimised native code (ws uses an optional native addon or a vectorised JavaScript fallback). It is one of the reasons client-to-server throughput is slightly lower than server-to-client throughput.

Source: RFC 6455, section 10.3: Attacks On Infrastructure (Masking)

A message may be split into several frames. The first frame carries the real opcode (text or binary) with FIN 0, the following frames carry opcode 0 (continuation) with FIN 0, and the last one carries opcode 0 with FIN 1. The rules are:

Fragmentation lets a sender start transmitting a large message before it knows its total length, and lets a multiplexing sender interleave control frames. It rarely matters to application code, because libraries reassemble messages before delivering them, but it explains why browsers expose message events with whole messages and why bufferedAmount counts bytes rather than messages. Browser-side details are in The Browser WebSocket API.

A ping (opcode 9) may carry up to 125 bytes of application data. The receiver must answer with a pong (opcode 10) that carries the same data, as soon as practical, unless it has already received a close frame. An unsolicited pong is allowed and is ignored, which makes it a one-way heartbeat. Browsers answer pings automatically and expose no API to send them, which is why Chatterbox sends an application-level presence heartbeat as well as a server-initiated protocol ping every heartbeatMs.

Protocol ping/pong has two uses. It keeps NAT mappings and load-balancer idle timers alive (the AWS Application Load Balancer closes idle connections after 60 seconds by default, so pings must be more frequent than that), and it detects half-open connections: if no pong arrives within a deadline, the server terminates the socket. Intervals, deadlines and reconnection are covered in Connection Lifecycle, Heartbeats and Reconnection.

Closing is a two-step protocol, separate from closing TCP. An endpoint that wants to close sends a close frame (opcode 8). Its optional payload is a 2-byte status code (big-endian) followed by a UTF-8 reason, 123 bytes at most because the whole control payload is limited to 125. The peer answers with its own close frame, usually echoing the code. After an endpoint has sent a close frame it sends no more data frames, and after it has received one it discards anything that follows. When both close frames have been exchanged, the server closes the TCP connection first, and the client waits for that. A client that does not see the server close TCP within a reasonable time closes it itself, so a peer that never answers cannot hold the connection open forever.

The raw-socket client below ends its session exactly like this: it sends a masked close frame whose payload is 03 e8 62 79 65 (03 e8 is 1000 and 62 79 65 is the reason bye), and the server answers with the unmasked 88 05 03 e8 62 79 65.

Sec-WebSocket-Protocol negotiates the application protocol spoken in the frames. The client lists tokens in preference order, the server picks exactly one and echoes it, and the browser exposes it as socket.protocol. If the server does not support any of them it simply omits the header, and the connection is open with an empty protocol (a server that insists on a subprotocol should refuse the handshake instead). If the server picks a token the client did not offer, the client must fail the connection.

Chatterbox uses the token chatterbox.v1; a future incompatible envelope would be chatterbox.v2, and a client can offer both, newest first, to migrate without breaking old servers. The token is a name, not a URL, and it should be unique: IANA keeps a Subprotocol Name Registry (for example xmpp, the subprotocol of RFC 7395 described in XMPP in the Browser; mqtt; graphql-transport-ws). Registration is optional, but reusing a registered token for a different protocol is a bug waiting for an interoperability problem. Because the header is the only custom value a browser lets a script choose, some applications smuggle a token in it; it is a hack with real drawbacks (the value appears in logs and must be a valid token), compared in Authentication and Authorization.

Sec-WebSocket-Extensions negotiates protocol-level changes: the client offers one or more extensions with parameters, and the server answers with the subset it accepts, with the final parameter values. Extensions claim the RSV bits and may add extension data before the payload. They apply in the order listed. The IANA Extension Name Registry holds permessage-deflate (RFC 7692), the one extension in practice. (x-webkit-deflate-frame and deflate-frame, earlier drafts of per-frame compression, were obsolete long ago.)

The Upgrade mechanism exists only in HTTP/1.1, so WebSocket cannot reuse an HTTP/2 or HTTP/3 connection through it. Two RFCs bootstrap WebSocket over a single stream of a multiplexed connection, so that a page’s WebSockets and requests share one TCP or QUIC connection:

The request replaces the HTTP/1.1 handshake. There is no Upgrade, no Sec-WebSocket-Key and no Sec-WebSocket-Accept, because the stream itself identifies the exchange. Sec-WebSocket-Version, Sec-WebSocket-Protocol and Sec-WebSocket-Extensions keep their meaning, and Origin is still sent by browsers:

A successful answer is a 200 status (not 101), after which the stream’s data carries ordinary WebSocket frames (masked in client frames as always). A client must not send an extended CONNECT before it has seen the setting from the server, and a server that receives an unknown :protocol answers 501 Not Implemented. Closing the WebSocket ends the stream (a FIN on the stream, or a stream reset when the connection is aborted) instead of closing the connection.

Why it matters: with HTTP/1.1, each WebSocket needs its own TCP connection, which strains browsers' per-host connection limits and proxies; over HTTP/2 or HTTP/3 many sockets and requests share one connection, and over HTTP/3 a lost packet in one stream no longer stalls the others (though one WebSocket is still an ordered stream). Support belongs to the stack, not to the JavaScript API: the page still calls new WebSocket(url), and the browser chooses the transport. A server or proxy has to support it explicitly (for Node.js, node:http2 can enable the setting through its enableConnectProtocol option and then handle the CONNECT stream itself, while ws itself speaks HTTP/1.1), and many deployments terminate HTTP/2 at the proxy and talk HTTP/1.1 upstream, which keeps application servers unchanged. For new, low-latency designs the alternative is WebTransport and Media over QUIC. Proxy specifics are in Proxies, Load Balancers and Deployment.

Source: RFC 8441: Bootstrapping WebSockets with HTTP/2, RFC 9220: Bootstrapping WebSockets with HTTP/3

IANA maintains the "WebSocket Protocol Registries": the WebSocket Extension Name Registry, the Subprotocol Name Registry, the Version Number Registry, the Close Code Number Registry, the Opcode Registry and the Framing Header Bits Registry. Close codes 1000-2999 need standards action or specification review, 3000-3999 are first-come-first-served and 4000-4999 are not registered, and RFC 7936 clarified the registration procedures of the subprotocol registry. Before inventing a subprotocol token or a close code in the 3000 range, look at the registry. The page of the registry is the authoritative list of the codes in the table above.

Source: IANA: WebSocket Protocol Registries

A minimal, complete ws server for Chatterbox. It rejects any handshake whose Origin is not on the allow-list, selects chatterbox.v1, configures permessage-deflate conservatively, sets maxPayload, answers pings, and echoes messages. It does the origin check in the HTTP upgrade event, before the WebSocket handshake is completed, so a rejected client gets a plain 403 and never owns a socket.

Source: ws documentation: Class WebSocketServer

The protocol’s security rests on a few decisions, and each is the application’s to make.

Cross-Site WebSocket Hijacking. Browsers do not apply the same-origin policy to WebSocket handshakes: a page on any site may open wss://chat.example.test/ws, and the browser attaches the site’s cookies to the request. If the server authenticates the handshake by cookie alone and does not look at Origin, any web page the victim visits can open a socket as the victim, read the replies (a WebSocket, unlike a fetch() to another origin, has no CORS check on reading) and send commands. That is Cross-Site WebSocket Hijacking, the WebSocket variant of cross-site request forgery. The protocol’s own defence is the Origin header, which the browser sets and a page cannot change, so the server must allow-list Origin (as the example above does), refuse anything unexpected with 403, and decide explicitly what to do with requests that have no Origin (non-browser clients). It is the equivalent of the CORS checks described in What is CORS? with the difference that CORS is enforced by the browser while for WebSockets the server is the only enforcer. SameSite=Lax or Strict cookies reduce the exposure, but WebSocket handshakes from the same site (different origin) and older browsers still need the Origin check. A one-time ticket in the URL or in the first message (instead of an ambient cookie) removes ambient authority altogether; the trade-offs of each option are in Authentication and Authorization and Security.

Other rules: use wss:// always (otherwise masking is the only protection and a proxy can read and alter everything); set maxPayload; validate JSON after parsing and never trust the ts or from fields of a client (Chatterbox ignores them); rate-limit per connection; time out connections that never complete hello; and keep close reasons free of internal details.

Source: RFC 6455, section 10.2: Origin Considerations

Browser DevTools. In Chrome, open the Network panel, toggle the WS filter, click the connection and open the Messages tab to see the text and binary messages in each direction with their time; the Headers tab shows the handshake request and the 101 response (or the failing status of a refused handshake), which is where a 403 from the origin check or a 400 from a proxy shows up. Firefox has the same filter and a Messages pane. The panels show decoded messages and not raw frames, so masking keys, fragments and RSV bits are not visible, and control frames such as ping and pong are typically not listed as messages. DevTools also throttles WebSocket connections together with other network traffic, which is useful for testing slow links.

Wireshark. Capture the loopback or network interface and filter websocket. The dissector shows each frame with websocket.fin, websocket.opcode, websocket.mask, websocket.masking_key, websocket.payload_length and the unmasked payload (websocket.payload.text), and it reassembles fragmented messages. Useful filters are websocket.opcode == 9 || websocket.opcode == 10 for ping and pong, websocket.opcode == 8 for closes (the status code is websocket.payload.close.status_code) and http.upgrade for the handshake requests. Wireshark cannot read the frames inside wss:// unless you give it the TLS secrets: start the browser with the SSLKEYLOGFILE environment variable set to a file, then point Wireshark’s TLS preferences to the "(Pre)-Master-Secret log filename". For permessage-deflate traffic Wireshark can inflate messages when the context-takeover parameters allow it (the websocket.decompression.failed.expert field flags failures). Use unencrypted ws:// on localhost for the examples of this page and capture the loopback interface.

Source: Chrome DevTools: Network features reference and Wireshark: WebSocket display filter reference