Loading AI tools
Computer network protocol From Wikipedia, the free encyclopedia
WebSocket is a computer communications protocol, providing a simultaneous two-way communication channel over a single Transmission Control Protocol (TCP) connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011. The current specification allowing web applications to use this protocol is known as WebSockets.[1] It is a living standard maintained by the WHATWG and a successor to The WebSocket API from the W3C.[2]
![]() A diagram describing a connection using WebSocket | |
International standard | RFC 6455 |
---|---|
Developed by | IETF |
Industry | Computer science |
Connector type | TCP |
Website | https://websockets.spec.whatwg.org/ |
WebSocket is distinct from HTTP used to serve most webpages. Although they are different, RFC 6455 states that WebSocket "is designed to work over HTTP ports 443 and 80 as well as to support HTTP proxies and intermediaries", thus making it compatible with HTTP. To achieve compatibility, the WebSocket handshake uses the HTTP Upgrade header[3] to change from the HTTP protocol to the WebSocket protocol.
The WebSocket protocol enables full-duplex interaction between a web browser (or other client application) and a web server with lower overhead than half-duplex alternatives such as HTTP polling, facilitating real-time data transfer from and to the server. This is made possible by providing a standardized way for the server to send content to the client without being first requested by the client, and allowing messages to be passed back and forth while keeping the connection open. In this way, a two-way ongoing conversation can take place between the client and the server. The communications are usually done over TCP port number 443 (or 80 in the case of unsecured connections), which is beneficial for environments that block non-web Internet connections using a firewall. Additionally, WebSocket enables streams of messages on top of TCP. TCP alone deals with streams of bytes with no inherent concept of a message. Similar two-way browser–server communications have been achieved in non-standardized ways using stopgap technologies such as Comet or Adobe Flash Player.[4]
Most browsers support the protocol, including Google Chrome, Firefox, Microsoft Edge, Internet Explorer, Safari and Opera.[5]
The WebSocket protocol specification defines ws
(WebSocket) and wss
(WebSocket Secure) as two new uniform resource identifier (URI) schemes[6] that are used for unencrypted and encrypted connections respectively. Apart from the scheme name and fragment (i.e. #
is not supported), the rest of the URI components are defined to use URI generic syntax.[7]
WebSocket was first referenced as TCPConnection in the HTML5 specification, as a placeholder for a TCP-based socket API.[8] In June 2008, a series of discussions were led by Michael Carter that resulted in the first version of the protocol known as WebSocket.[9] Before WebSocket, port 80 full-duplex communication was attainable using Comet channels; however, Comet implementation is nontrivial, and due to the TCP handshake and HTTP header overhead, it is inefficient for small messages. The WebSocket protocol aims to solve these problems without compromising the security assumptions of the web. The name "WebSocket" was coined by Ian Hickson and Michael Carter shortly thereafter through collaboration on the #whatwg IRC chat room,[10] and subsequently authored for inclusion in the HTML5 specification by Ian Hickson. In December 2009, Google Chrome 4 was the first browser to ship full support for the standard, with WebSocket enabled by default.[11] Development of the WebSocket protocol was subsequently moved from the W3C and WHATWG group to the IETF in February 2010, and authored for two revisions under Ian Hickson.[12]
After the protocol was shipped and enabled by default in multiple browsers, the RFC 6455 was finalized under Ian Fette in December 2011.
RFC 7692 introduced compression extension to WebSocket using the DEFLATE algorithm on a per-message basis.
<!DOCTYPE html>
<script>
// Connect to server
ws = new WebSocket("ws://127.0.0.1/scoreboard") // Local server
// ws = new WebSocket("wss://game.example.com/scoreboard") // Remote server
ws.onopen = () => {
console.log("Connection opened")
ws.send("Hi server, please send me the score of yesterday's game")
}
ws.onmessage = (event) => {
console.log("Data received", event.data)
ws.close() // We got the score so we don't need the connection anymore
}
ws.onclose = (event) => {
console.log("Connection closed", event.code, event.reason, event.wasClean)
}
ws.onerror = () => {
console.log("Connection closed due to error")
}
</script>
from socket import socket
from base64 import b64encode
from hashlib import sha1
MAGIC = b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
# Create socket and listen at port 80
ws = socket()
ws.bind(("", 80))
ws.listen()
conn, addr = ws.accept()
# Parse request
for line in conn.recv(4096).split(b"\r\n"):
if line.startswith(b"Sec-WebSocket-Key"):
nonce = line.split(b":")[1].strip()
# Format response
response = f"""\
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: {b64encode(sha1(nonce + MAGIC).digest()).decode()}
"""
conn.send(response.replace("\n", "\r\n").encode())
while True: # decode messages from the client
header = conn.recv(2)
FIN = bool(header[0] & 0x80) # bit 0
assert FIN == 1, "We only support unfragmented messages"
opcode = header[0] & 0xf # bits 4-7
assert opcode == 1 or opcode == 2, "We only support data messages"
masked = bool(header[1] & 0x80) # bit 8
assert masked, "The client must mask all frames"
payload_size = header[1] & 0x7f # bits 9-15
assert payload_size <= 125, "We only support small messages"
masking_key = conn.recv(4)
payload = bytearray(conn.recv(payload_size))
for i in range(payload_size):
payload[i] = payload[i] ^ masking_key[i % 4]
print(payload)
A web application (e.g. web browser) may use the WebSocket
interface to connect to a WebSocket server.
Type | Name[13] | Description |
---|---|---|
Constructor | ws = new WebSocket(url [, protocols ]) |
Start opening handshake with a WebSocket server.[14]
|
Method | ws.send(data) |
Send data. data must be string , Blob , ArrayBuffer or ArrayBufferView . Throw InvalidStateError if ws.readyState is WebSocket.CONNECTING . |
ws.close([ code ] [, reason ]) |
Start closing handshake.[15]
| |
Event | ws.onopen = (event) => {}
|
Opening handshake succeeded. event type is Event . |
ws.onmessage = (event) => {}
|
Data received. event type is MessageEvent . event.data contains the data received, of type:[16]
| |
ws.onclose = (event) => {}
|
The underlying TCP connection closed. event type is CloseEvent containing:[17][18][19][20]
Note:
| |
ws.onerror = (event) => {}
|
Connection closed due to error. event type is Event . | |
Attribute | ws.binaryType |
A string indicating the type of event.data in ws.onmessage when binary data is received. Initially set to "blob" (Blob object). May be changed to "arraybuffer" (ArrayBuffer object). |
Read-only attribute | ws.url |
The URL given to the WebSocket constructor. |
ws.bufferedAmount |
The number of bytes waiting to be transmitted. | |
ws.protocol |
The protocol accepted by the server, or an empty string if the client did not specify protocols in the WebSocket constructor. | |
ws.extensions |
The extensions accepted by the server. | |
ws.readyState |
The connection state. It is one of the constants below. | |
Constant | WebSocket.CONNECTING = 0 |
Waiting opening handshake.[21][22] |
WebSocket.OPEN = 1 |
Opening handshake succeeded. The client and server may message each other.[23][24] | |
WebSocket.CLOSING = 2 |
Waiting closing handshake. Either ws.close() was called or the server sent a Close frame.[25][26] | |
WebSocket.CLOSED = 3 |
The underlying TCP connection is closed.[27][17][18] |
Steps:
The client sends an HTTP request (method GET, version ≥ 1.1) and the server returns an HTTP response with status code 101 (Switching Protocols) on success. This means a WebSocket server can use the same port as HTTP (80) and HTTPS (443) because the handshake is compatible with HTTP.[28]
Side |
Header | Value | Mandatory |
---|---|---|---|
Request |
Origin | Varies | Yes (for browser clients)[29] |
Host | Varies | Yes | |
Sec-WebSocket-Version | 13[30] | ||
Sec-WebSocket-Key | base64-encode(16-byte random nonce)[31] | ||
Response |
Sec-WebSocket-Accept | base64-encode(sha1(Sec-WebSocket-Key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))[32] | |
Both |
Connection | Upgrade[33][34] | |
Upgrade | websocket[35][36] | ||
Sec-WebSocket-Protocol | The request may contain a comma-separated list of strings (ordered by preference) indicating application-level protocols (built on top of WebSocket data messages) the client wishes to use.[37] If the client sends this header, the server response must be one of the values from the list. | Optional | |
Sec-WebSocket-Extensions | |||
Other headers | Varies |
Example request:[38]
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13
Origin: http://example.com
Example response:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat
In HTTP each line ends in \r\n
and the last line is empty.
# Calculate Sec-WebSocket-Accept using Sec-WebSocket-Key
from base64 import b64encode
from hashlib import sha1
from os import urandom
# key = b64encode(urandom(16)) # Client should do this
key = b"x3JJHMbDL1EzLkh9GBhXDw==" # Value in example request above
magic = b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11" # Protocol constant
print(b64encode(sha1(key + magic).digest()))
# Output: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Once the connection is established, communication switches to a binary frame-based protocol which does not conform to the HTTP protocol.
Sec-WebSocket-Key
and Sec-WebSocket-Accept
are intended to prevent a caching proxy from re-sending a previous WebSocket conversation,[39] and does not provide any authentication, privacy, or integrity.
Though some servers accept a short Sec-WebSocket-Key
, many modern servers will reject the request with error "invalid Sec-WebSocket-Key header".
After the opening handshake, the client and server can, at any time, send messages to each other, such as data messages (text or binary) and control messages (close, ping, pong). A message is composed of one or more frames.
Fragmentation allows a message to be split into two or more frames. It enables sending messages with initial data available but complete length unknown. Without fragmentation, the whole message must be sent in one frame, so the complete length is needed before the first byte can be sent, which requires a buffer.[40] It also enables multiplexing several streams simultaneously (e.g. to avoid monopolizing a socket for a single large payload).[41]
FIN = 1
and opcode ≠ 0
.FIN = 0
and opcode ≠ 0
, followed by zero or more frames with FIN = 0
and opcode = 0
, and terminated by a single frame with FIN = 1
and opcode = 0
.Index (in bits) |
Field | Size (in bits) |
Description | |
---|---|---|---|---|
0 | FIN[42] | 1 |
| |
1 | RSV1 | 1 | Must be 0 unless defined by an extension.[43] | |
2 | RSV2 | 1 | ||
3 | RSV3 | 1 | ||
4 | Opcode | 4 | See opcodes below. | |
8 | Masked[44] | 1 |
| |
9 | Payload length[45] | 7, 7+16 or 7+64 | Length of the payload (extension data + application data) in bytes.
| |
Varies | Masking key | 0 or 32 | A client must mask all frames sent to the server. A server must not mask any frames sent to the client.[46]
Frame masking applies XOR between the masking key (a four-byte random nonce) and the payload data. The following algorithm is used to mask/unmask a frame:[47]for i = 0 to payload_length - 1
payload[i] = payload[i] xor masking_key[i modulo 4]
| |
Payload | Extension data | Payload length (in bytes) | Must be empty unless defined by an extension. | |
Application data | Depends on the opcode. |
Frame type | Opcode | Related | Description | Purpose | Fragmentable |
Max. payload length | |
---|---|---|---|---|---|---|---|
Continuation | 0 | Identifies an intermediate frame of a fragmented message. | bytes | ||||
Data frame | Text | 1 | send() , onmessage |
UTF-8 encoded application text. | Application data | Yes | |
Binary | 2 | Application binary data. | |||||
3–7 | Reserved | ||||||
Control frame | Close | 8 | close() , onclose |
A Close frame is sent to start the closing handshake which may prevent data loss by complementing the TCP closing handshake.[48] No frame can be sent after a Close frame. If a Close frame is received and no prior Close frame was sent, a response Close frame with the same payload must be sent. The payload is optional, but if present, it must start with a two-byte big-endian unsigned integer reason code, optionally followed by a UTF-8 encoded reason message not longer than 123 bytes.[49] | Protocol state | No | 125 bytes |
Ping | 9 | May be used for latency measurement, keepalive and heartbeat. Both sides can initiate a ping (with any payload). Whoever receives it must immediately send back a pong with the same payload. A pong should be ignored if no prior ping was sent.[50][51] | |||||
Pong | 10 | ||||||
11–15 | Reserved |
Range[52] | Allowed in Close frame | Code | Description |
---|---|---|---|
0–999 | No | Unused | |
1000–2999 (Protocol) | Yes | 1000 | Normal closure. |
1001 | Going away (e.g. browser tab closed). | ||
1002 | Protocol error. | ||
1003 | Unsupported data (e.g. endpoint only understands text but received binary). | ||
No | 1004 | Reserved for future usage | |
1005 | No code received. | ||
1006 | Connection closed abnormally (closing handshake did not occur). | ||
Yes | 1007 | Invalid payload data (e.g. non UTF-8 data in a text message). | |
1008 | Policy violated. | ||
1009 | Message too big. | ||
1010 | Unsupported extension. The client should write the extensions it expected the server to support in the payload. | ||
1011 | Internal server error. | ||
No | 1015 | TLS handshake failure. | |
3000–3999 | Yes | Used by libraries, frameworks and applications. | |
4000–4999 | Private use. |
A secure version of the WebSocket protocol is implemented in Firefox 6,[54] Safari 6, Google Chrome 14,[55] Opera 12.10 and Internet Explorer 10.[56] A detailed protocol test suite report[57] lists the conformance of those browsers to specific protocol aspects.
An older, less secure version of the protocol was implemented in Opera 11 and Safari 5, as well as the mobile version of Safari in iOS 4.2.[58] The BlackBerry Browser in OS7 implements WebSockets.[59] Because of vulnerabilities, it was disabled in Firefox 4 and 5,[60] and Opera 11.[61] Using browser developer tools, developers can inspect the WebSocket handshake as well as the WebSocket frames.[62]
Protocol Version |
Draft date | Internet Explorer | Firefox[63] (PC) |
Firefox (Android) |
Chrome (PC, Mobile) |
Safari (Mac, iOS) |
Opera (PC, Mobile) |
Android Browser |
---|---|---|---|---|---|---|---|---|
hixie-75 | February 4, 2010 | 4 | 5.0.0 | |||||
hixie-76 hybi-00 |
May 6, 2010 May 23, 2010 |
4.0 (disabled) |
6 | 5.0.1 | 11.00 (disabled) |
|||
hybi-07, v7 | April 22, 2011 | 6[64][lower-alpha 1] | ||||||
hybi-10, v8 | July 11, 2011 | 7[66][lower-alpha 1] | 7 | 14[67] | ||||
RFC 6455, v13 | December, 2011 | 10[68] | 11 | 11 | 16[69] | 6 | 12.10[70] | 4.4 |
Unlike regular cross-domain HTTP requests, WebSocket requests are not restricted by the same-origin policy. Therefore, WebSocket servers must validate the "Origin" header against the expected origins during connection establishment, to avoid cross-site WebSocket hijacking attacks (similar to cross-site request forgery), which might be possible when the connection is authenticated with cookies or HTTP authentication. It is better to use tokens or similar protection mechanisms to authenticate the WebSocket connection when sensitive (private) data is being transferred over the WebSocket.[78] A live example of vulnerability was seen in 2020 in the form of Cable Haunt.
WebSocket protocol client implementations try to detect whether the user agent is configured to use a proxy when connecting to destination host and port, and if it is, uses HTTP CONNECT method to set up a persistent tunnel.
While the WebSocket protocol itself is unaware of proxy servers and firewalls, it features an HTTP-compatible handshake, thus allowing HTTP servers to share their default HTTP and HTTPS ports (80 and 443 respectively) with a WebSocket gateway or server. The WebSocket protocol defines a ws:// and wss:// prefix to indicate a WebSocket and a WebSocket Secure connection respectively. Both schemes use an HTTP upgrade mechanism to upgrade to the WebSocket protocol. Some proxy servers are transparent and work fine with WebSocket; others will prevent WebSocket from working correctly, causing the connection to fail. In some cases, additional proxy-server configuration may be required, and certain proxy servers may need to be upgraded to support WebSocket.
If unencrypted WebSocket traffic flows through an explicit or a transparent proxy server without WebSockets support, the connection will likely fail.[79]
If an encrypted WebSocket connection is used, then the use of Transport Layer Security (TLS) in the WebSocket Secure connection ensures that an HTTP CONNECT
command is issued when the browser is configured to use an explicit proxy server. This sets up a tunnel, which provides low-level end-to-end TCP communication through the HTTP proxy, between the WebSocket Secure client and the WebSocket server. In the case of transparent proxy servers, the browser is unaware of the proxy server, so no HTTP CONNECT
is sent. However, since the wire traffic is encrypted, intermediate transparent proxy servers may simply allow the encrypted traffic through, so there is a much better chance that the WebSocket connection will succeed if WebSocket Secure is used. Using encryption is not free of resource cost, but often provides the highest success rate, since it would be travelling through a secure tunnel.
A mid-2010 draft (version hixie-76) broke compatibility with reverse proxies and gateways by including eight bytes of key data after the headers, but not advertising that data in a Content-Length: 8
header.[80] This data was not forwarded by all intermediates, which could lead to protocol failure. More recent drafts (e.g., hybi-09[81]) put the key data in a Sec-WebSocket-Key
header, solving this problem.