Computer NetworksWebSocket Protocol

WebSocket: Full-Duplex Web Communication

LevelIntermediate

Duration60 mins

TopicWebSocket Protocol

2 / 5

WebSocket Handshake

The Protocol Upgrade Magic

How does a browser, speaking HTTP to a server, suddenly switch to an entirely different protocol? How does WebSocket coexist with billions of HTTP requests flowing through proxies, load balancers, and CDNs designed for HTTP? The answer lies in one of the most elegant protocol designs in modern networking: the WebSocket handshake.

The handshake is deceptively simple—a single HTTP request followed by a single HTTP response, and suddenly the connection is no longer HTTP at all. But within this apparent simplicity lies careful engineering: cryptographic security measures, compatibility considerations, and precise choreography between client and server.

Understanding the handshake is essential for troubleshooting connection failures, implementing WebSocket servers, and appreciating how new protocols can be deployed over existing infrastructure without breaking the internet.

What You Will Learn

By the end of this page, you will understand every component of the WebSocket handshake—the client's opening handshake request, the server's response, the security key exchange, and how the connection transitions from HTTP semantics to WebSocket framing. You'll be able to read raw handshake traffic and diagnose common connection failures.

The HTTP Upgrade Mechanism

WebSocket's handshake leverages an existing HTTP feature: the Upgrade header. HTTP/1.1 (RFC 2616, later RFC 7230) defines a mechanism allowing clients to request a protocol switch on an existing connection. This wasn't designed specifically for WebSocket—it's a general facility that WebSocket elegantly exploits.

The Upgrade Flow:

Client sends an HTTP request with Connection: Upgrade and Upgrade: websocket headers
If the server supports the requested protocol upgrade, it responds with 101 Switching Protocols
From that moment forward, the TCP connection no longer speaks HTTP—both parties use the upgraded protocol

This design is ingenious for several reasons:

Infrastructure Compatibility: Proxies and load balancers that don't understand WebSocket will see what looks like an HTTP request and forward it appropriately
Port Sharing: WebSocket uses the same ports as HTTP (80) and HTTPS (443), requiring no firewall configuration changes
Security Integration: HTTPS-based WebSocket (WSS) uses the existing TLS connection, inheriting all its security properties
Graceful Degradation: If the server doesn't support WebSocket, it returns a normal HTTP error, allowing clients to fallback

Beyond WebSocket

The HTTP Upgrade mechanism isn't exclusive to WebSocket. HTTP/2 originally used it for cleartext upgrades (h2c), and it's been proposed for other protocols. However, WebSocket remains the most widely deployed use of HTTP Upgrade. Most HTTP/2 deployments use ALPN (TLS negotiation) instead of Upgrade headers.

The Client Opening Handshake

When a browser executes new WebSocket('ws://example.com/chat'), it constructs and sends an HTTP GET request with specific headers. Let's examine each component of a typical client handshake:

GET /chat HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: http://example.com
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Extensions: permessage-deflate

Let's break down each header:

Client Handshake Headers Explained
Header	Value (Example)	Purpose	Required
`GET /chat HTTP/1.1`	Request line	Must be GET; path becomes WebSocket endpoint	Yes
`Host`	`example.com`	Standard HTTP host header; required in HTTP/1.1	Yes
`Upgrade`	`websocket`	Requests upgrade to WebSocket protocol	Yes
`Connection`	`Upgrade`	Indicates connection-level header follows	Yes
`Sec-WebSocket-Key`	Base64 random value	Security nonce; prevents caching attacks	Yes
`Sec-WebSocket-Version`	`13`	WebSocket protocol version (13 is final RFC)	Yes
`Origin`	Connecting page origin	Security; servers can reject cross-origin	Browser-required
`Sec-WebSocket-Protocol`	Subprotocol list	Application-level protocol negotiation	Optional
`Sec-WebSocket-Extensions`	Extension list	Compression, framing extensions	Optional

Critical Details:

The Request Method Must Be GET: POST, PUT, or other methods are not permitted. This aligns with the semantics—we're 'getting' a WebSocket connection, not submitting data.

