Skip to main content

4. Opening Handshake

The WebSocket Protocol's opening handshake is designed to be compatible with existing HTTP infrastructure. The handshake is an HTTP Upgrade request.

4.1 Client Requirements​

The handshake request sent by the client must be a valid HTTP request in the following format:

GET /chat HTTP/1.1
Host: server.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

Required Header Fields​

Host

  • Contains the server's host and port number
  • Complies with HTTP/1.1 specification

Upgrade: websocket

  • MUST include this header
  • Value is "websocket" (case-insensitive)

Connection: Upgrade

  • MUST include this header
  • Indicates this is an Upgrade request

Sec-WebSocket-Key

  • MUST include this header
  • Randomly generated 16-byte value, Base64 encoded
  • Used to verify server understands WebSocket protocol

Sec-WebSocket-Version: 13

  • MUST include this header
  • Current version number is 13

Optional Header Fields​

Origin

  • Browser clients MUST include
  • Non-browser clients MAY include
  • Used for server-side security validation

Sec-WebSocket-Protocol

  • OPTIONAL
  • Specifies list of subprotocols supported by client
  • Multiple values separated by commas

Sec-WebSocket-Extensions

  • OPTIONAL
  • Specifies extensions supported by client
  • Format: extension-name [; parameter=value]*

4.2 Server-Side Requirements​

The server must validate the client handshake and return an appropriate response.

4.2.1 Reading the Client's Opening Handshake​

The server MUST validate the following:

  1. HTTP method: Must be GET
  2. HTTP version: At least HTTP/1.1
  3. Required headers: Host, Upgrade, Connection, Sec-WebSocket-Key, Sec-WebSocket-Version must be present
  4. Sec-WebSocket-Version: Must be 13 (or a version supported by the server)

If validation fails, the server SHOULD return an appropriate HTTP error status code.

4.2.2 Sending the Server's Opening Handshake​

If validation succeeds, the server MUST send a handshake response:

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

Calculating Sec-WebSocket-Accept​

This is a critical part of the handshake. The server must calculate as follows:

  1. Take the client's Sec-WebSocket-Key value
  2. Concatenate with the fixed GUID string: 258EAFA5-E914-47DA-95CA-C5AB0DC85B11
  3. Perform SHA-1 hash on the concatenated string
  4. Base64 encode the hash result

Algorithm Example (JavaScript):

const crypto = require('crypto');

function generateAcceptKey(clientKey) {
  const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
  const concatenated = clientKey + GUID;
  const hash = crypto.createHash('sha1').update(concatenated).digest();
  return hash.toString('base64');
}

// Example
const clientKey = 'dGhlIHNhbXBsZSBub25jZQ==';
const acceptKey = generateAcceptKey(clientKey);
console.log(acceptKey); // s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

4.3 Collecting Extensions and Subprotocols​

Subprotocol Negotiation​

The client can list multiple subprotocols in the Sec-WebSocket-Protocol header:

Sec-WebSocket-Protocol: chat, superchat

The server MUST select one (or none) from the client's list and return it in the response:

Sec-WebSocket-Protocol: chat

If the server doesn't support any of the client's requested subprotocols, it may omit the Sec-WebSocket-Protocol header.

Extension Negotiation​

Extension negotiation occurs through the Sec-WebSocket-Extensions header:

Client Request:

Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits

Server Response:

Sec-WebSocket-Extensions: permessage-deflate

The server can accept, modify parameters, or reject extensions.

4.4 Supporting Multiple Versions​

If the server doesn't support the version requested by the client, it SHOULD return HTTP 426 Upgrade Required and include a Sec-WebSocket-Version header listing supported versions:

HTTP/1.1 426 Upgrade Required
Sec-WebSocket-Version: 13, 8, 7

Complete Handshake Examples​

Successful Handshake​

Client → Server:

GET /chat HTTP/1.1
Host: example.com:8000
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: chat
Sec-WebSocket-Version: 13
Origin: http://example.com

Server → Client:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat

Failed Handshake Examples​

Unsupported Version:

HTTP/1.1 426 Upgrade Required
Sec-WebSocket-Version: 13

Origin Not Accepted:

HTTP/1.1 403 Forbidden

Security Considerations​

  1. Validate Origin: Servers should validate the Origin header to prevent cross-site attacks
  2. Use TLS: Use wss:// in production environments
  3. Validate All Headers: Ensure all required headers are present and properly formatted
  4. Limit Connections: Implement rate limiting to prevent DoS attacks
Last updated on