Sec-WebSocket-Key: The Complete Guide to WebSocket Handshake Security (2025)

Introduction to Sec-WebSocket-Key

Understanding the WebSocket Handshake

Handshake Process Overview

1. Client Initiates Connection: The client sends an HTTP GET request with upgrade headers.
2. Server Validates and Responds: The server checks headers, processes the Sec-WebSocket-Key, and replies with an HTTP 101 Switching Protocols response.
3. Connection Established: Both parties switch to the WebSocket protocol for further communication.

WebSocket Handshake Flow

What is Sec-WebSocket-Key?

1GET /chat HTTP/1.1
2Host: server.example.com
3Upgrade: websocket
4Connection: Upgrade
5Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
6Sec-WebSocket-Version: 13
7

How Sec-WebSocket-Key Works

• The client generates a random 16-byte value.
• This value is base64-encoded and set as the Sec-WebSocket-Key header.
• The server reads the key, processes it (see next section), and responds with a corresponding header.

The Relationship between Sec-WebSocket-Key and Sec-WebSocket-Accept

1. Concatenation: The server appends the fixed GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 to the received Sec-WebSocket-Key.
2. SHA-1 Hashing: The concatenated string is hashed using the SHA-1 algorithm.
3. Base64 Encoding: The resulting hash is base64-encoded to produce the value of Sec-WebSocket-Accept.

Example: Generating Sec-WebSocket-Accept from Sec-WebSocket-Key

1const crypto = require('crypto');
2const secWebSocketKey = "dGhlIHNhbXBsZSBub25jZQ==";
3const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
4const accept = crypto
5  .createHash('sha1')
6  .update(secWebSocketKey + GUID)
7  .digest('base64');
8console.log(accept); // Should output: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
9

1HTTP/1.1 101 Switching Protocols
2Upgrade: websocket
3Connection: Upgrade
4Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
5

Security Implications and Misconceptions

• Prevent protocol downgrade and replay attacks by ensuring each handshake is unique.
• Distinguish WebSocket requests from generic HTTP requests, making it harder for proxies or attackers to spoof connections.
• Promote correct protocol implementation by requiring both parties to understand the handshake process.

Implementing WebSocket Handshake with Sec-WebSocket-Key

Node.js Example

1const http = require('http');
2const crypto = require('crypto');
3
4const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
5
6const server = http.createServer((req, res) => {
7  // Only handle WebSocket upgrade requests
8  if (req.headers['upgrade'] !== 'websocket') {
9    res.writeHead(400);
10    res.end('Not a WebSocket request');
11    return;
12  }
13  const key = req.headers['sec-websocket-key'];
14  const accept = crypto
15    .createHash('sha1')
16    .update(key + GUID)
17    .digest('base64');
18  res.writeHead(101, {
19    'Upgrade': 'websocket',
20    'Connection': 'Upgrade',
21    'Sec-WebSocket-Accept': accept
22  });
23  res.end();
24});
25
26server.listen(8080);
27

Python Example (using standard libraries)

1import base64
2import hashlib
3from http.server import BaseHTTPRequestHandler, HTTPServer
4
5GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
6
7class WSHandler(BaseHTTPRequestHandler):
8    def do_GET(self):
9        if self.headers.get('Upgrade', '').lower() != 'websocket':
10            self.send_error(400, 'Not a WebSocket request')
11            return
12        key = self.headers['Sec-WebSocket-Key']
13        accept = base64.b64encode(
14            hashlib.sha1((key + GUID).encode('utf-8')).digest()
15        ).decode('utf-8')
16        self.send_response(101)
17        self.send_header('Upgrade', 'websocket')
18        self.send_header('Connection', 'Upgrade')
19        self.send_header('Sec-WebSocket-Accept', accept)
20        self.end_headers()
21
22httpd = HTTPServer(('localhost', 8080), WSHandler)
23httpd.serve_forever()
24

Best Practices and Common Errors

• Always validate and sanitize incoming headers.
• Ensure the Sec-WebSocket-Key is exactly 16 bytes, base64-encoded.
• Respond only with HTTP 101 if all handshake headers are correct.
• Use existing WebSocket libraries in production for robust handling.

WebSocket Protocol Compliance and Browser Support

Troubleshooting Sec-WebSocket-Key Issues

• Malformed or missing Sec-WebSocket-Key: Ensure the client sends a valid, base64-encoded 16-byte key.
• Incorrect Sec-WebSocket-Accept: Double-check your server’s hash and encoding logic.
• Proxy interference: Some intermediaries strip or modify headers; configure proxies for WebSocket compliance.

• Use tools like Wireshark or Chrome DevTools to inspect handshake requests/responses.
• Log raw headers for failed handshakes.
• Validate base64-encoded key length and format before processing.

Conclusion: The Importance of Sec-WebSocket-Key in Secure WebSocket Connections