HTTP Version Must Be 1.1 or Higher: HTTP/1.0 doesn't support persistent connections or the Upgrade mechanism. Clients must not attempt WebSocket over HTTP/1.0.

The Sec-WebSocket-Key: This 16-byte, base64-encoded random value is crucial to WebSocket security. We'll examine its purpose in detail shortly, but understand that the server must perform a specific transformation on this key and return the result. This prevents various attacks involving proxies and caching.

The Version Number: As of the final RFC 6455, the WebSocket version is 13. Earlier draft versions used different numbers (8, 13, etc.). Servers should reject unknown versions with a Sec-WebSocket-Version header indicating supported versions.

The Sec- Prefix

Headers beginning with 'Sec-' cannot be set by JavaScript using XMLHttpRequest or fetch(). Only the browser can set these headers. This is a security feature preventing malicious scripts from forging WebSocket handshakes. When you see a 'Sec-WebSocket-Key' header, you know it came from a genuine browser WebSocket implementation, not a forged request.

The Server Handshake Response

Upon receiving a valid WebSocket handshake request, the server must respond with a specific HTTP response to complete the upgrade:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat
Sec-WebSocket-Extensions: permessage-deflate

Let's examine each component:

Server Handshake Response Headers
Header	Value (Example)	Purpose	Required
`101 Switching Protocols`	Status line	HTTP status indicating protocol switch	Yes
`Upgrade`	`websocket`	Confirms upgrade to WebSocket	Yes
`Connection`	`Upgrade`	Confirms connection-level upgrade	Yes
`Sec-WebSocket-Accept`	Computed value	Proves server understands WebSocket	Yes
`Sec-WebSocket-Protocol`	Chosen subprotocol	Server's choice from client's list	If client sent list
`Sec-WebSocket-Extensions`	Accepted extensions	Extensions server will use	Optional

The 101 Status Code:

HTTP status code 101 specifically means 'Switching Protocols.' It's the only valid response for a successful WebSocket upgrade. Any other status code (200, 400, 404, etc.) indicates failure—the connection remains HTTP, and no WebSocket communication occurs.

Subprotocol Selection:

If the client specified Sec-WebSocket-Protocol: chat, superchat, the server must choose at most one from the list or omit the header entirely. The server cannot choose a protocol not offered by the client, and if it sends a Sec-WebSocket-Protocol header, it must exactly match one of the client's offerings.

Subprotocols are application-level concerns—they define what messages mean and how to structure them. Examples include:

graphql-ws for GraphQL subscriptions
mqtt for IoT messaging
stomp for message queuing
Custom protocols for specific applications

Extension Negotiation:

Extensions modify WebSocket framing behavior. The most common is permessage-deflate (RFC 7692), which compresses message payloads. The server's accepted extensions must be a subset of (or equal to) what the client offered.

After the Response

The instant after the server sends the final byte of its 101 response, the connection is no longer HTTP. Any subsequent data is WebSocket frames. The server can immediately begin sending frames; it doesn't need to wait for the client. Similarly, the client can begin sending frames immediately after receiving the 101 response.

The Security Key Exchange: Preventing Cross-Protocol Attacks

The Sec-WebSocket-Key and Sec-WebSocket-Accept headers constitute WebSocket's defense against a specific class of attacks. Understanding this mechanism reveals thoughtful protocol design.

The Problem: Cache Poisoning and Cross-Protocol Attacks

Before WebSocket, attacks existed where malicious content could be injected into HTTP caches by exploiting how intermediary proxies handled different protocols. A server speaking a non-HTTP protocol might send data that looks like an HTTP response to a confused proxy, poisoning its cache.

WebSocket's key exchange prevents this by ensuring:

The server genuinely supports WebSocket: It must correctly compute the Accept value, proving it's not just echoing bytes
The response is truly a WebSocket handshake: It cannot be confused with a cached HTTP response or data from another protocol

The Algorithm:

WebSocket Accept Key Computation

