 The WebSocket logo | |
| International standard | RFC 6455,WebSockets |
|---|---|
| Developed by | IETF,WHATWG |
| Introduced | December 2011 (2011-12) |
| Industry | Computer science |
| Connector type | TCP |
WebSocket is a computercommunications protocol, providing abidirectional communication channel over a singleTransmission Control Protocol (TCP) connection. The WebSocket protocol was standardized by theIETF asRFC 6455 in 2011. The current specification allowing web applications to use this protocol is known asWebSockets.[1] It is a living standard maintained by theWHATWG and a successor toThe WebSocket API from theW3C.[2]
WebSocket is distinct fromHTTP 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", making the WebSocket protocol compatible with HTTP. To achieve compatibility, the WebSockethandshake uses theHTTP Upgrade header[3] to change from the HTTP protocol to the WebSocket protocol.
The WebSocket protocol enablesfull-duplex interaction between aweb browser (or otherclient application) and aweb server with lower overhead than half-duplex alternatives such as HTTPpolling, facilitating real-time data transfer from and to the server. This is achieved 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 exchanged 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 TCPport number 443 (or 80 in the case of unsecured connections), which is beneficial for environments that block non-web Internet connections using afirewall. 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 asComet orAdobe Flash Player.[4]
Most browsers support the protocol, includingGoogle Chrome,Firefox,Microsoft Edge,Internet Explorer,Safari andOpera.[5] Its utility also extends to desktop applications, such as the social virtual reality platformResonite[6] which, as well as its predecessorNeosVR, uses WebSockets for real-time integrations with external services and hardware.
The WebSocket protocol specification definesws (WebSocket) andwss (WebSocket Secure) as two newuniform resource identifier (URI) schemes[7] that are used for unencrypted and encrypted connections respectively. Apart from the scheme name andfragment (i.e.# is not supported), the rest of the URI components are defined to useURI generic syntax.[8]
WebSocket was first referenced as TCPConnection in theHTML5 specification, as a placeholder for a TCP-based socket API.[9] In June 2008, a series of discussions were led byMichael Carter that resulted in the first version of the protocol known as WebSocket.[10]Before WebSocket, port 80 full-duplex communication was attainable usingComet 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 byIan Hickson and Michael Carter shortly thereafter through collaboration on the #whatwg IRC chat room,[11] 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.[12] Development of the WebSocket protocol was subsequently moved from the W3C andWHATWG group to the IETF in February 2010, and authored for two revisions under Ian Hickson.[13]
After the protocol was shipped and enabled by default in multiple browsers, theRFC 6455 was finalized under Ian Fette in December 2011.
RFC 7692 introduced compression extension to WebSocket using theDEFLATE algorithm on a per-message basis.
A web application (e.g. web browser) may use theWebSocket interface to maintain bidirectional communications with a WebSocket server.[14]
InTypeScript.
// Connect to serverconstws:WebSocket=newWebSocket("wss://game.example.com/scoreboard");// Receive ArrayBuffer instead of Blobws.binaryType="arraybuffer";// Set event listenersws.onopen=():void=>{console.log("Connection opened");ws.send("Hi server, please send me the score of yesterday's game");};ws.onmessage=(event:MessageEvent):void=>{console.log("Message received",event.data);ws.close();// We got the score so we don't need the connection anymore};ws.onclose=(event:CloseEvent):void=>{console.log("Connection closed",event.code,event.reason,event.wasClean);};ws.onerror=(event:Event):void=>{console.log("Connection closed due to error");};
| Type | Name[15] | Description |
|---|---|---|
| Constructor | ws = newWebSocket(url: string, protocols?: string | string[]) | Start opening handshake.[16]
Exceptions:
|
| Method | ws.send(data: string | Blob | ArrayBuffer | ArrayBufferView) | Send data message.[17]
Return: Exceptions:
Note:
|
ws.close(code?: number, reason?: string) | Startclosing handshake.[18]
Return: Exceptions:
Note:
| |
| Event | ws.onopen = (event: Event): void => {}
| Opening handshake succeeded.event type isEvent. |
ws.onmessage = (event: MessageEvent): void => {}
| Data message received.[19]event type isMessageEvent. This event is only fired ifws.readyState isOPEN.
| |
ws.onclose = (event: CloseEvent): void => {}
| The underlyingTCP connection closed.event type isCloseEvent containing:[20][21][22][23]
Note:
| |
ws.onerror = (event: Event): void => {}
| Connection closed due to error.event type isEvent. | |
| Attribute | ws.binaryType (string) | Type ofevent.data inws.onmessage when a binary data message is received. Initially set to"blob" (Blob object). May be changed to"arraybuffer" (ArrayBuffer object).[24] |
| Read-only attribute | ws.url (string) | URL given to theWebSocket constructor with the following transformations:
|
ws.bufferedAmount (number) | Number of bytes of application data (UTF-8 text and binary data) that have beenqueued usingws.send() but not yet transmitted to the network. It resets to zero once all queued data has been sent. If the connection closes, this value will only increase, with each call tows.send(), and never reset to zero.[25] | |
ws.protocol (string) | Protocol accepted by the server, or an empty string if the client did not specifyprotocols in theWebSocket constructor. | |
ws.extensions (string) | Extensions accepted by the server. | |
ws.readyState (number) | Connection state. It is one of the constants below. Initially set toCONNECTING.[26] | |
| Constant | WebSocket.CONNECTING = 0 | Opening handshake is currently in progress. The initial state of the connection.[27][28] |
WebSocket.OPEN = 1 | Opening handshake succeeded. The client and server may send messages to each other.[29][30] | |
WebSocket.CLOSING = 2 | Closing handshake is currently in progress. Eitherws.close() was called or aClose message was received.[31][32] | |
WebSocket.CLOSED = 3 | The underlyingTCP connection is closed.[33][20][21] |
Steps:
The client sends anHTTP request (methodGET,version ≥ 1.1) and the server returns anHTTP response withstatus code 101 (Switching Protocols) on success. HTTP and WebSocket clients can connect to a server using the same port because the opening handshake uses HTTP. Sending additional HTTP headers (that are not in the table below) is allowed. HTTP headers may be sent in any order. After theSwitching Protocols HTTP response, the opening handshake is complete, the HTTP protocol stops being used, and communication switches to a binary frame-based protocol.[34][35]
Side | Header | Value | Mandatory |
|---|---|---|---|
Request | Origin[36] | Varies | Yes (for browser clients) |
| Host[37] | Varies | Yes | |
| Sec-WebSocket-Version[38] | 13 | ||
| Sec-WebSocket-Key[39] | base64-encode(16-byte randomnonce) | ||
Response | Sec-WebSocket-Accept[40] | base64-encode(SHA1(Sec-WebSocket-Key +258EAFA5-E914-47DA-95CA-C5AB0DC85B11))[b] | |
Both | Connection[41][42] | Upgrade | |
| Upgrade[43][44] | websocket | ||
| Sec-WebSocket-Protocol[45] | The request may contain acomma-separated list of strings (ordered by preference) indicatingapplication-level protocols (built on top of WebSocket data messages) the client wishes to use. If the client sends this header, the server response must be one of the values from the list. | No | |
| Sec-WebSocket-Extensions[46][47][48][49] | Used to negotiate protocol-level extensions. The client may request extensions to the WebSocket protocol by including a comma-separated list of extensions (ordered by preference). Each extension may have a parameter (e.g. foo=4). The server may accept some or all extensions requested by the client. This field may appear multiple times in the request (logically equivalent to a single occurrence containing all values) and must not appear more than once in the response. |
Example request:[35]
GET/chatHTTP/1.1Host:server.example.comUpgrade:websocketConnection:UpgradeSec-WebSocket-Key:dGhlIHNhbXBsZSBub25jZQ==Origin:http://example.comSec-WebSocket-Protocol:chat, superchatSec-WebSocket-Version:13
Example response:[35]
HTTP/1.1101Switching ProtocolsUpgrade:websocketConnection:UpgradeSec-WebSocket-Accept:s3pPLMBiTxaQ9kYGzzhZRbK+xOo=Sec-WebSocket-Protocol:chat
The followingPython code generates a randomSec-WebSocket-Key.
importbase64importosprint(base64.b64encode(os.urandom(16)))
The following Python code calculatesSec-WebSocket-Accept usingSec-WebSocket-Key from the example request above.
importbase64importhashlibKEY:bytes=b"dGhlIHNhbXBsZSBub25jZQ=="MAGIC:bytes=b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"print(base64.b64encode(hashlib.sha1(KEY+MAGIC).digest()))
Sec-WebSocket-Key andSec-WebSocket-Accept are intended to prevent acachingproxy from re-sending a previous WebSocket conversation,[50] and does not provide any authentication, privacy, or integrity.
Though some servers accept a shortSec-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, senddata messages (text or binary) andcontrol messages (Close,Ping,Pong) to each other. A message is composed ofone frame if unfragmented orat least two frames if fragmented.
Fragmentation splits a message intotwo 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. It also enables multiplexing several streams simultaneously (e.g. to avoid monopolizing a socket for a single largepayload).[51][52]
FIN = 1 andopcode ≠ 0.FIN = 0 andopcode ≠ 0, followed by zero or more frames withFIN = 0 andopcode = 0, and terminated by one frame withFIN = 1 andopcode = 0.| Offset (bits) | Field[53] | Size (bits) | Description | |
|---|---|---|---|---|
| 0 | FIN[54] | 1 |
| |
| 1 | RSV1 | 1 | Reserved. Must be 0 unless defined by an extension. If a non-zero value is received and none of the negotiated extensions defines the meaning of such a non-zero value, the connection must be closed.[55] | |
| 2 | RSV2 | 1 | ||
| 3 | RSV3 | 1 | ||
| 4 | Opcode | 4 | Seeopcodes below. | |
| 8 | Masked[56] | 1 |
| |
| 9 | Payload length[57] | 7, 7+16 or 7+64 | Length of the payload (extension data + application data) in bytes.
| |
| Varies | Masking key[58] | 0 or 32 | Random nonce. Present if the masked field is 1. The client generates a masking key for every masked frame. | |
| Payload | Extension data | Payload length (bytes) | Must be empty unless defined by an extension. | |
| Application data | Depends on the opcode | |||
| Frame type[59] | Opcode[60] | Related | Description | Purpose | Fragmentable | Max. payload length (bytes) | |
|---|---|---|---|---|---|---|---|
| Continuation frame | 0 | Non-first frame of a fragmented message. | Message fragmentation | 263 − 1[c] | |||
| Non-control frame | Text | 1 | send(),onmessage | UTF-8-encoded text. | Data message | Yes | |
| Binary | 2 | Binary data. | |||||
| 3–7 | Reserved for further non-control frames. May be defined by an extension.[61] | ||||||
| Control frame[62] | Close | 8 | close(),onclose | The WebSocketclosing handshake starts upon either sending or receiving aClose frame.[63] It may prevent data loss by complementing theTCP closing handshake.[64] No frame can be sent after sending aClose frame. If aClose frame is received and no priorClose frame was sent, aClose frame must be sent in response (typically echoing the status code received). The payload is optional, but if present, it must start with a two-byte big-endian unsigned integerstatus code, optionally followed by a UTF-8-encoded reason message not longer than 123 bytes.[65] | Protocol state | No | 125 |
| Ping | 9 | May be used forlatency measurement,keepalive andheartbeat. Both sides cansend a ping (with any payload). Whoever receives it must, as soon as is practical,send back a pong with the same payload. A pong should be ignored if no prior ping was sent.[66][67][68] | |||||
| Pong | 10 | ||||||
| 11–15 | Reserved for further control frames. May be defined by an extension.[61] | ||||||
Aclient must mask all frames sent to the server. Aserver must not mask any frames sent to the client.[69] Frame masking appliesXOR between the payload and the masking key. The followingpseudocode describes the algorithm used to both mask and unmask a frame.[58]
for ifrom 0to payload_length − 1 payload[i] := payload[i] xor masking_key[i mod 4]
| Range[70] | Allowed inClose frame | Code | Description |
|---|---|---|---|
| 0–999 | No | Unused | |
| 1000–2999 (Protocol) | Yes | 1000 | Normal closure. |
| 1001 | Going away (e.g. browser tab closed; server going down). | ||
| 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 (i.e. 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 | Reserved for libraries, frameworks and applications. Registered directly withIANA. | |
| 4000–4999 | Private use. |
In Python.
Note:recv() returns up to the amount of bytes requested. For readability, the code ignores that, thus it may fail in non-ideal network conditions.
importbase64importhashlibimportstructfromtypingimportOptionalfromsocketimportsocketasSocketdefhandle_websocket_connection(ws:Socket)->None:# Accept connectionconn,addr=ws.accept()# Receive and parse HTTP requestkey:Optional[bytes]=Noneforlineinconn.recv(4096).split(b"\r\n"):ifline.startswith(b"Sec-WebSocket-Key"):key=line.split()[-1]ifkeyisNone:raiseValueError("Sec-WebSocket-Key not found")# Send HTTP responsesec_accept=base64.b64encode(hashlib.sha1(key+b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11").digest())conn.sendall(b"\r\n".join([b"HTTP/1.1 101 Switching Protocols",b"Connection: Upgrade",b"Upgrade: websocket",b"Sec-WebSocket-Accept: "+sec_accept,b"",b"",]))# Decode and print frameswhileTrue:byte0,byte1=conn.recv(2)fin:int=byte0>>7opcode:int=byte0&0b1111masked:int=byte1>>7assertmasked,"The client must mask all frames"ifopcode>=8:assertfin,"Control frames are unfragmentable"# Payload sizepayload_size:int=byte1&0b111_1111ifpayload_size==126:payload_size,=struct.unpack(">H",conn.recv(2))assertpayload_size>125,"The minimum number of bits must be used"elifpayload_size==127:payload_size,=struct.unpack(">Q",conn.recv(8))assertpayload_size>2**16-1,"The minimum number of bits must be used"assertpayload_size<=2**63-1,"The most significant bit must be zero"ifopcode>=8:assertpayload_size<=125,"Control frames must have up to 125 bytes"# Unmaskmasking_key:bytes=conn.recv(4)payload:bytearray=bytearray(conn.recv(payload_size))foriinrange(payload_size):payload[i]=payload[i]^masking_key[i%4]print("Received frame",FIN,opcode,payload)if__name__=="__main__":# Accept TCP connection on any interface at port 80ws:Socket=Socket()ws.bind(("",80))ws.listen()handle_websocket_connection(ws)
A secure version of the WebSocket protocol is implemented in Firefox 6,[72] Safari 6, Google Chrome 14,[73]Opera 12.10 andInternet Explorer 10.[74] A detailed protocol test suite report[75] lists the conformance of those browsers to specific protocol aspects.
An older, less secure version of the protocol was implemented in Opera 11 andSafari 5, as well as the mobile version of Safari iniOS 4.2.[76] The BlackBerry Browser in OS7 implements WebSockets.[77] Because of vulnerabilities, it was disabled in Firefox 4 and 5,[78] and Opera 11.[79]Using browser developer tools, developers can inspect the WebSocket handshake as well as the WebSocket frames.[80]
| Protocol version | Draft date | Internet Explorer | Firefox[81] (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[82][d] | ||||||
| hybi-10, v8 | July 11, 2011 | 7[84][d] | 7 | 14[85] | ||||
| RFC 6455, v13 | December, 2011 | 10[86] | 11 | 11 | 16[87] | 6 | 12.10[88] | 4.4 |
ASP.NET Core have support for WebSockets using theapp.UseWebSockets(); middleware.[96]
Unlike regular cross-domain HTTP requests, WebSocket requests are not restricted by thesame-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 tocross-site request forgery), which might be possible when the connection is authenticated withcookies 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.[97] A live example of vulnerability was seen in 2020 in the form ofCable Haunt.
WebSocket protocol client implementations try to detect whether theuser agent is configured to use a proxy when connecting to destination host and port, and if it is, usesHTTP CONNECT method to set up a persistent tunnel.
The WebSocket protocol is unaware of proxy servers and firewalls. 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.[98]
If an encrypted WebSocket connection is used, then the use ofTransport Layer Security (TLS) in the WebSocket Secure connection ensures that anHTTP 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 noHTTP 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 withreverse proxies and gateways by including eight bytes of key data after the headers, but not advertising that data in aContent-Length: 8 header.[99] This data was not forwarded by all intermediates, which could lead to protocol failure. More recent drafts (e.g., hybi-09[100]) put the key data in aSec-WebSocket-Key header, solving this problem.
TCP connections require a "client" and a "server". Flash Player can create client sockets.
The computation [...] is meant to prevent a caching intermediary from providing a WS-client with a cached WS-server reply without actual interaction with the WS-server.