1. Take the Sec-WebSocket-Key from the client request
   Example: dGhlIHNhbXBsZSBub25jZQ==
 
2. Concatenate with the 'magic' GUID:
   258EAFA5-E914-47DA-95CA-C5AB0DC85B11
   
   Result: dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-C5AB0DC85B11
 
3. Compute the SHA-1 hash of the concatenated string
 
4. Base64 encode the 20-byte hash
 
5. Result is the Sec-WebSocket-Accept value:
   s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Why This Magic GUID?

The GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 is hardcoded in RFC 6455. It's essentially a random value that:

Is extremely unlikely to appear in any other protocol's data
Distinguishes WebSocket-aware servers from servers that might echo back headers blindly
Prevents pre-computation attacks (attackers can't predict Accept values without knowing the random Key)

What This Proves:

When a client receives a correct Sec-WebSocket-Accept value, it has proof that:

The server received the exact Sec-WebSocket-Key the client sent
The server computed a cryptographic hash (SHA-1) of specific data
The server is not simply echoing back HTTP headers or cached responses
The server understands the WebSocket protocol well enough to implement this handshake correctly

SHA-1 Security

You might wonder why WebSocket uses SHA-1, which is considered cryptographically weak for some applications. Here, SHA-1's role is not to provide cryptographic security (that's TLS's job) but merely to prove computation occurred. The key exchange isn't secret—it happens in cleartext. The goal is preventing confusion with other protocols, not encrypting anything.

Complete Handshake: Step-by-Step

Let's trace a complete WebSocket connection from JavaScript code to established connection:

Step 1: Client JavaScript Code

client.js
JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Browser JavaScript
const socket = new WebSocket('wss://chat.example.com/room/42');
 
socket.onopen = function(event) {
    console.log('Connection established!');
    socket.send(JSON.stringify({ type: 'join', user: 'Alice' }));
};
 
socket.onmessage = function(event) {
    const message = JSON.parse(event.data);
    console.log('Received:', message);
};
 
socket.onerror = function(error) {
    console.error('WebSocket error:', error);
};
 
socket.onclose = function(event) {
    console.log('Connection closed:', event.code, event.reason);
};

Step 2: Client HTTP Request (sent by browser)

client-request.http
HTTP
1
2
3
4
5
6
7
8
9
GET /room/42 HTTP/1.1
Host: chat.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Origin: https://myapp.example.com
Sec-WebSocket-Protocol: json, msgpack
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits

Step 3: Server Validates Request

The server validates:

Is this a GET request?
Is HTTP version 1.1 or higher?
Are Upgrade: websocket and Connection: Upgrade present?
Is Sec-WebSocket-Key a valid 16-byte base64 value?
Is Sec-WebSocket-Version 13?
Is the Origin acceptable? (access control)
Is the path (/room/42) a valid WebSocket endpoint?

Step 4: Server HTTP Response

server-response.http
HTTP
1
2
3
4
5
6
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: json
Sec-WebSocket-Extensions: permessage-deflate; server_max_window_bits=10

Step 5: Connection Upgraded

Immediately after the server sends the final \r\n of its response:

The TCP connection is now WebSocket, not HTTP
Server can immediately send WebSocket frames
Client's onopen callback fires
Browser begins processing any queued user calls to socket.send()

Key Observations:

The Sec-WebSocket-Accept value (HSmrc0sMlYUkAGmm5OPpG2HaGWk=) is computed from the client's key (x3JJHMbDL1EzLkh9GBhXDw==)
Server chose json from the client's two offered protocols
Server agreed to compression but negotiated a specific window size
The TLS layer (wss://) is transparent—the handshake happens after TLS negotiation

Handshake Failures: Diagnosis and Resolution

Not all handshakes succeed. Understanding common failure modes is essential for debugging WebSocket applications.

Common Handshake Failures
HTTP Status	Meaning	Common Cause	Resolution
400 Bad Request	Malformed handshake	Missing required headers, invalid Key format	Check client library; verify headers
403 Forbidden	Access denied	Origin not whitelisted, authentication failed	Check CORS config, include credentials
404 Not Found	Endpoint doesn't exist	Wrong path, WebSocket not configured on path	Verify server routes, check path spelling
426 Upgrade Required	Need different version	Server requires different WebSocket version	Check Sec-WebSocket-Version in response
500 Internal Server Error	Server crashed during handshake	Bug in server handshake code	Check server logs; fix handler code
502 Bad Gateway	Proxy can't connect	Backend server down or unreachable	Check backend availability; review proxy config
503 Service Unavailable	Server overloaded	Too many connections, resource exhaustion	Scale servers; implement connection limits

Browser-Specific Error Messages

•'WebSocket connection failed': Generic browser error—check server availability and network
•'Error during WebSocket handshake: Unexpected response code': Server returned non-101 status; check server logs
•'Mixed Content': Trying to connect ws:// from https:// page—use wss://
•'SecurityError': Blocked by Content Security Policy—update CSP to allow WebSocket endpoint
•Connection timeout: Server not responding to handshake—check firewall, server health

Debugging with Browser DevTools

Chrome/Firefox DevTools → Network → WS filter shows WebSocket connections. Click a connection to see the handshake request/response headers and all subsequent messages. For failed handshakes, check the HTTP response in the 'Headers' tab—the response status and headers reveal exactly why it failed.

Proxy and Load Balancer Considerations

Real-world WebSocket deployments must traverse various intermediaries: reverse proxies, load balancers, CDNs, corporate firewalls. Each presents unique challenges.

The Fundamental Challenge:

Most HTTP intermediaries expect request-response pairs. After forwarding a request, they expect a single response, then the conversation is 'done' for that request. WebSocket's persistent, bidirectional nature violates these assumptions.

Nginx Configuration Example:

nginx.conf
nginx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# WebSocket proxy configuration
upstream websocket_servers {
    server backend1:8080;
    server backend2:8080;
    # Note: sticky sessions may be needed if WebSocket servers share state
}
 
server {
    listen 443 ssl;
    server_name example.com;
    
    location /ws/ {
        proxy_pass http://websocket_servers;
        proxy_http_version 1.1;
        
        # Required: Pass upgrade headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # Preserve original client info
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # Timeouts for long-lived connections
        proxy_read_timeout 86400s;  # 24 hours
        proxy_send_timeout 86400s;
        
        # Buffering settings for real-time data
        proxy_buffering off;
    }
}

Key Configuration Points:

Upgrade Header Forwarding: The proxy must forward Upgrade and Connection headers. Without this, the backend never sees the WebSocket handshake.
HTTP/1.1 Required: proxy_http_version 1.1 is critical—HTTP/1.0 doesn't support Upgrade.
Extended Timeouts: Default HTTP timeouts (often 60 seconds) would kill WebSocket connections. Set timeouts appropriate for your application—often hours.
Buffering Disabled: HTTP proxies typically buffer responses. For real-time WebSocket, buffering adds unacceptable latency.
Sticky Sessions: If your WebSocket servers maintain per-connection state that isn't replicated, the load balancer must route reconnecting clients to the same server. IP-based or cookie-based affinity may be needed.

Cloud Load Balancers

AWS ALB, Google Cloud Load Balancer, and Azure Load Balancer all support WebSocket, but often with limitations. Check idle timeout settings (often 60 seconds by default), which require client-side ping implementation. Some require specific listener configurations. Always test WebSocket functionality; don't assume it 'just works' behind cloud infrastructure.

Security Considerations

The WebSocket handshake incorporates several security features, but applications must implement additional protections. Let's examine both the built-in security and required application-level measures.

Built-in Handshake Security:

Protocol-Level Protections

•Key Exchange: Prevents cross-protocol attacks and cache poisoning via the Sec-WebSocket-Key/Accept mechanism
•Origin Header: Browsers automatically include the Origin header; servers should validate it to prevent cross-site WebSocket hijacking
•Sec- Prefix Headers: Cannot be set by JavaScript—prevents malicious scripts from forging handshakes
•Client-to-Server Masking: All client frames are masked, preventing proxy cache poisoning from malicious WebSocket data
•TLS (wss://): When using Secure WebSocket, all communication (including handshake) is encrypted end-to-end

Required Application-Level Security:

You Must Implement

•Origin Validation: Don't accept connections from untrusted origins. Validate the Origin header against a whitelist.
•Authentication: WebSocket doesn't have a built-in auth mechanism. Authenticate during handshake (e.g., JWT in query string or cookie) or immediately after connection opens via a protocol message.
•Authorization: Verify users have permission for requested resources. Just because a user authenticated doesn't mean they can access every WebSocket endpoint.
•Input Validation: Every message from clients is untrusted input. Validate, sanitize, and reject malformed data.
•Rate Limiting: Impose limits on message frequency and size to prevent DoS. A single client shouldn't be able to flood your server.
•Message Size Limits: Set maximum payload sizes to prevent memory exhaustion attacks.

Common Vulnerability: CSRF for WebSocket

Cross-Site WebSocket Hijacking (CSWSH) is similar to CSRF but for WebSocket. An attacker's page can establish a WebSocket to your server if you don't validate the Origin header. The connection will carry the victim's cookies! Always validate Origin, and consider requiring explicit authentication tokens that aren't automatically sent by browsers.

Summary: The Handshake Foundation

The WebSocket handshake is a masterfully designed protocol transition mechanism. Let's consolidate the key technical details:

Key Takeaways

•HTTP Upgrade mechanism enables WebSocket to coexist with HTTP infrastructure—same ports, same initial connection
•Client handshake requires GET, HTTP/1.1+, Upgrade headers, Sec-WebSocket-Key (random base64), and Version 13
•Server response must be exactly 101 with Upgrade confirmation and correctly computed Sec-WebSocket-Accept
•Key exchange proves server WebSocket support via SHA-1 hash of client key + magic GUID
•Subprotocols and extensions are negotiated during handshake—server picks from client's offerings
•Common failure causes include misconfigured proxies, missing Upgrade headers, authentication failures, and Origin rejection
•Proxy configuration requires explicit support for Upgrade headers, extended timeouts, and disabled buffering
•Security combines protocol-level protections with mandatory application-level authentication and validation

What's Next:

With handshake mechanics thoroughly understood, the next page explores where WebSocket truly shines: concrete use cases ranging from real-time chat and live sports feeds to multiplayer gaming and collaborative editing. You'll see how the full-duplex capability we've established translates into solving real engineering problems.

Page Complete

You now possess detailed understanding of the WebSocket handshake—from the initial HTTP request through protocol upgrade to the security implications. This knowledge enables you to implement WebSocket servers, debug connection failures, and configure infrastructure correctly. Next, we'll explore the diverse use cases that make WebSocket invaluable in modern web development.

2 / 5

Loading learning content...

Computer NetworksWebSocket Protocol

WebSocket: Full-Duplex Web Communication

LevelIntermediate

Duration60 mins

TopicWebSocket Protocol

2 / 5

WebSocket Handshake

The Protocol Upgrade Magic

What You Will Learn

The HTTP Upgrade Mechanism

The Upgrade Flow:

Client sends an HTTP request with Connection: Upgrade and Upgrade: websocket headers
If the server supports the requested protocol upgrade, it responds with 101 Switching Protocols
From that moment forward, the TCP connection no longer speaks HTTP—both parties use the upgraded protocol

This design is ingenious for several reasons:

Infrastructure Compatibility: Proxies and load balancers that don't understand WebSocket will see what looks like an HTTP request and forward it appropriately
Port Sharing: WebSocket uses the same ports as HTTP (80) and HTTPS (443), requiring no firewall configuration changes
Security Integration: HTTPS-based WebSocket (WSS) uses the existing TLS connection, inheriting all its security properties
Graceful Degradation: If the server doesn't support WebSocket, it returns a normal HTTP error, allowing clients to fallback

Beyond WebSocket

The Client Opening Handshake

When a browser executes new WebSocket('ws://example.com/chat'), it constructs and sends an HTTP GET request with specific headers. Let's examine each component of a typical client handshake:

GET /chat HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: http://example.com
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Extensions: permessage-deflate

Let's break down each header:

Client Handshake Headers Explained
Header	Value (Example)	Purpose	Required
`GET /chat HTTP/1.1`	Request line	Must be GET; path becomes WebSocket endpoint	Yes
`Host`	`example.com`	Standard HTTP host header; required in HTTP/1.1	Yes
`Upgrade`	`websocket`	Requests upgrade to WebSocket protocol	Yes
`Connection`	`Upgrade`	Indicates connection-level header follows	Yes
`Sec-WebSocket-Key`	Base64 random value	Security nonce; prevents caching attacks	Yes
`Sec-WebSocket-Version`	`13`	WebSocket protocol version (13 is final RFC)	Yes
`Origin`	Connecting page origin	Security; servers can reject cross-origin	Browser-required
`Sec-WebSocket-Protocol`	Subprotocol list	Application-level protocol negotiation	Optional
`Sec-WebSocket-Extensions`	Extension list	Compression, framing extensions	Optional

Critical Details:

The Request Method Must Be GET: POST, PUT, or other methods are not permitted. This aligns with the semantics—we're 'getting' a WebSocket connection, not submitting data.

HTTP Version Must Be 1.1 or Higher: HTTP/1.0 doesn't support persistent connections or the Upgrade mechanism. Clients must not attempt WebSocket over HTTP/1.0.

The Sec- Prefix

The Server Handshake Response

Upon receiving a valid WebSocket handshake request, the server must respond with a specific HTTP response to complete the upgrade:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat
Sec-WebSocket-Extensions: permessage-deflate

Let's examine each component:

Server Handshake Response Headers
Header	Value (Example)	Purpose	Required
`101 Switching Protocols`	Status line	HTTP status indicating protocol switch	Yes
`Upgrade`	`websocket`	Confirms upgrade to WebSocket	Yes
`Connection`	`Upgrade`	Confirms connection-level upgrade	Yes
`Sec-WebSocket-Accept`	Computed value	Proves server understands WebSocket	Yes
`Sec-WebSocket-Protocol`	Chosen subprotocol	Server's choice from client's list	If client sent list
`Sec-WebSocket-Extensions`	Accepted extensions	Extensions server will use	Optional

The 101 Status Code:

Subprotocol Selection:

Subprotocols are application-level concerns—they define what messages mean and how to structure them. Examples include:

graphql-ws for GraphQL subscriptions
mqtt for IoT messaging
stomp for message queuing
Custom protocols for specific applications

Extension Negotiation:

After the Response

The Security Key Exchange: Preventing Cross-Protocol Attacks

The Sec-WebSocket-Key and Sec-WebSocket-Accept headers constitute WebSocket's defense against a specific class of attacks. Understanding this mechanism reveals thoughtful protocol design.

The Problem: Cache Poisoning and Cross-Protocol Attacks

WebSocket's key exchange prevents this by ensuring:

The server genuinely supports WebSocket: It must correctly compute the Accept value, proving it's not just echoing bytes
The response is truly a WebSocket handshake: It cannot be confused with a cached HTTP response or data from another protocol

The Algorithm:

WebSocket Accept Key Computation

1. Take the Sec-WebSocket-Key from the client request
   Example: dGhlIHNhbXBsZSBub25jZQ==
 
2. Concatenate with the 'magic' GUID:
   258EAFA5-E914-47DA-95CA-C5AB0DC85B11
   
   Result: dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-C5AB0DC85B11
 
3. Compute the SHA-1 hash of the concatenated string
 
4. Base64 encode the 20-byte hash
 
5. Result is the Sec-WebSocket-Accept value:
   s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Why This Magic GUID?

The GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 is hardcoded in RFC 6455. It's essentially a random value that:

Is extremely unlikely to appear in any other protocol's data
Distinguishes WebSocket-aware servers from servers that might echo back headers blindly
Prevents pre-computation attacks (attackers can't predict Accept values without knowing the random Key)

What This Proves:

When a client receives a correct Sec-WebSocket-Accept value, it has proof that:

The server received the exact Sec-WebSocket-Key the client sent
The server computed a cryptographic hash (SHA-1) of specific data
The server is not simply echoing back HTTP headers or cached responses
The server understands the WebSocket protocol well enough to implement this handshake correctly

SHA-1 Security

Complete Handshake: Step-by-Step

Let's trace a complete WebSocket connection from JavaScript code to established connection:

Step 1: Client JavaScript Code

client.js
JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Browser JavaScript
const socket = new WebSocket('wss://chat.example.com/room/42');
 
socket.onopen = function(event) {
    console.log('Connection established!');
    socket.send(JSON.stringify({ type: 'join', user: 'Alice' }));
};
 
socket.onmessage = function(event) {
    const message = JSON.parse(event.data);
    console.log('Received:', message);
};
 
socket.onerror = function(error) {
    console.error('WebSocket error:', error);
};
 
socket.onclose = function(event) {
    console.log('Connection closed:', event.code, event.reason);
};

Step 2: Client HTTP Request (sent by browser)

client-request.http
HTTP
1
2
3
4
5
6
7
8
9
GET /room/42 HTTP/1.1
Host: chat.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Origin: https://myapp.example.com
Sec-WebSocket-Protocol: json, msgpack
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits

Step 3: Server Validates Request

The server validates:

Is this a GET request?
Is HTTP version 1.1 or higher?
Are Upgrade: websocket and Connection: Upgrade present?
Is Sec-WebSocket-Key a valid 16-byte base64 value?
Is Sec-WebSocket-Version 13?
Is the Origin acceptable? (access control)
Is the path (/room/42) a valid WebSocket endpoint?

Step 4: Server HTTP Response

server-response.http
HTTP
1
2
3
4
5
6
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: json
Sec-WebSocket-Extensions: permessage-deflate; server_max_window_bits=10

Step 5: Connection Upgraded

Immediately after the server sends the final \r\n of its response:

The TCP connection is now WebSocket, not HTTP
Server can immediately send WebSocket frames
Client's onopen callback fires
Browser begins processing any queued user calls to socket.send()

Key Observations:

The Sec-WebSocket-Accept value (HSmrc0sMlYUkAGmm5OPpG2HaGWk=) is computed from the client's key (x3JJHMbDL1EzLkh9GBhXDw==)
Server chose json from the client's two offered protocols
Server agreed to compression but negotiated a specific window size
The TLS layer (wss://) is transparent—the handshake happens after TLS negotiation

Handshake Failures: Diagnosis and Resolution

Not all handshakes succeed. Understanding common failure modes is essential for debugging WebSocket applications.

Common Handshake Failures
HTTP Status	Meaning	Common Cause	Resolution
400 Bad Request	Malformed handshake	Missing required headers, invalid Key format	Check client library; verify headers
403 Forbidden	Access denied	Origin not whitelisted, authentication failed	Check CORS config, include credentials
404 Not Found	Endpoint doesn't exist	Wrong path, WebSocket not configured on path	Verify server routes, check path spelling
426 Upgrade Required	Need different version	Server requires different WebSocket version	Check Sec-WebSocket-Version in response
500 Internal Server Error	Server crashed during handshake	Bug in server handshake code	Check server logs; fix handler code
502 Bad Gateway	Proxy can't connect	Backend server down or unreachable	Check backend availability; review proxy config
503 Service Unavailable	Server overloaded	Too many connections, resource exhaustion	Scale servers; implement connection limits

Browser-Specific Error Messages

•'WebSocket connection failed': Generic browser error—check server availability and network
•'Error during WebSocket handshake: Unexpected response code': Server returned non-101 status; check server logs
•'Mixed Content': Trying to connect ws:// from https:// page—use wss://
•'SecurityError': Blocked by Content Security Policy—update CSP to allow WebSocket endpoint
•Connection timeout: Server not responding to handshake—check firewall, server health

Debugging with Browser DevTools

Proxy and Load Balancer Considerations

Real-world WebSocket deployments must traverse various intermediaries: reverse proxies, load balancers, CDNs, corporate firewalls. Each presents unique challenges.

The Fundamental Challenge:

Nginx Configuration Example:

nginx.conf
nginx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# WebSocket proxy configuration
upstream websocket_servers {
    server backend1:8080;
    server backend2:8080;
    # Note: sticky sessions may be needed if WebSocket servers share state
}
 
server {
    listen 443 ssl;
    server_name example.com;
    
    location /ws/ {
        proxy_pass http://websocket_servers;
        proxy_http_version 1.1;
        
        # Required: Pass upgrade headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # Preserve original client info
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # Timeouts for long-lived connections
        proxy_read_timeout 86400s;  # 24 hours
        proxy_send_timeout 86400s;
        
        # Buffering settings for real-time data
        proxy_buffering off;
    }
}

Key Configuration Points:

Upgrade Header Forwarding: The proxy must forward Upgrade and Connection headers. Without this, the backend never sees the WebSocket handshake.
HTTP/1.1 Required: proxy_http_version 1.1 is critical—HTTP/1.0 doesn't support Upgrade.
Extended Timeouts: Default HTTP timeouts (often 60 seconds) would kill WebSocket connections. Set timeouts appropriate for your application—often hours.
Buffering Disabled: HTTP proxies typically buffer responses. For real-time WebSocket, buffering adds unacceptable latency.
Sticky Sessions: If your WebSocket servers maintain per-connection state that isn't replicated, the load balancer must route reconnecting clients to the same server. IP-based or cookie-based affinity may be needed.

Cloud Load Balancers

Security Considerations

Built-in Handshake Security:

Protocol-Level Protections

•Key Exchange: Prevents cross-protocol attacks and cache poisoning via the Sec-WebSocket-Key/Accept mechanism
•Origin Header: Browsers automatically include the Origin header; servers should validate it to prevent cross-site WebSocket hijacking
•Sec- Prefix Headers: Cannot be set by JavaScript—prevents malicious scripts from forging handshakes
•Client-to-Server Masking: All client frames are masked, preventing proxy cache poisoning from malicious WebSocket data
•TLS (wss://): When using Secure WebSocket, all communication (including handshake) is encrypted end-to-end

Required Application-Level Security:

You Must Implement

•Origin Validation: Don't accept connections from untrusted origins. Validate the Origin header against a whitelist.
•Authentication: WebSocket doesn't have a built-in auth mechanism. Authenticate during handshake (e.g., JWT in query string or cookie) or immediately after connection opens via a protocol message.
•Authorization: Verify users have permission for requested resources. Just because a user authenticated doesn't mean they can access every WebSocket endpoint.
•Input Validation: Every message from clients is untrusted input. Validate, sanitize, and reject malformed data.
•Rate Limiting: Impose limits on message frequency and size to prevent DoS. A single client shouldn't be able to flood your server.
•Message Size Limits: Set maximum payload sizes to prevent memory exhaustion attacks.

Common Vulnerability: CSRF for WebSocket

Summary: The Handshake Foundation

The WebSocket handshake is a masterfully designed protocol transition mechanism. Let's consolidate the key technical details:

Key Takeaways

•HTTP Upgrade mechanism enables WebSocket to coexist with HTTP infrastructure—same ports, same initial connection
•Client handshake requires GET, HTTP/1.1+, Upgrade headers, Sec-WebSocket-Key (random base64), and Version 13
•Server response must be exactly 101 with Upgrade confirmation and correctly computed Sec-WebSocket-Accept
•Key exchange proves server WebSocket support via SHA-1 hash of client key + magic GUID
•Subprotocols and extensions are negotiated during handshake—server picks from client's offerings
•Common failure causes include misconfigured proxies, missing Upgrade headers, authentication failures, and Origin rejection
•Proxy configuration requires explicit support for Upgrade headers, extended timeouts, and disabled buffering
•Security combines protocol-level protections with mandatory application-level authentication and validation

What's Next:

Page Complete

2 / 5