idnits 2.16.02
/tmp/draft-ietf-hybi-thewebsocketprotocol-17.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** There are 7 instances of too long lines in the document, the longest one
being 10 characters in excess of 72.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (September 30, 2011) is 2794 days in the past. Is
this intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
** Downref: Normative reference to an Informational RFC: RFC 2818
** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446)
** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126)
== Outdated reference: draft-ietf-websec-origin has been published as RFC
6454
Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 HyBi Working Group I. Fette
3 Internet-Draft Google, Inc.
4 Intended status: Standards Track A. Melnikov
5 Expires: April 2, 2012 Isode Ltd
6 September 30, 2011
8 The WebSocket protocol
9 draft-ietf-hybi-thewebsocketprotocol-17
11 Abstract
13 The WebSocket protocol enables two-way communication between a client
14 running untrusted code running in a controlled environment to a
15 remote host that has opted-in to communications from that code. The
16 security model used for this is the Origin-based security model
17 commonly used by Web browsers. The protocol consists of an opening
18 handshake followed by basic message framing, layered over TCP. The
19 goal of this technology is to provide a mechanism for browser-based
20 applications that need two-way communication with servers that does
21 not rely on opening multiple HTTP connections (e.g. using
22 XMLHttpRequest or s and long polling).
24 Please send feedback to the hybi@ietf.org mailing list.
26 Status of this Memo
28 This Internet-Draft is submitted in full conformance with the
29 provisions of BCP 78 and BCP 79.
31 Internet-Drafts are working documents of the Internet Engineering
32 Task Force (IETF). Note that other groups may also distribute
33 working documents as Internet-Drafts. The list of current Internet-
34 Drafts is at http://datatracker.ietf.org/drafts/current/.
36 Internet-Drafts are draft documents valid for a maximum of six months
37 and may be updated, replaced, or obsoleted by other documents at any
38 time. It is inappropriate to use Internet-Drafts as reference
39 material or to cite them other than as "work in progress."
41 This Internet-Draft will expire on April 2, 2012.
43 Copyright Notice
45 Copyright (c) 2011 IETF Trust and the persons identified as the
46 document authors. All rights reserved.
48 This document is subject to BCP 78 and the IETF Trust's Legal
49 Provisions Relating to IETF Documents
50 (http://trustee.ietf.org/license-info) in effect on the date of
51 publication of this document. Please review these documents
52 carefully, as they describe your rights and restrictions with respect
53 to this document. Code Components extracted from this document must
54 include Simplified BSD License text as described in Section 4.e of
55 the Trust Legal Provisions and are provided without warranty as
56 described in the Simplified BSD License.
58 Table of Contents
60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
61 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . . 5
62 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 6
63 1.3. Opening Handshake . . . . . . . . . . . . . . . . . . . . 7
64 1.4. Closing Handshake . . . . . . . . . . . . . . . . . . . . 10
65 1.5. Design Philosophy . . . . . . . . . . . . . . . . . . . . 10
66 1.6. Security Model . . . . . . . . . . . . . . . . . . . . . . 11
67 1.7. Relationship to TCP and HTTP . . . . . . . . . . . . . . . 12
68 1.8. Establishing a Connection . . . . . . . . . . . . . . . . 12
69 1.9. Subprotocols Using the WebSocket protocol . . . . . . . . 12
70 2. Conformance Requirements . . . . . . . . . . . . . . . . . . . 14
71 2.1. Terminology and other conventions . . . . . . . . . . . . 14
72 3. WebSocket URIs . . . . . . . . . . . . . . . . . . . . . . . . 16
73 4. Opening Handshake . . . . . . . . . . . . . . . . . . . . . . 17
74 4.1. Client Requirements . . . . . . . . . . . . . . . . . . . 17
75 4.2. Server-side Requirements . . . . . . . . . . . . . . . . . 22
76 4.2.1. Reading the Client's Opening Handshake . . . . . . . . 23
77 4.2.2. Sending the Server's Opening Handshake . . . . . . . . 24
78 4.3. Collected ABNF for new header fields used in handshake . . 27
79 4.4. Supporting multiple versions of WebSocket protocol . . . . 28
80 5. Data Framing . . . . . . . . . . . . . . . . . . . . . . . . . 30
81 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 30
82 5.2. Base Framing Protocol . . . . . . . . . . . . . . . . . . 30
83 5.3. Client-to-Server Masking . . . . . . . . . . . . . . . . . 35
84 5.4. Fragmentation . . . . . . . . . . . . . . . . . . . . . . 36
85 5.5. Control Frames . . . . . . . . . . . . . . . . . . . . . . 38
86 5.5.1. Close . . . . . . . . . . . . . . . . . . . . . . . . 38
87 5.5.2. Ping . . . . . . . . . . . . . . . . . . . . . . . . . 39
88 5.5.3. Pong . . . . . . . . . . . . . . . . . . . . . . . . . 39
89 5.6. Data Frames . . . . . . . . . . . . . . . . . . . . . . . 40
90 5.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 40
91 5.8. Extensibility . . . . . . . . . . . . . . . . . . . . . . 41
92 6. Sending and Receiving Data . . . . . . . . . . . . . . . . . . 42
93 6.1. Sending Data . . . . . . . . . . . . . . . . . . . . . . . 42
94 6.2. Receiving Data . . . . . . . . . . . . . . . . . . . . . . 42
95 7. Closing the connection . . . . . . . . . . . . . . . . . . . . 44
96 7.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 44
97 7.1.1. Close the WebSocket Connection . . . . . . . . . . . . 44
98 7.1.2. Start the WebSocket Closing Handshake . . . . . . . . 44
99 7.1.3. The WebSocket Closing Handshake is Started . . . . . . 44
100 7.1.4. The WebSocket Connection is Closed . . . . . . . . . . 45
101 7.1.5. The WebSocket Connection Close Code . . . . . . . . . 45
102 7.1.6. The WebSocket Connection Close Reason . . . . . . . . 45
103 7.1.7. Fail the WebSocket Connection . . . . . . . . . . . . 46
104 7.2. Abnormal Closures . . . . . . . . . . . . . . . . . . . . 46
105 7.2.1. Client-Initiated Closure . . . . . . . . . . . . . . . 46
106 7.2.2. Server-Initiated Closure . . . . . . . . . . . . . . . 47
107 7.2.3. Recovering From Abnormal Closure . . . . . . . . . . . 47
108 7.3. Normal Closure of Connections . . . . . . . . . . . . . . 47
109 7.4. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 47
110 7.4.1. Defined Status Codes . . . . . . . . . . . . . . . . . 48
111 7.4.2. Reserved Status Code Ranges . . . . . . . . . . . . . 49
112 8. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 51
113 8.1. Handling Errors in UTF-8 Encoded Data . . . . . . . . . . 51
114 9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 52
115 9.1. Negotiating Extensions . . . . . . . . . . . . . . . . . . 52
116 9.2. Known Extensions . . . . . . . . . . . . . . . . . . . . . 53
117 10. Security Considerations . . . . . . . . . . . . . . . . . . . 54
118 10.1. Non-Browser Clients . . . . . . . . . . . . . . . . . . . 54
119 10.2. Origin Considerations . . . . . . . . . . . . . . . . . . 54
120 10.3. Attacks On Infrastructure (Masking) . . . . . . . . . . . 55
121 10.4. Implementation-Specific Limits . . . . . . . . . . . . . . 56
122 10.5. WebSocket client authentication . . . . . . . . . . . . . 56
123 10.6. Connection confidentiality and integrity . . . . . . . . . 57
124 10.7. Handling of invalid data . . . . . . . . . . . . . . . . . 57
125 10.8. Use of SHA-1 by the WebSocket handshake . . . . . . . . . 57
126 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 59
127 11.1. Registration of new URI Schemes . . . . . . . . . . . . . 59
128 11.1.1. Registration of "ws" Scheme . . . . . . . . . . . . . 59
129 11.1.2. Registration of "wss" Scheme . . . . . . . . . . . . . 60
130 11.2. Registration of the "WebSocket" HTTP Upgrade Keyword . . . 61
131 11.3. Registration of new HTTP Header Fields . . . . . . . . . . 61
132 11.3.1. Sec-WebSocket-Key . . . . . . . . . . . . . . . . . . 62
133 11.3.2. Sec-WebSocket-Extensions . . . . . . . . . . . . . . . 62
134 11.3.3. Sec-WebSocket-Accept . . . . . . . . . . . . . . . . . 63
135 11.3.4. Sec-WebSocket-Protocol . . . . . . . . . . . . . . . . 64
136 11.3.5. Sec-WebSocket-Version . . . . . . . . . . . . . . . . 64
137 11.4. WebSocket Extension Name Registry . . . . . . . . . . . . 65
138 11.5. WebSocket Subprotocol Name Registry . . . . . . . . . . . 66
139 11.6. WebSocket Version Number Registry . . . . . . . . . . . . 67
140 11.7. WebSocket Close Code Number Registry . . . . . . . . . . . 68
141 11.8. WebSocket Opcode Registry . . . . . . . . . . . . . . . . 70
142 11.9. WebSocket Framing Header Bits Registry . . . . . . . . . . 71
143 12. Using the WebSocket protocol from Other Specifications . . . . 72
144 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 73
145 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 74
146 14.1. Normative References . . . . . . . . . . . . . . . . . . . 74
147 14.2. Informative References . . . . . . . . . . . . . . . . . . 75
148 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 77
150 1. Introduction
152 1.1. Background
154 _This section is non-normative._
156 Historically, creating Web applications that need bidirectional
157 communication between a client and a server (e.g., instant messaging
158 and gaming applications) has required an abuse of HTTP to poll the
159 server for updates while sending upstream notifications as distinct
160 HTTP calls.[RFC6202]
162 This results in a variety of problems:
164 o The server is forced to use a number of different underlying TCP
165 connections for each client: one for sending information to the
166 client, and a new one for each incoming message.
168 o The wire protocol has a high overhead, with each client-to-server
169 message having an HTTP header.
171 o The client-side script is forced to maintain a mapping from the
172 outgoing connections to the incoming connection to track replies.
174 A simpler solution would be to use a single TCP connection for
175 traffic in both directions. This is what the WebSocket protocol
176 provides. Combined with the WebSocket API, it provides an
177 alternative to HTTP polling for two-way communication from a Web page
178 to a remote server. [WSAPI]
180 The same technique can be used for a variety of Web applications:
181 games, stock tickers, multiuser applications with simultaneous
182 editing, user interfaces exposing server-side services in real time,
183 etc.
185 The WebSocket protocol is designed to supersede existing
186 bidirectional communication technologies which use HTTP as a
187 transport layer to benefit from existing infrastructure (proxies,
188 filtering, authentication). Such technologies were implemented as
189 trade-offs between efficiency and reliability because HTTP was not
190 initially meant to be used for bidirectional communication (see
191 [RFC6202] for further discussion). The WebSocket protocol attempts
192 to address the goals of existing bidirectional HTTP technologies in
193 the context of the existing HTTP infrastructure; as such, it is
194 designed to work over HTTP ports 80 and 443 as well as to support
195 HTTP proxies and intermediaries, even if this implies some complexity
196 specific to the current environment. However, the design does not
197 limit WebSocket to HTTP, and future implementations could use a
198 simpler handshake over a dedicated port without revinventing the
199 entire protocol. This last point is important because the traffic
200 patterns of interactive messaging do not closely match standard HTTP
201 traffic and can induce unusual loads on some components.
203 1.2. Protocol Overview
205 _This section is non-normative._
207 The protocol has two parts: a handshake, and then the data transfer.
209 The handshake from the client looks as follows:
211 GET /chat HTTP/1.1
212 Host: server.example.com
213 Upgrade: websocket
214 Connection: Upgrade
215 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
216 Origin: http://example.com
217 Sec-WebSocket-Protocol: chat, superchat
218 Sec-WebSocket-Version: 13
220 The handshake from the server looks as follows:
222 HTTP/1.1 101 Switching Protocols
223 Upgrade: websocket
224 Connection: Upgrade
225 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
226 Sec-WebSocket-Protocol: chat
228 The leading line from the client follows the Request-Line format.
229 The leading line from the server follows the Status-Line format. The
230 Request-Line and Status-Line productions are defined in [RFC2616].
232 After the leading line in both cases come an unordered set of header
233 fields. The meaning of these header fields is specified in Section 4
234 of this document. Additional header fields may also be present, such
235 as cookies [RFC6265]. The format and parsing of headers is as
236 defined in [RFC2616].
238 Once the client and server have both sent their handshakes, and if
239 the handshake was successful, then the data transfer part starts.
240 This is a two-way communication channel where each side can,
241 independently from the other, send data at will.
243 Clients and servers, after a successful handshake, transfer data back
244 and forth in conceptual units referred to in this specification as
245 "messages". On the wire a message is composed of one or more frames.
246 The WebSocket message does not necessarily correspond to a particular
247 network layer framing, as a fragmented message may be coalesced or
248 split by an intermediary.
250 A frame has an associated type. Each frame belonging to the same
251 message contain the same type of data. Broadly speaking, there are
252 types for textual data, which is interpreted as UTF-8 [RFC3629] text,
253 binary data (whose interpretation is left up to the application), and
254 control frames, which are not intended to carry data for the
255 application, but instead for protocol-level signaling, such as to
256 signal that the connection should be closed. This version of the
257 protocol defines six frame types and leaves ten reserved for future
258 use.
260 1.3. Opening Handshake
262 _This section is non-normative._
264 The opening handshake is intended to be compatible with HTTP-based
265 server-side software and intermediaries, so that a single port can be
266 used by both HTTP clients talking to that server and WebSocket
267 clients talking to that server. To this end, the WebSocket client's
268 handshake is an HTTP Upgrade request:
270 GET /chat HTTP/1.1
271 Host: server.example.com
272 Upgrade: websocket
273 Connection: Upgrade
274 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
275 Origin: http://example.com
276 Sec-WebSocket-Protocol: chat, superchat
277 Sec-WebSocket-Version: 13
279 In compliance with [RFC2616], header fields in the handshake may be
280 sent by the client in any order, so the order in which different
281 header fields are received is not significant.
283 The "Request-URI" of the GET method [RFC2616] is used to identify the
284 endpoint of the WebSocket connection, both to allow multiple domains
285 to be served from one IP address and to allow multiple WebSocket
286 endpoints to be served by a single server.
288 The client includes the hostname in the Host header field of its
289 handshake as per [RFC2616], so that both the client and the server
290 can verify that they agree on which host is in use.
292 Additional header fields are used to select options in the WebSocket
293 protocol. Typical options available in this version are the
294 subprotocol selector (|Sec-WebSocket-Protocol|), list of extensions
295 support by the client (|Sec-WebSocket-Extensions|), |Origin| header
296 field, etc. The |Sec-WebSocket-Protocol| request-header field can be
297 used to indicate what subprotocols (application-level protocols
298 layered over the WebSocket protocol) are acceptable to the client.
299 The server selects one or none of the acceptable protocols and echoes
300 that value in its handshake to indicate that it has selected that
301 protocol.
302 Sec-WebSocket-Protocol: chat
304 The |Origin| header field [I-D.ietf-websec-origin] is used to protect
305 against unauthorized cross-origin use of a WebSocket server by
306 scripts using the |WebSocket| API in a Web browser. The server is
307 informed of the script origin generating the WebSocket connection
308 request. If the server does not wish to accept connections from this
309 origin, it can choose to reject the connection by sending an
310 appropriate HTTP error code. This header field is sent by browser
311 clients, for non-browser clients this header field may be sent if it
312 makes sense in the context of those clients.
314 Finally, the server has to prove to the client that it received the
315 client's WebSocket handshake, so that the server doesn't accept
316 connections that are not WebSocket connections. This prevents an
317 attacker from tricking a WebSocket server by sending it carefully-
318 crafted packets using |XMLHttpRequest| [XMLHttpRequest] or a |form|
319 submission.
321 To prove that the handshake was received, the server has to take two
322 pieces of information and combine them to form a response. The first
323 piece of information comes from the |Sec-WebSocket-Key| header field
324 in the client handshake:
326 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
328 For this header field, the server has to take the value (as present
329 in the header field, e.g. the base64-encoded [RFC4648] version minus
330 any leading and trailing whitespace), and concatenate this with the
331 Globally Unique Identifier (GUID, [RFC4122]) "258EAFA5-E914-47DA-
332 95CA-C5AB0DC85B11" in string form, which is unlikely to be used by
333 network endpoints that do not understand the WebSocket protocol. A
334 SHA-1 hash (160 bits), base64-encoded (see Section 4 of [RFC4648]),
335 of this concatenation is then returned in the server's handshake
336 [FIPS.180-2.2002].
338 Concretely, if as in the example above, |Sec-WebSocket-Key| header
339 field had the value "dGhlIHNhbXBsZSBub25jZQ==", the server would
340 concatenate the string "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" to form
341 the string "dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-
342 C5AB0DC85B11". The server would then take the SHA-1 hash of this,
343 giving the value 0xb3 0x7a 0x4f 0x2c 0xc0 0x62 0x4f 0x16 0x90 0xf6
344 0x46 0x06 0xcf 0x38 0x59 0x45 0xb2 0xbe 0xc4 0xea. This value is
345 then base64-encoded (see Section 4 of [RFC4648]), to give the value
346 "s3pPLMBiTxaQ9kYGzzhZRbK+xOo=". This value would then be echoed in
347 the |Sec-WebSocket-Accept| header field.
349 The handshake from the server is much simpler than the client
350 handshake. The first line is an HTTP Status-Line, with the status
351 code 101:
353 HTTP/1.1 101 Switching Protocols
355 Any status code other than 101 indicates that the WebSocket handshake
356 has not completed, and that the semantics of HTTP still apply. The
357 headers follow the status code.
359 The |Connection| and |Upgrade| header fields complete the HTTP
360 Upgrade. The |Sec-WebSocket-Accept| header field indicates whether
361 the server is willing to accept the connection. If present, this
362 header field must include a hash of the client's nonce sent in |Sec-
363 WebSocket-Key| along with a predefined GUID. Any other value must
364 not be interpreted as an acceptance of the connection by the server.
366 HTTP/1.1 101 Switching Protocols
367 Upgrade: websocket
368 Connection: Upgrade
369 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
371 These fields are checked by the |WebSocket| client for scripted
372 pages. If the |Sec-WebSocket-Accept| value does not match the
373 expected value, or if the header field is missing, or if the HTTP
374 status code is not 101, the connection will not be established and
375 WebSocket frames will not be sent.
377 Option fields can also be included. In this version of the protocol,
378 the main option field is |Sec-WebSocket-Protocol|, which indicates
379 the subprotocol that the server has selected. WebSocket clients
380 verify that the server included one of the values as was specified in
381 the WebSocket client's handshake. A server that speaks multiple
382 subprotocols has to make sure it selects one based on the client's
383 handshake and specifies it in its handshake.
385 Sec-WebSocket-Protocol: chat
387 The server can also set cookie-related option fields to _set_
388 cookies, as described in [RFC6265].
390 1.4. Closing Handshake
392 _This section is non-normative._
394 The closing handshake is far simpler than the opening handshake.
396 Either peer can send a control frame with data containing a specified
397 control sequence to begin the closing handshake (detailed in
398 Section 5.5.1). Upon receiving such a frame, the other peer sends a
399 close frame in response, if it hasn't already sent one. Upon
400 receiving _that_ control frame, the first peer then closes the
401 connection, safe in the knowledge that no further data is
402 forthcoming.
404 After sending a control frame indicating the connection should be
405 closed, a peer does not send any further data; after receiving a
406 control frame indicating the connection should be closed, a peer
407 discards any further data received.
409 It is safe for both peers to initiate this handshake simultaneously.
411 The closing handshake is intended to complement the TCP closing
412 handshake (FIN/ACK), on the basis that the TCP closing handshake is
413 not always reliable end-to-end, especially in the presence of
414 intercepting proxies and other intermediaries.
416 By sending a close frame and waiting for a close frame in response,
417 certain cases are avoided where data may be unnecessarily lost. For
418 instance, on some platforms, if a socket is closed with data in the
419 receive queue, a RST packet is sent, which will then cause recv() to
420 fail for the party that received the RST, even if there was data
421 waiting to be read.
423 1.5. Design Philosophy
425 _This section is non-normative._
427 The WebSocket protocol is designed on the principle that there should
428 be minimal framing (the only framing that exists is to make the
429 protocol frame-based instead of stream-based, and to support a
430 distinction between Unicode text and binary frames). It is expected
431 that metadata would be layered on top of WebSocket by the application
432 layer, in the same way that metadata is layered on top of TCP by the
433 application layer (e.g., HTTP).
435 Conceptually, WebSocket is really just a layer on top of TCP that
436 does the following:
438 o adds a Web "origin"-based security model for browsers
440 o adds an addressing and protocol naming mechanism to support
441 multiple services on one port and multiple host names on one IP
442 address;
444 o layers a framing mechanism on top of TCP to get back to the IP
445 packet mechanism that TCP is built on, but without length limits
447 o includes an additional closing handshake in-band that is designed
448 to work in the presence of proxies and other intermediaries
450 Other than that, WebSocket adds nothing. Basically it is intended to
451 be as close to just exposing raw TCP to script as possible given the
452 constraints of the Web. It's also designed in such a way that its
453 servers can share a port with HTTP servers, by having its handshake
454 be a valid HTTP Upgrade request mechanism also. One could
455 conceptually use other protocols to establish client-server
456 messaging, but the intent of WebSockets was to provide a relatively
457 simple protocol that can coexist with HTTP and deployed HTTP
458 infrastructure (such as proxies) that is as close to TCP as is safe
459 for use with such infrastructure given security considerations, with
460 targeted additions to simplify usage and make simple things simple
461 (such as the addition of message semantics).
463 The protocol is intended to be extensible; future versions will
464 likely introduce additional concepts such as multiplexing.
466 1.6. Security Model
468 _This section is non-normative._
470 The WebSocket protocol uses the origin model used by Web browsers to
471 restrict which Web pages can contact a WebSocket server when the
472 WebSocket protocol is used from a Web page. Naturally, when the
473 WebSocket protocol is used by a dedicated client directly (i.e. not
474 from a Web page through a Web browser), the origin model is not
475 useful, as the client can provide any arbitrary origin string.
477 This protocol is intended to fail to establish a connection with
478 servers of pre-existing protocols like SMTP [RFC5321] and HTTP, while
479 allowing HTTP servers to opt-in to supporting this protocol if
480 desired. This is achieved by having a strict and elaborate
481 handshake, and by limiting the data that can be inserted into the
482 connection before the handshake is finished (thus limiting how much
483 the server can be influenced).
485 It is similarly intended to fail to establish a connection when data
486 from other protocols, especially HTTP, is sent to a WebSocket server,
487 for example as might happen if an HTML |form| were submitted to a
488 WebSocket server. This is primarily achieved by requiring that the
489 server prove that it read the handshake, which it can only do if the
490 handshake contains the appropriate parts which themselves can only be
491 sent by a WebSocket handshake. In particular, at the time of writing
492 of this specification, fields starting with |Sec-| cannot be set by
493 an attacker from a Web browser using only HTML and JavaScript APIs
494 such as |XMLHttpRequest| [XMLHttpRequest].
496 1.7. Relationship to TCP and HTTP
498 _This section is non-normative._
500 The WebSocket protocol is an independent TCP-based protocol. Its
501 only relationship to HTTP is that its handshake is interpreted by
502 HTTP servers as an Upgrade request.
504 By default the WebSocket protocol uses port 80 for regular WebSocket
505 connections and port 443 for WebSocket connections tunneled over TLS
506 [RFC2818].
508 1.8. Establishing a Connection
510 _This section is non-normative._
512 When a connection is to be made to a port that is shared by an HTTP
513 server (a situation that is quite likely to occur with traffic to
514 ports 80 and 443), the connection will appear to the HTTP server to
515 be a regular GET request with an Upgrade offer. In relatively simple
516 setups with just one IP address and a single server for all traffic
517 to a single hostname, this might allow a practical way for systems
518 based on the WebSocket protocol to be deployed. In more elaborate
519 setups (e.g. with load balancers and multiple servers), a dedicated
520 set of hosts for WebSocket connections separate from the HTTP servers
521 is probably easier to manage. At the time of writing of this
522 specification, it should be noted that connections on port 80 and 443
523 have significantly different success rates, with connections on port
524 443 being significantly more likely to succeed, though this may
525 change with time.
527 1.9. Subprotocols Using the WebSocket protocol
529 _This section is non-normative._
530 The client can request that the server use a specific subprotocol by
531 including the |Sec-WebSocket-Protocol| field in its handshake. If it
532 is specified, the server needs to include the same field and one of
533 the selected subprotocol values in its response for the connection to
534 be established.
536 These subprotocol names should be registered as per Section 11.5. To
537 avoid potential collisions, it is recommended to use names that
538 contain the ASCII version of the domain name of the subprotocol's
539 originator. For example, if Example Corporation were to create a
540 Chat subprotocol to be implemented by many servers around the Web,
541 they could name it "chat.example.com". If the Example Organization
542 called their competing subprotocol "chat.example.org", then the two
543 subprotocols could be implemented by servers simultaneously, with the
544 server dynamically selecting which subprotocol to use based on the
545 value sent by the client.
547 Subprotocols can be versioned in backwards-incompatible ways by
548 changing the subprotocol name, e.g. going from "bookings.example.net"
549 to "v2.bookings.example.net". These subprotocols would be considered
550 completely separate by WebSocket clients. Backwards-compatible
551 versioning can be implemented by reusing the same subprotocol string
552 but carefully designing the actual subprotocol to support this kind
553 of extensibility.
555 2. Conformance Requirements
557 All diagrams, examples, and notes in this specification are non-
558 normative, as are all sections explicitly marked non-normative.
559 Everything else in this specification is normative.
561 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
562 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
563 document are to be interpreted as described in RFC2119. [RFC2119]
565 Requirements phrased in the imperative as part of algorithms (such as
566 "strip any leading space characters" or "return false and abort these
567 steps") are to be interpreted with the meaning of the key word
568 ("must", "should", "may", etc) used in introducing the algorithm.
570 Conformance requirements phrased as algorithms or specific steps MAY
571 be implemented in any manner, so long as the end result is
572 equivalent. (In particular, the algorithms defined in this
573 specification are intended to be easy to follow, and not intended to
574 be performant.)
576 2.1. Terminology and other conventions
578 _ASCII_ shall mean the character-encoding scheme defined in
579 [ANSI.X3-4.1986].
581 This document makes reference to UTF-8 values and uses UTF-8
582 notational formats as defined in STD 63 [RFC3629].
584 Key Terms such as named algorithms or definitions are indicated like
585 _this_.
587 Names of header fields or variables are indicated like |this|.
589 Variable values are indicated like /this/.
591 This document references the procedure to _Fail the WebSocket
592 Connection_. This procedure is defined in Section 7.1.7.
594 _Converting a string to ASCII lowercase_ means replacing all
595 characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER
596 A to LATIN CAPITAL LETTER Z) with the corresponding characters in the
597 range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL
598 LETTER Z).
600 Comparing two strings in an _ASCII case-insensitive_ manner means
601 comparing them exactly, code point for code point, except that the
602 characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER
603 A to LATIN CAPITAL LETTER Z) and the corresponding characters in the
604 range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL
605 LETTER Z) are considered to also match.
607 The term "URI" is used in this document as defined in [RFC3986].
609 When an implementation is required to _send_ data as part of the
610 WebSocket protocol, the implementation MAY delay the actual
611 transmission arbitrarily, e.g. buffering data so as to send fewer IP
612 packets.
614 Note that this document uses both [RFC5234] and [RFC2616] variants of
615 ABNF in different sections.
617 3. WebSocket URIs
619 This specification defines two URI schemes, using the ABNF syntax
620 defined in RFC 5234 [RFC5234], and terminology and ABNF productions
621 defined by the URI specification RFC 3986 [RFC3986].
623 ws-URI = "ws:" "//" host [ ":" port ] path [ "?" query ]
624 wss-URI = "wss:" "//" host [ ":" port ] path [ "?" query ]
626 host =
627 port =
628 path =
629 query =
631 The port component is OPTIONAL; the default for "ws" is port 80,
632 while the default for "wss" is port 443.
634 The URI is called "secure" (and it said that "the secure flag is
635 set") if the scheme component matches "wss" case-insensitively.
637 The "resource-name" (also known as /resource name/ in Section 4.1)
638 can be constructed by concatenating
640 o "/" if the path component is empty
642 o the path component
644 o "?" if the query component is non-empty
646 o the query component
648 Fragment identifiers are meaningless in the context of WebSocket
649 URIs, and MUST NOT be used on these URIs. The character "#" in URIs
650 MUST be escaped as %23 if used as part of the query component.
652 4. Opening Handshake
654 4.1. Client Requirements
656 To _Establish a WebSocket Connection_, a client opens a connection
657 and sends a handshake as defined in this section. A connection is
658 defined to initially be in a CONNECTING state. A client will need to
659 supply a /host/, /port/, /resource name/, and a /secure/ flag, which
660 are the components of a WebSocket URI as discussed in Section 3,
661 along with a list of /protocols/ and /extensions/ to be used.
662 Additionally, if the client is a web browser, it supplies /origin/.
664 Clients running in controlled environments, e.g. browsers on mobile
665 handsets tied to specific carriers, MAY offload the management of the
666 connection to another agent on the network. In such a situation, the
667 client for the purposes of this specification is considered to
668 include both the handset software and any such agents.
670 When the client is to _Establish a WebSocket Connection_ given a set
671 of (/host/, /port/, /resource name/, and /secure/ flag), along with a
672 list of /protocols/ and /extensions/ to be used, and an /origin/ in
673 the case of web browsers, it MUST open a connection, send an opening
674 handshake, and read the server's handshake in response. The exact
675 requirements of how the connection should be opened, what should be
676 sent in the opening handshake, and how the server's response should
677 be interpreted, are as follows in this section. In the following
678 text, we will use terms from Section 3 such as "/host/" and "/secure/
679 flag" as defined in that section.
681 1. The components of the WebSocket URI passed into this algorithm
682 (/host/, /port/, /resource name/ and /secure/ flag) MUST be valid
683 according to the specification of WebSocket URIs specified in
684 Section 3. If any of the components are invalid, the client MUST
685 _Fail the WebSocket Connection_ and abort these steps.
687 2. If the client already has a WebSocket connection to the remote
688 host (IP address) identified by /host/ and port /port/ pair, even
689 if the remote host is known by another name, the client MUST wait
690 until that connection has been established or for that connection
691 to have failed. There MUST be no more than one connection in a
692 CONNECTING state. If multiple connections to the same IP address
693 are attempted simultaneously, the client MUST serialize them so
694 that there is no more than one connection at a time running
695 through the following steps.
697 If the client cannot determine the IP address of the remote host
698 (for example because all communication is being done through a
699 proxy server that performs DNS queries itself), then the client
700 MUST assume for the purposes of this step that each host name
701 refers to a distinct remote host, and instead the client SHOULD
702 limit the total number of simultaneous pending connections to a
703 reasonably low number (e.g., the client might allow simultaneous
704 pending connections to a.example.com and b.example.com, but if
705 thirty simultaneous connections to a single host are requested,
706 that may not be allowed). For example in a Web browser context,
707 the client needs to consider the number of tabs the user has open
708 in setting a limit to the number of simultaneous pending
709 connections.
711 NOTE: This makes it harder for a script to perform a denial of
712 service attack by just opening a large number of WebSocket
713 connections to a remote host. A server can further reduce the
714 load on itself when attacked by pausing before closing the
715 connection, as that will reduce the rate at which the client
716 reconnects.
718 NOTE: There is no limit to the number of established WebSocket
719 connections a client can have with a single remote host. Servers
720 can refuse to accept connections from hosts/IP addresses with an
721 excessive number of existing connections, or disconnect resource-
722 hogging connections when suffering high load.
724 3. _Proxy Usage_: If the client is configured to use a proxy when
725 using the WebSocket protocol to connect to host /host/ and port
726 /port/, then the client SHOULD connect to that proxy and ask it
727 to open a TCP connection to the host given by /host/ and the port
728 given by /port/.
730 EXAMPLE: For example, if the client uses an HTTP proxy for all
731 traffic, then if it was to try to connect to port 80 on server
732 example.com, it might send the following lines to the proxy
733 server:
735 CONNECT example.com:80 HTTP/1.1
736 Host: example.com
738 If there was a password, the connection might look like:
740 CONNECT example.com:80 HTTP/1.1
741 Host: example.com
742 Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE=
744 If the client is not configured to use a proxy, then a direct TCP
745 connection SHOULD be opened to the host given by /host/ and the
746 port given by /port/.
748 NOTE: Implementations that do not expose explicit UI for
749 selecting a proxy for WebSocket connections separate from other
750 proxies are encouraged to use a SOCKS5 [RFC1928] proxy for
751 WebSocket connections, if available, or failing that, to prefer
752 the proxy configured for HTTPS connections over the proxy
753 configured for HTTP connections.
755 For the purpose of proxy autoconfiguration scripts, the URI to
756 pass the function MUST be constructed from /host/, /port/,
757 /resource name/, and the /secure/ flag using the definition of a
758 WebSocket URI as given in Section 3.
760 NOTE: The WebSocket protocol can be identified in proxy
761 autoconfiguration scripts from the scheme ("ws" for unencrypted
762 connections and "wss" for encrypted connections).
764 4. If the connection could not be opened, either because a direct
765 connection failed or because any proxy used returned an error,
766 then the client MUST _Fail the WebSocket Connection_ and abort
767 the connection attempt.
769 5. If /secure/ is true, the client MUST perform a TLS handshake over
770 the connection after opening the connection and before sending
771 the handshake data [RFC2818]. If this fails (e.g. the server's
772 certificate could not be verified), then the client MUST _Fail
773 the WebSocket Connection_ and abort the connection. Otherwise,
774 all further communication on this channel MUST run through the
775 encrypted tunnel. [RFC5246]
777 Clients MUST use the Server Name Indication extension in the TLS
778 handshake. [RFC6066]
780 Once a connection to the server has been established (including a
781 connection via a proxy or over a TLS-encrypted tunnel), the client
782 MUST send an opening handshake to the server. The handshake consists
783 of an HTTP upgrade request, along with a list of required and
784 optional header fields. The requirements for this handshake are as
785 follows.
787 1. The handshake MUST be a valid HTTP request as specified by
788 [RFC2616].
790 2. The Method of the request MUST be GET and the HTTP version MUST
791 be at least 1.1.
793 For example, if the WebSocket URI is "ws://example.com/chat",
794 The first line sent should be "GET /chat HTTP/1.1"
796 3. The "Request-URI" part of the request MUST match the /resource
797 name/ Section 3 (a relative URI), or be an absolute http/https
798 URI that, when parsed, has a /resource name/, /host/ and /port/
799 that match the corresponding ws/wss URI.
801 4. The request MUST contain a "Host" header field whose value is
802 equal to /host/.
804 5. The request MUST contain an "Upgrade" header field whose value
805 is equal to "websocket".
807 6. The request MUST contain a "Connection" header field whose value
808 MUST include the "Upgrade" token.
810 7. The request MUST include a header field with the name "Sec-
811 WebSocket-Key". The value of this header field MUST be a nonce
812 consisting of a randomly selected 16-byte value that has been
813 base64-encoded (see Section 4 of [RFC4648]). The nonce MUST be
814 selected randomly for each connection.
816 NOTE: As an example, if the randomly selected value was the
817 sequence of bytes 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
818 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f 0x10, the value of the header
819 field would be "AQIDBAUGBwgJCgsMDQ4PEC=="
821 8. The request MUST include a header field with the name "Origin"
822 [I-D.ietf-websec-origin] if the request is coming from a browser
823 client. If the connection is from a non-browser client, the
824 request MAY include this header field if the semantics of that
825 client match the use-case described here for browser clients.
826 The value of this header field is the ASCII serialization of
827 origin of the context in which the code establishing the
828 connection is running. See [I-D.ietf-websec-origin] for the
829 details of how this header field value is constructed.
831 As an example, if code downloaded from www.example.com attempts
832 to establish a connection to ww2.example.com, the value of the
833 header field would be "http://www.example.com".
835 9. The request MUST include a header field with the name "Sec-
836 WebSocket-Version". The value of this header field MUST be 13.
837 _Note: Although drafts -09, -10, -11 and -12 were published, as
838 they were mostly comprised of editorial changes and
839 clarifications and not changes to the wire protocol, values 9,
840 10, 11 and 12 were not used as valid values for Sec-WebSocket-
841 Version. These values were reserved in the IANA registry but
842 were not and will not be used._
844 10. The request MAY include a header field with the name "Sec-
845 WebSocket-Protocol". If present, this value indicates one or
846 more comma separated subprotocol the client wishes to speak,
847 ordered by preference. The elements that comprise this value
848 MUST be non-empty strings with characters in the range U+0021 to
849 U+007E not including separator characters as defined in
850 [RFC2616], and MUST all be unique strings. The ABNF for the
851 value of this header field is 1#token, where the definitions of
852 constructs and rules are as given in [RFC2616].
854 11. The request MAY include a header field with the name "Sec-
855 WebSocket-Extensions". If present, this value indicates the
856 protocol-level extension(s) the client wishes to speak. The
857 interpretation and format of this header field is described in
858 Section 9.1.
860 12. The request MAY include any other header fields, for example
861 cookies [RFC6265] and/or authentication related header fields
862 such as Authorization header field [RFC2616], which are
863 processed according to documents that define them.
865 Once the client's opening handshake has been sent, the client MUST
866 wait for a response from the server before sending any further data.
867 The client MUST validate the server's response as follows:
869 1. If the status code received from the server is not 101, the
870 client handles the response per HTTP [RFC2616] procedures, in
871 particular the client might perform authentication if it receives
872 401 status code, the server might redirect the client using a 3xx
873 status code (but clients are not required to follow them), etc.
874 Otherwise, proceed as follows.
876 2. If the response lacks an "Upgrade" header field or the "Upgrade"
877 header field contains a value that is not an ASCII case-
878 insensitive match for the value "websocket", the client MUST
879 _Fail the WebSocket Connection _.
881 3. If the response lacks a "Connection" header field or the
882 "Connection" header field doesn't contain a token that is an
883 ASCII case-insensitive match for the value "Upgrade", the client
884 MUST _Fail the WebSocket Connection_.
886 4. If the response lacks a "Sec-WebSocket-Accept" header field or
887 the "Sec-WebSocket-Accept" contains a value other than the
888 base64-encoded SHA-1 of the concatenation of the "Sec-WebSocket-
889 Key" (as a string, not base64-decoded) with the string "258EAFA5-
890 E914-47DA-95CA-C5AB0DC85B11", but ignoring any leading and
891 trailing whitespace, the client MUST _Fail the WebSocket
892 Connection_
894 5. If the response includes a "Sec-WebSocket-Extensions" header
895 field, and this header field indicates the use of an extension
896 that was not present in the client' handshake (the server has
897 indicated an extension not requested by the client), the client
898 MUST _Fail the WebSocket Connection_. (The parsing of this
899 header field to determine which extensions are requested is
900 discussed in Section 9.1.)
902 6. If the response includes a "Sec-WebSocket-Protocol" header field,
903 and this header field indicates the use of a subprotocol that was
904 not present in the client' handshake (the server has indicated a
905 subprotocol not requested by the client), the client MUST _Fail
906 the WebSocket Connection_.
908 If the server's response does not conform to the requirements for the
909 server's handshake as defined in this section and in Section 4.2.2,
910 the client MUST _Fail the WebSocket Connection_.
912 Please note that according to [RFC2616] all header field names in
913 both HTTP requests and HTTP responses are case-insensitive.
915 If the server's response is validated as provided for above, it is
916 said that _The WebSocket Connection is Established_ and that the
917 WebSocket Connection is in the OPEN state. The _Extensions In Use_
918 is defined to be a (possibly empty) string, the value of which is
919 equal to the value of the |Sec-WebSocket-Extensions| header field
920 supplied by the server's handshake, or the null value if that header
921 field was not present in the server's handshake. The _Subprotocol In
922 Use_ is defined to be the value of the |Sec-WebSocket-Protocol|
923 header field in the server's handshake, or the null value if that
924 header field was not present in the server's handshake.
925 Additionally, if any header fields in the server's handshake indicate
926 that cookies should be set (as defined by [RFC6265]), these cookies
927 are referred to as _Cookies Set During the Server's Opening
928 Handshake_.
930 4.2. Server-side Requirements
932 Servers MAY offload the management of the connection to other agents
933 on the network, for example load balancers and reverse proxies. In
934 such a situation, the server for the purposes of this specification
935 is considered to include all parts of the server-side infrastructure
936 from the first device to terminate the TCP connection all the way to
937 the server that processes requests and sends responses.
939 EXAMPLE: For example, a data center might have a server that responds
940 to WebSocket requests with an appropriate handshake, and then passes
941 the connection to another server to actually process the data frames.
942 For the purposes of this specification, the "server" is the
943 combination of both computers.
945 4.2.1. Reading the Client's Opening Handshake
947 When a client starts a WebSocket connection, it sends its part of the
948 opening handshake. The server must parse at least part of this
949 handshake in order to obtain the necessary information to generate
950 the server part of the handshake.
952 The client's opening handshake consists of the following parts. If
953 the server, while reading the handshake, finds that the client did
954 not send a handshake that matches the description below (note that as
955 per [RFC2616] the order of the header fields is not important),
956 including but not limited to any violations of the ABNF grammar
957 specified for the components of the handshake, the server MUST stop
958 processing the client's handshake, and return an HTTP response with
959 an appropriate error code (such as 400 Bad Request).
961 1. An HTTP/1.1 or higher GET request, including a "Request-URI"
962 [RFC2616] that should be interpreted as a /resource name/
963 Section 3 (or an absolute HTTP/HTTPS URI containing the
964 /resource name/).
966 2. A "Host" header field containing the server's authority.
968 3. An "Upgrade" header field containing the value "websocket",
969 treated as an ASCII case-insensitive value.
971 4. A "Connection" header field that includes the token "Upgrade",
972 treated as an ASCII case-insensitive value.
974 5. A "Sec-WebSocket-Key" header field with a base64-encoded (see
975 Section 4 of [RFC4648]) value that, when decoded, is 16 bytes in
976 length.
978 6. A "Sec-WebSocket-Version" header field, with a value of 13.
980 7. Optionally, an "Origin" header field. This header field is sent
981 by all browser clients. A connection attempt lacking this
982 header field SHOULD NOT be interpreted as coming from a browser
983 client.
985 8. Optionally, a "Sec-WebSocket-Protocol" header field, with a list
986 of values indicating which protocols the client would like to
987 speak, ordered by preference.
989 9. Optionally, a "Sec-WebSocket-Extensions" header field, with a
990 list of values indicating which extensions the client would like
991 to speak. The interpretation of this header field is discussed
992 in Section 9.1.
994 10. Optionally, other header fields, such as those used to send
995 cookies or request authentication to a server. Unknown header
996 fields are ignored, as per [RFC2616].
998 4.2.2. Sending the Server's Opening Handshake
1000 When a client establishes a WebSocket connection to a server, the
1001 server MUST complete the following steps to accept the connection and
1002 send the server's opening handshake.
1004 1. If the connection is happening on an HTTPS (HTTP-over-TLS) port,
1005 perform a TLS handshake over the connection. If this fails (e.g.
1006 the client indicated a host name in the extended client hello
1007 "server_name" extension that the server does not host), then
1008 close the connection; otherwise, all further communication for
1009 the connection (including the server's handshake) MUST run
1010 through the encrypted tunnel. [RFC5246]
1012 2. The server can perform additional client authentication, for
1013 example by returning a 401 status code with the corresponding
1014 WWW-Authenticate header field as described in [RFC2616].
1016 3. The server MAY redirect the client using a 3xx status code
1017 [RFC2616]. Note that this step can happen together with, before
1018 or after the optional authentication step described above.
1020 4. Establish the following information:
1022 /origin/
1023 The |Origin| header field in the client's handshake indicates
1024 the origin of the script establishing the connection. The
1025 origin is serialized to ASCII and converted to lowercase. The
1026 server MAY use this information as part of a determination of
1027 whether to accept the incoming connection. If the server does
1028 not validate the origin, it will accept connections from
1029 anywhere. If the server does not wish to accept this
1030 connection, it MUST return an appropriate HTTP error code
1031 (e.g. 403 Forbidden) and abort the WebSocket handshake
1032 described in this section. For more detail, refer to
1033 Section 10.
1035 /key/
1036 The |Sec-WebSocket-Key| header field in the client's handshake
1037 includes a base64-encoded value that, if decoded, is 16 bytes
1038 in length. This (encoded) value is used in the creation of
1039 the server's handshake to indicate an acceptance of the
1040 connection. It is not necessary for the server to base64-
1041 decode the "Sec-WebSocket-Key" value.
1043 /version/
1044 The |Sec-WebSocket-Version| header field in the client's
1045 handshake includes the version of the WebSocket protocol the
1046 client is attempting to communicate with. If this version
1047 does not match a version understood by the server, the server
1048 MUST abort the websocket handshake described in this section
1049 and instead send an appropriate HTTP error code (such as 426
1050 Upgrade Required), and a |Sec-WebSocket-Version| header field
1051 indicating the version(s) the server is capable of
1052 understanding.
1054 /resource name/
1055 An identifier for the service provided by the server. If the
1056 server provides multiple services, then the value should be
1057 derived from the resource name given in the client's handshake
1058 from the Request-URI [RFC2616] of the GET method. If the
1059 requested service is not available, the server MUST send an
1060 appropriate HTTP error code (such as 404 Not Found) and abort
1061 the WebSocket handshake.
1063 /subprotocol/
1064 Either a single value representing the subprotocol the server
1065 is ready to use or null. The value chosen MUST be derived
1066 from the client's handshake, specifically by selecting one of
1067 the values from the "Sec-WebSocket-Protocol" field that the
1068 server is willing to use for this connection (if any). If the
1069 client's handshake did not contain such a header field, or if
1070 the server does not agree to any of the client's requested
1071 subprotocols, the only acceptable value is null. The absence
1072 of such a field is equivalent to the null value (meaning that
1073 if the server does not wish to agree to one of the suggested
1074 subprotocols, it MUST NOT send back a |Sec-WebSocket-Protocol|
1075 header field in its response). The empty string is not the
1076 same as the null value for these purposes, and is not a legal
1077 value for this field. The ABNF for the value of this header
1078 field is (token), where the definitions of constructs and
1079 rules are as given in [RFC2616].
1081 /extensions/
1082 A (possibly empty) list representing the protocol-level
1083 extensions the server is ready to use. If the server supports
1084 multiple extensions, then the value MUST be derived from the
1085 client's handshake, specifically by selecting one or more of
1086 the values from the "Sec-WebSocket-Extensions" field. The
1087 absence of such a field is equivalent to the null value. The
1088 empty string is not the same as the null value for these
1089 purposes. Extensions not listed by the client MUST NOT be
1090 listed. The method by which these values should be selected
1091 and interpreted is discussed in Section 9.1.
1093 5. If the server chooses to accept the incoming connection, it MUST
1094 reply with a valid HTTP response indicating the following.
1096 1. A Status-Line with a 101 response code as per RFC 2616
1097 [RFC2616]. Such a response could look like "HTTP/1.1 101
1098 Switching Protocols"
1100 2. An "Upgrade" header field with value "websocket" as per RFC
1101 2616 [RFC2616].
1103 3. A "Connection" header field with value "Upgrade"
1105 4. A "Sec-WebSocket-Accept" header field. The value of this
1106 header field is constructed by concatenating /key/, defined
1107 above in Paragraph 4 of Section 4.2.2, with the string
1108 "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", taking the SHA-1 hash
1109 of this concatenated value to obtain a 20-byte value, and
1110 base64-encoding (see Section 4 of [RFC4648]) this 20-byte
1111 hash.
1113 The ABNF [RFC2616] of this header field is defined as
1114 follows:
1116 Sec-WebSocket-Accept = base64-value-non-empty
1117 base64-value-non-empty = (1*base64-data [ base64-padding ]) |
1118 base64-padding
1119 base64-data = 4base64-character
1120 base64-padding = (2base64-character "==") |
1121 (3base64-character "=")
1122 base64-character = ALPHA | DIGIT | "+" | "/"
1124 NOTE: As an example, if the value of the "Sec-WebSocket-Key"
1125 header field in the client's handshake were
1126 "dGhlIHNhbXBsZSBub25jZQ==", the server would append the
1127 string "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" to form the
1128 string "dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-
1129 C5AB0DC85B11". The server would then take the SHA-1 hash of
1130 this string, giving the value 0xb3 0x7a 0x4f 0x2c 0xc0 0x62
1131 0x4f 0x16 0x90 0xf6 0x46 0x06 0xcf 0x38 0x59 0x45 0xb2 0xbe
1132 0xc4 0xea. This value is then base64-encoded, to give the
1133 value "s3pPLMBiTxaQ9kYGzzhZRbK+xOo=", which would be returned
1134 in the "Sec-WebSocket-Accept" header field.
1136 5. Optionally, a "Sec-WebSocket-Protocol" header field, with a
1137 value /subprotocol/ as defined in Paragraph 4 of
1138 Section 4.2.2.
1140 6. Optionally, a "Sec-WebSocket-Extensions" header field, with a
1141 value /extensions/ as defined in Paragraph 4 of
1142 Section 4.2.2. If multiple extensions are to be used, they
1143 can all be listed in a single Sec-WebSocket-Extensions header
1144 field, or split between multiple instances of the Sec-
1145 WebSocket-Extensions header field.
1147 This completes the server's handshake. If the server finishes these
1148 steps without aborting the WebSocket handshake, the server considers
1149 the WebSocket connection to be established and that the WebSocket
1150 connection is in the OPEN state. At this point, the server may begin
1151 sending (and receiving) data.
1153 4.3. Collected ABNF for new header fields used in handshake
1155 This section is using ABNF syntax/rules from Section 2.1 of
1156 [RFC2616], including "implied *LWS rule".
1158 Note that the following ABNF conventions are used in this section:
1159 Some names of the rules correspond to names of the corresponding
1160 header fields. Such rules express values of the corresponding header
1161 fields, for example the Sec-WebSocket-Key ABNF rule describes syntax
1162 of the Sec-WebSocket-Key header field value. ABNF rules with the
1163 "-Client" suffix in the name are only used in requests sent by the
1164 client to the server; ABNF rules with the "-Server" suffix in the
1165 name are only used in responses sent by the server to the client.
1166 For example, the ABNF rule Sec-WebSocket-Protocol-Client describes
1167 syntax of the Sec-WebSocket-Protocol header field value sent by the
1168 client to the server.
1170 The following new header field can be sent during the handshake from
1171 the client to the server:
1173 Sec-WebSocket-Key = base64-value-non-empty
1174 Sec-WebSocket-Extensions = extension-list
1175 Sec-WebSocket-Protocol-Client = 1#token
1176 Sec-WebSocket-Version-Client = version
1178 base64-value-non-empty = (1*base64-data [ base64-padding ]) |
1179 base64-padding
1180 base64-data = 4base64-character
1181 base64-padding = (2base64-character "==") |
1182 (3base64-character "=")
1183 base64-character = ALPHA | DIGIT | "+" | "/"
1184 extension-list = 1#extension
1185 extension = extension-token *( ";" extension-param )
1186 extension-token = registered-token
1187 registered-token = token
1188 extension-param = token [ "=" (token | quoted-string) ]
1189 ;When using the quoted-string syntax variant, the value
1190 ;after quoted-string unescaping MUST conform to the 'token' ABNF.
1191 NZDIGIT = "1" | "2" | "3" | "4" | "5" | "6" |
1192 "7" | "8" | "9"
1193 version = DIGIT | (NZDIGIT DIGIT) |
1194 ("1" DIGIT DIGIT) | ("2" DIGIT DIGIT)
1195 ; Limited to 0-255 range, with no leading zeros
1197 The following new header field can be sent during the handshake from
1198 the server to the client:
1200 Sec-WebSocket-Extensions = extension-list
1201 Sec-WebSocket-Accept = base64-value-non-empty
1202 Sec-WebSocket-Protocol-Server = token
1203 Sec-WebSocket-Version-Server = 1#version
1205 4.4. Supporting multiple versions of WebSocket protocol
1207 This section provides some guidance on supporting multiple versions
1208 of the WebSocket protocol in clients and servers.
1210 Using the WebSocket version advertisement capability (the "Sec-
1211 WebSocket-Version" header field) client can initially request the
1212 version of the WebSocket protocol that it prefers (which doesn't
1213 necessarily have to be the latest supported by the client). If the
1214 server supports the requested version and the handshake message is
1215 otherwise valid, the server will accept that version. If the server
1216 doesn't support the requested version, it MUST respond with a Sec-
1217 WebSocket-Version header field (or multiple Sec-WebSocket-Version
1218 header fields) containing all versions it is willing to use. At this
1219 point, if the client supports one of the advertised versions, it can
1220 repeat the WebSocket handshake using a new version value.
1222 The following example demonstrates version negotiation described
1223 above:
1225 GET /chat HTTP/1.1
1226 Host: server.example.com
1227 Upgrade: websocket
1228 Connection: Upgrade
1229 ...
1230 Sec-WebSocket-Version: 25
1232 The response from the server might look as follows:
1234 HTTP/1.1 400 Bad Request
1235 ...
1236 Sec-WebSocket-Version: 13, 8, 7
1238 Note that the last response from the server might also look like:
1240 HTTP/1.1 400 Bad Request
1241 ...
1242 Sec-WebSocket-Version: 13
1243 Sec-WebSocket-Version: 8, 7
1245 The client now repeats the handshake that conforms to version 13:
1247 GET /chat HTTP/1.1
1248 Host: server.example.com
1249 Upgrade: websocket
1250 Connection: Upgrade
1251 ...
1252 Sec-WebSocket-Version: 13
1254 5. Data Framing
1256 5.1. Overview
1258 In the WebSocket protocol, data is transmitted using a sequence of
1259 frames. To avoid confusing network intermediaries (such as
1260 intercepting proxies) and for security reasons that are further
1261 discussed in Section 10.3, a client MUST mask all frames that it
1262 sends to the server (see Section 5.3 for further details). (Note
1263 that masking is done whether or not the WebSocket protocol is running
1264 over TLS.) The server MUST close the connection upon receiving a
1265 frame that is not masked. In this case, a server MAY send a close
1266 frame with a status code of 1002 (protocol error) as defined in
1267 Section 7.4.1. A server MUST NOT mask any frames that it sends to
1268 the client. A client MUST close a connection if it detects a masked
1269 frame. In this case, it MAY use the status code 1002 (protocol
1270 error) as defined in Section 7.4.1. (These rules might be relaxed in
1271 a future specification.)
1273 The base framing protocol defines a frame type with an opcode, a
1274 payload length, and designated locations for extension and
1275 application data, which together define the _payload_ data. Certain
1276 bits and opcodes are reserved for future expansion of the protocol.
1278 A data frame MAY be transmitted by either the client or the server at
1279 any time after opening handshake completion and before that endpoint
1280 has sent a close frame (Section 5.5.1).
1282 5.2. Base Framing Protocol
1284 This wire format for the data transfer part is described by the ABNF
1285 [RFC5234] given in detail in this section. (Note that unlike in
1286 other sections of this document the ABNF in this section is operating
1287 on groups of bits. The length of each group of bits is indicated in
1288 a comment. When encoded on the wire the most significant bit is the
1289 leftmost in the ABNF). A high level overview of the framing is given
1290 in the following figure. In a case of conflict between the figure
1291 below and the ABNF specified later in this section, the figure is
1292 authoritative.
1294 0 1 2 3
1295 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
1296 +-+-+-+-+-------+-+-------------+-------------------------------+
1297 |F|R|R|R| opcode|M| Payload len | Extended payload length |
1298 |I|S|S|S| (4) |A| (7) | (16/64) |
1299 |N|V|V|V| |S| | (if payload len==126/127) |
1300 | |1|2|3| |K| | |
1301 +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
1302 | Extended payload length continued, if payload len == 127 |
1303 + - - - - - - - - - - - - - - - +-------------------------------+
1304 | |Masking-key, if MASK set to 1 |
1305 +-------------------------------+-------------------------------+
1306 | Masking-key (continued) | Payload Data |
1307 +-------------------------------- - - - - - - - - - - - - - - - +
1308 : Payload Data continued ... :
1309 + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
1310 | Payload Data continued ... |
1311 +---------------------------------------------------------------+
1313 FIN: 1 bit
1315 Indicates that this is the final fragment in a message. The first
1316 fragment MAY also be the final fragment.
1318 RSV1, RSV2, RSV3: 1 bit each
1320 MUST be 0 unless an extension is negotiated which defines meanings
1321 for non-zero values. If a nonzero value is received and none of
1322 the negotiated extensions defines the meaning of such a nonzero
1323 value, the receiving endpoint MUST _Fail the WebSocket
1324 Connection_.
1326 Opcode: 4 bits
1328 Defines the interpretation of the payload data. If an unknown
1329 opcode is received, the receiving endpoint MUST _Fail the
1330 WebSocket Connection_. The following values are defined.
1332 * %x0 denotes a continuation frame
1334 * %x1 denotes a text frame
1336 * %x2 denotes a binary frame
1338 * %x3-7 are reserved for further non-control frames
1340 * %x8 denotes a connection close
1341 * %x9 denotes a ping
1343 * %xA denotes a pong
1345 * %xB-F are reserved for further control frames
1347 Mask: 1 bit
1349 Defines whether the payload data is masked. If set to 1, a
1350 masking key is present in masking-key, and this is used to unmask
1351 the payload data as per Section 5.3. All frames sent from client
1352 to server have this bit set to 1.
1354 Payload length: 7 bits, 7+16 bits, or 7+64 bits
1356 The length of the payload data, in bytes: if 0-125, that is the
1357 payload length. If 126, the following 2 bytes interpreted as a 16
1358 bit unsigned integer are the payload length. If 127, the
1359 following 8 bytes interpreted as a 64-bit unsigned integer (the
1360 most significant bit MUST be 0) are the payload length. Multibyte
1361 length quantities are expressed in network byte order. Note that
1362 in all case the minimal number of bytes MUST be used to encode the
1363 length, for example the length of a 124 byte long string can't be
1364 encoded as the sequence 126, 0, 124. The payload length is the
1365 length of the extension data + the length of the application data.
1366 The length of the extension data may be zero, in which case the
1367 payload length is the length of the application data.
1369 Masking-key: 0 or 4 bytes
1371 All frames sent from the client to the server are masked by a 32-
1372 bit value that is contained within the frame. This field is
1373 present if the mask bit is set to 1, and is absent if the mask bit
1374 is set to 0. See Section 5.3 for further information on client-
1375 to-server masking.
1377 Payload data: (x+y) bytes
1379 The payload data is defined as extension data concatenated with
1380 application data.
1382 Extension data: x bytes
1384 The extension data is 0 bytes unless an extension has been
1385 negotiated. Any extension MUST specify the length of the
1386 extension data, or how that length may be calculated, and how the
1387 extension use MUST be negotiated during the opening handshake. If
1388 present, the extension data is included in the total payload
1389 length.
1391 Application data: y bytes
1393 Arbitrary application data, taking up the remainder of the frame
1394 after any extension data. The length of the application data is
1395 equal to the payload length minus the length of the extension
1396 data.
1398 The base framing protocol is formally defined by the following ABNF
1399 [RFC5234]. It is important to note that the representation of this
1400 data is binary, not ASCII characters. As such, a field with a length
1401 of 1 bit that takes values %x0 / %x1 is represented as a single bit
1402 whose value is 0 or 1, not a full byte (octet) that stands for the
1403 characters "0" or "1" in the ASCII encoding. A field with a length
1404 of 4 bits with values between %x0-F again is represented by 4 bits,
1405 again NOT by an ASCII character or full byte (octet) with these
1406 values. [RFC5234] does not specify a character encoding - " Rules
1407 resolve into a string of terminal values, sometimes called
1408 characters. In ABNF, a character is merely a non-negative integer.
1409 In certain contexts, a specific mapping (encoding) of values into a
1410 character set (such as ASCII) will be specified." Here, the
1411 specified encoding is a binary encoding where each terminal value is
1412 encoded in the specified number of bits, which varies for each field.
1414 ws-frame = frame-fin ; 1 bit in length
1415 frame-rsv1 ; 1 bit in length
1416 frame-rsv2 ; 1 bit in length
1417 frame-rsv3 ; 1 bit in length
1418 frame-opcode ; 4 bits in length
1419 frame-masked ; 1 bit in length
1420 frame-payload-length ; 7 bits in length
1421 [ frame-masking-key ] ; 16 or 64 bits in length
1422 frame-payload-data ; n * 8 bits in length,
1423 ; where n >= 0
1425 frame-fin = %x0 ; more frames of this message follow
1426 / %x1 ; final frame of this message
1427 ; 1 bit in length
1429 frame-rsv1 = %x0 / %x1
1430 ; 1 bit in length, MUST be 0 unless negotiated
1431 ; otherwise
1433 frame-rsv2 = %x0 / %x1
1434 ; 1 bit in length, MUST be 0 unless negotiated
1435 ; otherwise
1437 frame-rsv3 = %x0 / %x1
1438 ; 1 bit in length, MUST be 0 unless negotiated
1439 ; otherwise
1441 frame-opcode = frame-opcode-non-control /
1442 frame-opcode-control
1444 frame-opcode-non-control= %x1 ; text frame
1445 / %x2 ; binary frame
1446 / %x3-7
1447 ; reserved for further non-control frames
1449 frame-opcode-control = %x8 ; connection close
1450 / %x9 ; ping
1451 / %xA ; pong
1452 / %xB-F ; reserved for further control frames
1453 ; 4 bits in length
1455 frame-masked = %x0
1456 ; frame is not masked, no frame-masking-key
1457 / %x1
1458 ; frame is masked, frame-masking-key present
1459 ; 1 bit in length
1461 frame-payload-length = %x00-7D
1462 / %x7E frame-payload-length-16
1463 / %x7F frame-payload-length-63
1464 ; 7 bits in length
1466 frame-payload-length-16 = %x0000-FFFF ; 16 bits in length
1468 frame-payload-length-63 = %x0000000000000000-7FFFFFFFFFFFFFFF
1469 ; 64 bits in length
1471 frame-masking-key = 4( %0x00-FF )
1472 ; present only if frame-masked is 1
1473 ; 32 bits in length
1475 frame-payload-data = (frame-masked-extension-data
1476 frame-masked-application-data)
1477 ; frame-masked 1
1478 / (frame-unmasked-extension-data
1479 frame-unmasked-application-data)
1480 ; frame-masked 0
1482 frame-masked-extension-data = *( %x00-FF )
1483 ; reserved for future extensibility
1484 ; n*8 bits in length , where n >= 0
1486 frame-masked-application-data = *( %x00-FF )
1487 ; n*8 bits in length, where n >= 0
1489 frame-unmasked-extension-data = *( %x00-FF )
1490 ; reserved for future extensibility
1491 ; n*8 bits in length, where n >= 0
1493 frame-unmasked-application-data = *( %x00-FF )
1494 ; n*8 bits in length, where n >= 0
1496 5.3. Client-to-Server Masking
1498 A masked frame MUST have the field frame-masked set to 1, as defined
1499 in Section 5.2.
1501 The masking key is contained completely within the frame, as defined
1502 in Section 5.2 as frame-masking-key. It is used to mask the payload
1503 data defined in the same section as frame-payload-data, which
1504 includes extension and application data.
1506 The masking key is a 32-bit value chosen at random by the client.
1507 When preparing a masked frame, the client MUST pick a fresh masking
1508 key from the set of allowed 32-bit values. The masking key needs to
1509 be unpredictable, thus the masking key MUST be derived from a strong
1510 source of entropy, and the masking key for a given frame MUST NOT
1511 make it simple for a server/proxy to predict the masking key for a
1512 subsequent frame. The unpredictability of the masking key is
1513 essential to prevent the author of malicious applications from
1514 selecting the bytes that appear on the wire. RFC 4086 [RFC4086]
1515 discusses what entails a suitable source of entropy for security-
1516 sensitive applications.
1518 The masking does not affect the length of the payload data. To
1519 convert masked data into unmasked data, or vice versa, the following
1520 algorithm is applied. The same algorithm applies regardless of the
1521 direction of the translation - e.g. the same steps are applied to
1522 mask the data as to unmask the data.
1524 Octet i of the transformed data ("transformed-octet-i") is the XOR of
1525 octet i of the original data ("original-octet-i") with octet at index
1526 i modulo 4 of the masking key ("masking-key-octet-j"):
1528 j = i MOD 4
1529 transformed-octet-i = original-octet-i XOR masking-key-octet-j
1531 The payload length, indicated in the framing as frame-payload-length,
1532 does NOT include the length of the masking key. It is the length of
1533 the payload data, e.g. the number of bytes following the masking key.
1535 5.4. Fragmentation
1537 The primary purpose of fragmentation is to allow sending a message
1538 that is of unknown size when the message is started without having to
1539 buffer that message. If messages couldn't be fragmented, then an
1540 endpoint would have to buffer the entire message so its length could
1541 be counted before first byte is sent. With fragmentation, a server
1542 or intermediary may choose a reasonable size buffer, and when the
1543 buffer is full write a fragment to the network.
1545 A secondary use-case for fragmentation is for multiplexing, where it
1546 is not desirable for a large message on one logical channel to
1547 monopolize the output channel, so the MUX needs to be free to split
1548 the message into smaller fragments to better share the output
1549 channel. (Note that the multiplexing extension is not described in
1550 this document.)
1552 Unless specified otherwise by an extension, frames have no semantic
1553 meaning. An intermediary might coalesce and/or split frames, if no
1554 extensions were negotiated by the client and the server, or if some
1555 extensions were negotiated, but the intermediary understood all the
1556 extensions negotiated and knows how to coalesce and/or split frames
1557 in presence of these extensions. One implication of this is that in
1558 absence of extensions senders and receivers must not depend on
1559 presence of specific frame boundaries.
1561 The following rules apply to fragmentation:
1563 o An unfragmented message consists of a single frame with the FIN
1564 bit set (Section 5.2) and an opcode other than 0.
1566 o A fragmented message consists of a single frame with the FIN bit
1567 clear and an opcode other than 0, followed by zero or more frames
1568 with the FIN bit clear and the opcode set to 0, and terminated by
1569 a single frame with the FIN bit set and an opcode of 0. A
1570 fragmented message is conceptually equivalent to a single larger
1571 message whose payload is equal to the concatenation of the
1572 payloads of the fragments in order, however in the presence of
1573 extensions this may not hold true as the extension defines the
1574 interpretation of the extension data present. For instance,
1575 extension data may only be present at the beginning of the first
1576 fragment and apply to subsequent fragments, or there may be
1577 extension data present in each of the fragments that applies only
1578 to that particular fragment. In absence of extension data, the
1579 following example demonstrates how fragmentation works.
1581 EXAMPLE: For a text message sent as three fragments, the first
1582 fragment would have an opcode of 0x1 and a FIN bit clear, the
1583 second fragment would have an opcode of 0x0 and a FIN bit clear,
1584 and the third fragment would have an opcode of 0x0 and a FIN bit
1585 that is set.
1587 o Control frames (see Section 5.5) MAY be injected in the middle of
1588 a fragmented message. Control frames themselves MUST NOT be
1589 fragmented.
1591 o Message fragments MUST be delivered to the recipient in the order
1592 sent by the sender.
1594 o The fragments of one message MUST NOT be interleaved between the
1595 fragments of another message unless an extension has been
1596 negotiated that can interpret the interleaving.
1598 o An endpoint MUST be capable of handling control frames in the
1599 middle of a fragmented message.
1601 o A sender MAY create fragments of any size for non-control
1602 messages.
1604 o Clients and servers MUST support receiving both fragmented and
1605 unfragmented messages.
1607 o As control frames cannot be fragmented, an intermediary MUST NOT
1608 attempt to change the fragmentation of a control frame.
1610 o An intermediary MUST NOT change the fragmentation of a message if
1611 any reserved bit values are used and the meaning of these values
1612 is not known to the intermediary.
1614 o An intermediary MUST NOT change the fragmentation of any message
1615 in the context of a connection where extensions have been
1616 negotiated and the intermediary is not aware of the semantics of
1617 the negotiated extensions. Similarly, an intermediary that didn't
1618 see the WebSocket handshake (and wasn't notified about its
1619 content) that resulted in a WebSocket connection MUST NOT change
1620 the fragmentation of any message of such connection.
1622 o As a consequence of these rules, all fragments of a message are of
1623 the same type, as set by the first fragment's opcode. Since
1624 Control frames cannot be fragmented, the type for all fragments in
1625 a message MUST be either text or binary, or one of the reserved
1626 opcodes.
1628 _Note: if control frames could not be interjected, the latency of a
1629 ping, for example, would be very long if behind a large message.
1630 Hence, the requirement of handling control frames in the middle of a
1631 fragmented message._
1633 _Implementation Note: in absence of any extension a receiver doesn't
1634 have to buffer the whole frame in order to process it. For example
1635 if a streaming API is used, a part of a frame can be delivered to the
1636 application. But note that that assumption might not hold true for
1637 all future WebSocket extensions._
1639 5.5. Control Frames
1641 Control frames are identified by opcodes where the most significant
1642 bit of the opcode is 1. Currently defined opcodes for control frames
1643 include 0x8 (Close), 0x9 (Ping), and 0xA (Pong). Opcodes 0xB-0xF are
1644 reserved for further control frames yet to be defined.
1646 Control frames are used to communicate state about the WebSocket.
1647 Control frames can be interjected in the middle of a fragmented
1648 message.
1650 All control frames MUST have a payload length of 125 bytes or less
1651 and MUST NOT be fragmented.
1653 5.5.1. Close
1655 The Close frame contains an opcode of 0x8.
1657 The Close frame MAY contain a body (the "application data" portion of
1658 the frame) that indicates a reason for closing, such as an endpoint
1659 shutting down, an endpoint having received a frame too large, or an
1660 endpoint having received a frame that does not conform to the format
1661 expected by the other endpoint. If there is a body, the first two
1662 bytes of the body MUST be a 2-byte unsigned integer (in network byte
1663 order) representing a status code with value /code/ defined in
1664 Section 7.4. Following the 2-byte integer the body MAY contain UTF-8
1665 encoded data with value /reason/, the interpretation of which is not
1666 defined by this specification. This data is not necessarily human
1667 readable, but may be useful for debugging or passing information
1668 relevant to the script that opened the connection. As the data is
1669 not guaranteed to be human readable, clients MUST NOT show it to end
1670 users.
1672 Close frames sent from client to server must be masked as per
1673 Section 5.3.
1675 The application MUST NOT send any more data frames after sending a
1676 close frame.
1678 If an endpoint receives a Close frame and that endpoint did not
1679 previously send a Close frame, the endpoint MUST send a Close frame
1680 in response. (When sending a Close frame in response the endpoint
1681 typically echos the status code it received.) It SHOULD do so as
1682 soon as practical. An endpoint MAY delay sending a close frame until
1683 its current message is sent (for instance, if the majority of a
1684 fragmented message is already sent, an endpoint MAY send the
1685 remaining fragments before sending a Close frame). However, there is
1686 no guarantee that the endpoint which has already sent a Close frame
1687 will continue to process data.
1689 After both sending and receiving a close message, an endpoint
1690 considers the WebSocket connection closed, and MUST close the
1691 underlying TCP connection. The server MUST close the underlying TCP
1692 connection immediately; the client SHOULD wait for the server to
1693 close the connection but MAY close the connection at any time after
1694 sending and receiving a close message, e.g. if it has not received a
1695 TCP close from the server in a reasonable time period.
1697 If a client and server both send a Close message at the same time,
1698 both endpoints will have sent and received a Close message and should
1699 consider the WebSocket connection closed and close the underlying TCP
1700 connection.
1702 5.5.2. Ping
1704 The Ping frame contains an opcode of 0x9.
1706 A Ping frame MAY include Application Data.
1708 Upon receipt of a Ping frame, an endpoint MUST send a Pong frame in
1709 response, unless it already received a Close frame. It SHOULD
1710 respond with Pong frame as soon as is practical. Pong frames are
1711 discussed in Section 5.5.3.
1713 An endpoint MAY send a Ping frame any time after the connection is
1714 established and before the connection is closed. NOTE: A ping frame
1715 may serve either as a keepalive, or to verify that the remote
1716 endpoint is still responsive.
1718 5.5.3. Pong
1720 The Pong frame contains an opcode of 0xA.
1722 Section 5.5.2 details requirements that apply to both Ping and Pong
1723 frames.
1725 A Pong frame sent in response to a Ping frame must have identical
1726 Application Data as found in the message body of the Ping frame being
1727 replied to.
1729 If an endpoint receives a Ping frame and has not yet sent Pong
1730 frame(s) in response to previous Ping frame(s), the endpoint MAY
1731 elect to send a Pong frame for only the most recently processed Ping
1732 frame.
1734 A Pong frame MAY be sent unsolicited. This serves as a
1735 unidirectional heartbeat. A response to an unsolicited pong is not
1736 expected.
1738 5.6. Data Frames
1740 Data frames (e.g. non-control frames) are identified by opcodes where
1741 the most significant bit of the opcode is 0. Currently defined
1742 opcodes for data frames include 0x1 (Text), 0x2 (Binary). Opcodes
1743 0x3-0x7 are reserved for further non-control frames yet to be
1744 defined.
1746 Data frames carry application-layer and/or extension-layer data. The
1747 opcode determines the interpretation of the data:
1749 Text
1751 The payload data is text data encoded as UTF-8. Note that a
1752 particular text frame might include a partial UTF-8 sequence,
1753 however the whole message MUST contain valid UTF-8. Invalid UTF-8
1754 in reassembled messages is handled as described in Section 8.1.
1756 Binary
1758 The payload data is arbitrary binary data whose interpretation is
1759 solely up to the application layer.
1761 5.7. Examples
1763 o A single-frame unmasked text message
1765 * 0x81 0x05 0x48 0x65 0x6c 0x6c 0x6f (contains "Hello")
1767 o A single-frame masked text message
1769 * 0x81 0x85 0x37 0xfa 0x21 0x3d 0x7f 0x9f 0x4d 0x51 0x58
1770 (contains "Hello")
1772 o A fragmented unmasked text message
1774 * 0x01 0x03 0x48 0x65 0x6c (contains "Hel")
1776 * 0x80 0x02 0x6c 0x6f (contains "lo")
1778 o Unmasked Ping request and masked Ping response
1780 * 0x89 0x05 0x48 0x65 0x6c 0x6c 0x6f (contains a body of "Hello",
1781 but the contents of the body are arbitrary)
1783 * 0x8a 0x85 0x37 0xfa 0x21 0x3d 0x7f 0x9f 0x4d 0x51 0x58
1784 (contains a body of "Hello", matching the body of the ping)
1786 o 256 bytes binary message in a single unmasked frame
1788 * 0x82 0x7E 0x0100 [256 bytes of binary data]
1790 o 64KiB binary message in a single unmasked frame
1792 * 0x82 0x7F 0x0000000000010000 [65536 bytes of binary data]
1794 5.8. Extensibility
1796 The protocol is designed to allow for extensions, which will add
1797 capabilities to the base protocol. The endpoints of a connection
1798 MUST negotiate the use of any extensions during the opening
1799 handshake. This specification provides opcodes 0x3 through 0x7 and
1800 0xB through 0xF, the extension data field, and the frame-rsv1, frame-
1801 rsv2, and frame-rsv3 bits of the frame header for use by extensions.
1802 The negotiation of extensions is discussed in further detail in
1803 Section 9.1. Below are some anticipated uses of extensions. This
1804 list is neither complete nor prescriptive.
1806 o Extension data may be placed in the payload data before the
1807 application data.
1809 o Reserved bits can be allocated for per-frame needs.
1811 o Reserved opcode values can be defined.
1813 o Reserved bits can be allocated to the opcode field if more opcode
1814 values are needed.
1816 o A reserved bit or an "extension" opcode can be defined which
1817 allocates additional bits out of the payload data to define larger
1818 opcodes or more per-frame bits.
1820 6. Sending and Receiving Data
1822 6.1. Sending Data
1824 To _Send a WebSocket Message_ comprising of /data/ over a WebSocket
1825 connection, an endpoint MUST perform the following steps.
1827 1. The endpoint MUST ensure the WebSocket connection is in the OPEN
1828 state (cf. Section 4.1 and Section 4.2.2.) If at any point the
1829 state of the WebSocket connection changes, the endpoint MUST
1830 abort the following steps.
1832 2. An endpoint MUST encapsulate the /data/ in a WebSocket frame as
1833 defined in Section 5.2. If the data to be sent is large, or if
1834 the data is not available in its entirety at the point the
1835 endpoint wishes to begin sending the data, the endpoint MAY
1836 alternately encapsulate the data in a series of frames as defined
1837 in Section 5.4.
1839 3. The opcode (frame-opcode) of the first frame containing the data
1840 MUST be set to the appropriate value from Section 5.2 for data
1841 that is to be interpreted by the recipient as text or binary
1842 data.
1844 4. The FIN bit (frame-fin) of the last frame containing the data
1845 MUST be set to 1 as defined in Section 5.2.
1847 5. If the data is being sent by the client, the frame(s) MUST be
1848 masked as defined in Section 5.3.
1850 6. If any extensions (Section 9) have been negotiated for the
1851 WebSocket connection, additional considerations may apply as per
1852 the definition of those extensions.
1854 7. The frame(s) that have been formed MUST be transmitted over the
1855 underlying network connection.
1857 6.2. Receiving Data
1859 To receive WebSocket data, an endpoint listens on the underlying
1860 network connection. Incoming data MUST be parsed as WebSocket frames
1861 as defined in Section 5.2. If a control frame (Section 5.5) is
1862 received, the frame MUST be handled as defined by Section 5.5. Upon
1863 receiving a data frame (Section 5.6), the endpoint MUST note the
1864 /type/ of the data as defined by the Opcode (frame-opcode) from
1865 Section 5.2. The _Application Data_ from this frame is defined as
1866 the /data/ of the message. If the frame comprises an unfragmented
1867 message (Section 5.4), it is said that _A WebSocket Message Has Been
1868 Received_ with type /type/ and data /data/. If the frame is part of
1869 a fragmented message, the _Application Data_ of the subsequent data
1870 frames is concatenated to form the /data/. When the last fragment is
1871 received as indicated by the FIN bit (frame-fin), it is said that _A
1872 WebSocket Message Has Been Received_ with data /data/ (comprised of
1873 the concatenation of the _Application Data_ of the fragments) and
1874 type /type/ (noted from the first frame of the fragmented message).
1875 Subsequent data frames MUST be interpreted as belonging to a new
1876 WebSocket Message.
1878 Extensions (Section 9) MAY change the semantics of how data is read,
1879 specifically including what comprises a message boundary.
1880 Extensions, in addition to adding "Extension data" before the
1881 "Application data" in a payload, MAY also modify the "Application
1882 data" (such as by compressing it).
1884 A server MUST remove masking for data frames received from a client
1885 as described in Section 5.3.
1887 7. Closing the connection
1889 7.1. Definitions
1891 7.1.1. Close the WebSocket Connection
1893 To _Close the WebSocket Connection_, an endpoint closes the
1894 underlying TCP connection. An endpoint SHOULD use a method that
1895 cleanly closes the TCP connection, as well as the TLS session, if
1896 applicable, discarding any trailing bytes that may be received. An
1897 endpoint MAY close the connection via any means available when
1898 necessary, such as when under attack.
1900 The underlying TCP connection, in most normal cases, SHOULD be closed
1901 first by the server, so that it holds the TIME_WAIT state and not the
1902 client (as this would prevent it from re-opening the connection for 2
1903 MSL, while there is no corresponding server impact as a TIME_WAIT
1904 connection is immediately reopened upon a new SYN with a higher seq
1905 number). In abnormal cases (such as not having received a TCP Close
1906 from the server after a reasonable amount of time) a client MAY
1907 initiate the TCP Close. As such, when a server is instructed to
1908 _Close the WebSocket Connection_ it SHOULD initiate a TCP Close
1909 immediately, and when a client is instructed to do the same, it
1910 SHOULD wait for a TCP Close from the server.
1912 As an example of how to obtain a clean closure in C using Berkeley
1913 sockets, one would call shutdown() with SHUT_WR on the socket, call
1914 recv() until obtaining a return value of 0 indicating that the peer
1915 has also performed an orderly shutdown, and finally calling close()
1916 on the socket.
1918 7.1.2. Start the WebSocket Closing Handshake
1920 To _Start the WebSocket Closing Handshake_ with a status code
1921 (Section 7.4) /code/ and an optional close reason (Section 7.1.6)
1922 /reason/, an endpoint MUST send a Close control frame, as described
1923 in Section 5.5.1 whose status code is set to /code/ and whose close
1924 reason is set to /reason/. Once an endpoint has both sent and
1925 received a Close control frame, that endpoint SHOULD _Close the
1926 WebSocket Connection_ as defined in Section 7.1.1.
1928 7.1.3. The WebSocket Closing Handshake is Started
1930 Upon either sending or receiving a Close control frame, it is said
1931 that _The WebSocket Closing Handshake is Started_ and that the
1932 WebSocket connection is in the CLOSING state.
1934 7.1.4. The WebSocket Connection is Closed
1936 When the underlying TCP connection is closed, it is said that _The
1937 WebSocket Connection is Closed_ and that the WebSocket connection is
1938 in the CLOSED state. If the tcp connection was closed after the
1939 WebSocket closing handshake was completed, the WebSocket connection
1940 is said to have been closed _cleanly_.
1942 If the WebSocket connection could not be established, it is also said
1943 that _The WebSocket Connection is Closed_, but not cleanly.
1945 7.1.5. The WebSocket Connection Close Code
1947 As defined in Section 5.5.1 and Section 7.4, a Close control frame
1948 may contain a status code indicating a reason for closure. A closing
1949 of the WebSocket connection may be initiated by either endpoint,
1950 potentially simultaneously. _The WebSocket Connection Close Code_ is
1951 defined as the status code (Section 7.4) contained in the first Close
1952 control frame received by the application implementing this protocol.
1953 If this Close control frame contains no status code, _The WebSocket
1954 Connection Close Code_ is considered to be 1005. If _The WebSocket
1955 Connection is Closed_ and no Close control frame was received by the
1956 endpoint (such as could occur if the underlying transport connection
1957 is lost), _The WebSocket Connection Close Code_ is considered to be
1958 1006.
1960 NOTE: Two endpoints may not agree on the value of _The WebSocket
1961 Connection Close Code_. As an example, if the remote endpoint sent a
1962 Close frame but the local application has not yet read the data
1963 containing the Close frame from its socket's receive buffer, and the
1964 local application independently decided to close the connection and
1965 send a Close frame, both endpoints will have sent and received a
1966 Close frame, and will not send further Close frames. Each endpoint
1967 will see the Connection Close Code sent by the other end as the
1968 _WebSocket Connection Close Code_. As such, it is possible that the
1969 two endpoints may not agree on the value of _The WebSocket Connection
1970 Close Code_ in the case that both endpoints _Start the WebSocket
1971 Closing Handshake_ independently and at roughly the same time.
1973 7.1.6. The WebSocket Connection Close Reason
1975 As defined in Section 5.5.1 and Section 7.4, a Close control frame
1976 may contain a status code indicating a reason for closure, followed
1977 by UTF-8 encoded data, the interpretation of said data being left to
1978 the endpoints and not defined by this protocol. A closing of the
1979 WebSocket connection may be initiated by either endpoint, potentially
1980 simultaneously. _The WebSocket Connection Close Reason_ is defined as
1981 the UTF-8 encoded data following the status code (Section 7.4)
1982 contained in the first Close control frame received by the
1983 application implementing this protocol. If there is no such data in
1984 the Close control frame, _The WebSocket Connection Close Reason_ is
1985 the empty string.
1987 NOTE: Following the same logic as noted in Section 7.1.5, two
1988 endpoints may not agree on _The WebSocket Connection Close Reason_.
1990 7.1.7. Fail the WebSocket Connection
1992 Certain algorithms and specifications require an endpoint to _Fail
1993 the WebSocket Connection_. To do so, the client MUST _Close the
1994 WebSocket Connection_, and MAY report the problem to the user (which
1995 would be especially useful for developers) in an appropriate manner.
1996 Similarly, to do so, the server MUST _Close the WebSocket
1997 Connection_, and SHOULD log the problem.
1999 If _The WebSocket Connection is Established_ prior to the point where
2000 the endpoint is required to _Fail the WebSocket Connection_, the
2001 endpoint SHOULD send a Close frame with an appropriate status code
2002 Section 7.4 before proceeding to _Close the WebSocket Connection_.
2003 An endpoint MAY omit sending a Close frame if it believes the other
2004 side is unlikely to be able to receive and process the close frame,
2005 due to the nature of the error that led to the WebSocket connection
2006 being failed in the first place. An endpoint MUST NOT continue to
2007 attempt to process data (including a responding Close frame) from the
2008 remote endpoint after being instructed to _Fail the WebSocket
2009 Connection_.
2011 Except as indicated above or as specified by the application layer
2012 (e.g. a script using the WebSocket API), clients SHOULD NOT close the
2013 connection.
2015 7.2. Abnormal Closures
2017 7.2.1. Client-Initiated Closure
2019 Certain algorithms, namely during the opening handshake, require the
2020 client to _Fail the WebSocket Connection_. To do so, the client MUST
2021 _Fail the WebSocket Connection_ as defined in Section 7.1.7.
2023 If at any point the underlying transport layer connection is
2024 unexpectedly lost, the client MUST _Fail the WebSocket Connection_.
2026 Except as indicated above or as specified by the application layer
2027 (e.g. a script using the WebSocket API), clients SHOULD NOT close the
2028 connection.
2030 7.2.2. Server-Initiated Closure
2032 Certain algorithms require or recommend that the server _Abort the
2033 WebSocket Connection_ during the opening handshake. To do so, the
2034 server MUST simply _Close the WebSocket Connection_ (Section 7.1.1).
2036 7.2.3. Recovering From Abnormal Closure
2038 Abnormal closures may be caused by any number of reasons. Such
2039 closures could be the result of a transient error, in which case
2040 reconnecting may lead to a good connection and a resumption of normal
2041 operations. Such closures may also be the result of a nontransient
2042 problem, in which case if each deployed client experiences an
2043 abnormal closure and immediately and persistently tries to reconnect,
2044 the server may experience what amounts to a denial of service attack
2045 by a large number of clients trying to reconnect. The end result of
2046 such a scenario could be that the service is unable to recover, or
2047 recovery is made much more difficult, in any sort of timely manner.
2049 To prevent this, clients SHOULD use some form of backoff when trying
2050 to reconnect after abnormal closures as described in this section.
2052 The first reconnect attempt SHOULD be delayed by a random amount of
2053 time. The parameters by which this random delay is chosen are left
2054 to the client to decide; a value chosen randomly between 0 and 5
2055 seconds is a reasonable initial delay though clients MAY choose a
2056 different interval from which to select a delay length based on
2057 implementation experience and particular application.
2059 Should the first reconnect attempt fail, subsequent reconnect
2060 attempts SHOULD be delayed by increasingly longer amounts of time,
2061 using a method such as truncated binary exponential backoff.
2063 7.3. Normal Closure of Connections
2065 Servers MAY close the WebSocket connection whenever desired. Clients
2066 SHOULD NOT close the WebSocket connection arbitrarily. In either
2067 case, an endpoint initiates a closure by following the procedures to
2068 _Start the WebSocket Closing Handshake_ (Section 7.1.2).
2070 7.4. Status Codes
2072 When closing an established connection (e.g. when sending a Close
2073 frame, after the opening handshake has completed), an endpoint MAY
2074 indicate a reason for closure. The interpretation of this reason by
2075 an endpoint, and the action an endpoint should take given this
2076 reason, are left undefined by this specification. This specification
2077 defines a set of pre-defined status codes, and specifies which ranges
2078 may be used by extensions, frameworks, and end applications. The
2079 status code and any associated textual message are optional
2080 components of a Close frame.
2082 7.4.1. Defined Status Codes
2084 Endpoints MAY use the following pre-defined status codes when sending
2085 a Close frame.
2087 1000
2089 1000 indicates a normal closure, meaning whatever purpose the
2090 connection was established for has been fulfilled.
2092 1001
2094 1001 indicates that an endpoint is "going away", such as a server
2095 going down, or a browser having navigated away from a page.
2097 1002
2099 1002 indicates that an endpoint is terminating the connection due
2100 to a protocol error.
2102 1003
2104 1003 indicates that an endpoint is terminating the connection
2105 because it has received a type of data it cannot accept (e.g. an
2106 endpoint that understands only text data MAY send this if it
2107 receives a binary message).
2109 1004
2111 Reserved. The specific meaning might be defined in the future.
2113 1005
2115 1005 is a reserved value and MUST NOT be set as a status code in a
2116 Close control frame by an endpoint. It is designated for use in
2117 applications expecting a status code to indicate that no status
2118 code was actually present.
2120 1006
2122 1006 is a reserved value and MUST NOT be set as a status code in a
2123 Close control frame by an endpoint. It is designated for use in
2124 applications expecting a status code to indicate that the
2125 connection was closed abnormally, e.g. without sending or
2126 receiving a Close control frame.
2128 1007
2130 1007 indicates that an endpoint is terminating the connection
2131 because it has received data within a message that was not
2132 consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
2133 data within a text message).
2135 1008
2137 1008 indicates that an endpoint is terminating the connection
2138 because it has received a message that violates its policy. This
2139 is a generic status code that can be returned when there is no
2140 other more suitable status code (e.g. 1003 or 1009), or if there
2141 is a need to hide specific details about the policy.
2143 1009
2145 1009 indicates that an endpoint is terminating the connection
2146 because it has received a message which is too big for it to
2147 process.
2149 1010
2151 1010 indicates that an endpoint (client) is terminating the
2152 connection because it has expected the server to negotiate one or
2153 more extension, but the server didn't return them in the response
2154 message of the WebSocket handshake. The list of extensions which
2155 are needed SHOULD appear in the /reason/ part of the Close frame.
2156 Note that this status code is not used by the server, because it
2157 can fail the WebSocket handshake instead.
2159 7.4.2. Reserved Status Code Ranges
2161 0-999
2163 Status codes in the range 0-999 are not used.
2165 1000-2999
2167 Status codes in the range 1000-2999 are reserved for definition by
2168 this protocol, its future revisions, and extensions specified in a
2169 permanent and readily available public specification.
2171 3000-3999
2173 Status codes in the range 3000-3999 are reserved for use by
2174 libraries, frameworks and application. These status codes are
2175 registered directly with IANA. The interpretation of these codes
2176 is undefined by this protocol.
2178 4000-4999
2180 Status codes in the range 4000-4999 are reserved for private use
2181 and thus can't be registered. Such codes can be used by prior
2182 agreements between WebSocket applications. The interpretation of
2183 these codes is undefined by this protocol.
2185 8. Error Handling
2187 8.1. Handling Errors in UTF-8 Encoded Data
2189 When an endpoint is to interpret a byte stream as UTF-8 but finds
2190 that the byte stream is not in fact a valid UTF-8 stream, that
2191 endpoint MUST _Fail the WebSocket Connection_. This rule applies
2192 both during the opening handshake and during subsequent data
2193 exchange.
2195 9. Extensions
2197 WebSocket clients MAY request extensions to this specification, and
2198 WebSocket servers MAY accept some or all extensions requested by the
2199 client. A server MUST NOT respond with any extension not requested
2200 by the client. If extension parameters are included in negotiations
2201 between the client and the server, those parameters MUST be chosen in
2202 accordance with the specification of the extension to which the
2203 parameters apply.
2205 9.1. Negotiating Extensions
2207 A client requests extensions by including a "Sec-WebSocket-
2208 Extensions" header field, which follows the normal rules for HTTP
2209 header fields (see [RFC2616] section 4.2) and the value of the header
2210 field is defined by the following ABNF [RFC2616]. Note that this
2211 section is using ABNF syntax/rules from [RFC2616], including "implied
2212 *LWS rule". If a value is received by either the client or the
2213 server during negotiation that does not conform to the ABNF below,
2214 the recipient of such malformed data MUST immediately _Fail the
2215 WebSocket Connection_.
2217 Sec-WebSocket-Extensions = extension-list
2218 extension-list = 1#extension
2219 extension = extension-token *( ";" extension-param )
2220 extension-token = registered-token
2221 registered-token = token
2222 extension-param = token [ "=" (token | quoted-string) ]
2223 ;When using the quoted-string syntax variant, the value
2224 ;after quoted-string unescaping MUST conform to the
2225 ;'token' ABNF.
2227 Note that like other HTTP header fields, this header field MAY be
2228 split or combined across multiple lines. Ergo, the following are
2229 equivalent:
2231 Sec-WebSocket-Extensions: foo
2232 Sec-WebSocket-Extensions: bar; baz=2
2234 is exactly equivalent to
2236 Sec-WebSocket-Extensions: foo, bar; baz=2
2238 Any extension-token used MUST be a registered token (see
2239 Section 11.4). The parameters supplied with any given extension MUST
2240 be defined for that extension. Note that the client is only offering
2241 to use any advertised extensions, and MUST NOT use them unless the
2242 server indicates that it wishes to use the extension.
2244 Note that the order of extensions is significant. Any interactions
2245 between multiple extensions MAY be defined in the documents defining
2246 the extensions. In the absence of such definition, the
2247 interpretation is that the header fields listed by the client in its
2248 request represent a preference of the header fields it wishes to use,
2249 with the first options listed being most preferable. The extensions
2250 listed by the server in response represent the extensions actually in
2251 use for the connection. Should the extensions modify the data and/or
2252 framing, the order of operations on the data should be assumed to be
2253 the same as the order in which the extensions are listed in the
2254 server's response in the opening handshake.
2256 For example, if there are two extensions "foo" and "bar", if the
2257 header field |Sec-WebSocket-Extensions| sent by the server has the
2258 value "foo, bar" then operations on the data will be made as
2259 bar(foo(data)), be those changes to the data itself (such as
2260 compression) or changes to the framing that may "stack".
2262 Non-normative examples of acceptable extension header fields (note
2263 that long lines are folded for readability):
2265 Sec-WebSocket-Extensions: deflate-stream
2266 Sec-WebSocket-Extensions: mux; max-channels=4; flow-control,
2267 deflate-stream
2268 Sec-WebSocket-Extensions: private-extension
2270 A server accepts one or more extensions by including a |Sec-
2271 WebSocket-Extensions| header field containing one or more extensions
2272 which were requested by the client. The interpretation of any
2273 extension parameters, and what constitutes a valid response by a
2274 server to a requested set of parameters by a client, will be defined
2275 by each such extension.
2277 9.2. Known Extensions
2279 Extensions provide a mechanism for implementations to opt-in to
2280 additional protocol features. This document doesn't define any
2281 extension but implementations MAY use extensions defined separately.
2283 10. Security Considerations
2285 This section describes some security considerations applicable to the
2286 WebSocket protocol. Specific security considerations are described
2287 in subsections of this section.
2289 10.1. Non-Browser Clients
2291 Many threats anticipated by the WebSocket protocol protect from
2292 malicious JavaScript running inside a trusted application such as a
2293 web browser, for example checking of the "Origin" header field (see
2294 below). See Section 1.6 for additional details. Such assumptions
2295 don't hold true in the case of a more capable client.
2297 While this protocol is intended to be used by scripts in Web pages,
2298 it can also be used directly by hosts. Such hosts are acting on
2299 their own behalf, and can therefore send fake "Origin" header fields,
2300 misleading the server. Servers should therefore be careful about
2301 assuming that they are talking directly to scripts from known
2302 origins, and must consider that they might be accessed in unexpected
2303 ways. In particular, a server should not trust that any input is
2304 valid.
2306 EXAMPLE: For example, if the server uses input as part of SQL
2307 queries, all input text should be escaped before being passed to the
2308 SQL server, lest the server be susceptible to SQL injection.
2310 10.2. Origin Considerations
2312 Servers that are not intended to process input from any Web page but
2313 only for certain sites SHOULD verify the "Origin" field is an origin
2314 they expect. If the origin indicated is unacceptable to the server,
2315 then it SHOULD respond to the WebSocket handshake with a reply
2316 containing HTTP 403 Forbidden status code.
2318 The "Origin" header field protects from the attack cases when the
2319 untrusted party is typically the author of a JavaScript application
2320 that is executing in the context of the trusted client. The client
2321 itself can contact the server and via the mechanism of the "Origin"
2322 header field, determine whether to extend those communication
2323 privileges to the JavaScript application. The intent is not to
2324 prevent non-browsers from establishing connections, but rather to
2325 ensure that trusted browsers under the control of potentially
2326 malicious JavaScript cannot fake a WebSocket handshake.
2328 10.3. Attacks On Infrastructure (Masking)
2330 In addition to endpoints being the target of attacks via WebSockets,
2331 other parts of web infrastructure, such as proxies, may be the
2332 subject of an attack.
2334 As this protocol was being developed, an experiment was conducted to
2335 demonstrate a class of attacks on proxies that led to the poisoning
2336 of caching proxies deployed in the wild [TALKING]. The general form
2337 of the attack was to establish a connection to a server under the
2338 "attacker's" control, perform an UPGRADE on the HTTP connection
2339 similar to what the WebSocket protocol does to establish a
2340 connection, and to subsequently send data over that UPGRADEd
2341 connection that looked like a GET request for a specific known
2342 resource (which in an attack would likely be something like a widely
2343 deployed script for tracking hits, or a resource on an ad-serving
2344 network). The remote server would respond with something that looked
2345 like a response to the fake GET request, and this response would be
2346 cached by a nonzero percentage of deployed intermediaries, thus
2347 poisioning the cache. The net effect of this attack would be that if
2348 a user could be convinced to visit a website the attacker controlled,
2349 the attacker could potentially poison the cache for that user and
2350 other users behind the same cache and run malicious script on other
2351 origins, compromising the web security model.
2353 To avoid such attacks on deployed intermediaries, it is not
2354 sufficient to prefix application supplied data with framing that is
2355 not compliant HTTP, as it is not possible to exhaustively discover
2356 and test that each nonconformant intermediary does not skip such non
2357 HTTP framing and act incorrectly on the frame payload. Thus the
2358 defence adopted is to mask all data from the client to the server, so
2359 that the remote script (attacker) does not have control over how the
2360 data being sent appears on the wire, and thus cannot construct a
2361 message that could be misinterpreted by an intermediary as an HTTP
2362 request.
2364 Clients MUST choose a new masking key for each frame, using an
2365 algorithm that cannot be predicted by end applications that provide
2366 data. For example, each masking could be drawn from a
2367 cryptographically strong random number generator. If the same key is
2368 used, or a decipherable pattern exists for how the next key is
2369 chosen, the attacker can send a message that, when masked, could
2370 appear to be an HTTP request (by taking the message the attacker
2371 wishes to see on the wire, and masking it with the next masking key
2372 to be used, when the client applies the masking key it will
2373 effectively unmask the data.)
2375 It is also necessary that once the transmission of a frame from a
2376 client has begun, the payload (application supplied data) of that
2377 frame must not be capable of being modified by the application.
2378 Otherwise, an attacker could send a long frame where the initial data
2379 was a known value (such as all zeros), compute the masking key being
2380 used upon receipt of the first part of the data, and then modify the
2381 data that is yet to be sent in the frame to appear as an HTTP request
2382 when masked. (This is essentially the same problem described in the
2383 previous paragraph with using a known or predictable masking key.)
2384 If additional data is to be sent or data to be sent is somehow
2385 changed, that new or changed data must be sent in a new frame and
2386 thus with a new masking key. In short, once transmission of a frame
2387 begins, the contents must not be modifiable by the remote script
2388 (application).
2390 The threat model being protected against is one in which the client
2391 sends data that appears to be a HTTP request. As such, the channel
2392 that needs to be masked is the data from the client to the server.
2393 The data from the server to the client can be made to look like a
2394 response, but to accomplish this request the client must also be able
2395 to forge a request. As such, it was not deemed necessary to mask
2396 data in both directions (the data from the server to the client is
2397 not masked).
2399 Despite the protection provided by masking, non-compliant HTTP
2400 proxies will still be vulnerable to poisoning attacks of this type by
2401 clients and servers that do not apply masking.
2403 10.4. Implementation-Specific Limits
2405 Implementations which have implementation- and/or platform-specific
2406 limitations regarding the frame size or total message size after
2407 reassembly from multiple frames MUST protect themselves against
2408 exceeding those limits. (For example, a malicious endpoint can try
2409 to exhaust its peer's memory or mount a denial of service attack by
2410 sending either a single big frame (e.g. of size 2**60), or by sending
2411 a long stream of small frames which are a part of a fragmented
2412 message.) Such an implementation SHOULD impose limit on frame sizes
2413 and the total message size after reassembly from multiple frames.
2415 10.5. WebSocket client authentication
2417 This protocol doesn't prescribe any particular way that servers can
2418 authenticate clients during the WebSocket handshake. The WebSocket
2419 server can use any client authentication mechanism available to a
2420 generic HTTP server, such as Cookies, HTTP Authentication, or TLS
2421 authentication.
2423 10.6. Connection confidentiality and integrity
2425 Communications confidentiality and integrity is provided by running
2426 the WebSocket protocol over TLS (wss URIs). WebSocket
2427 implementations MUST support TLS, and SHOULD employ it when
2428 communicating with their peers.
2430 For connections using TLS, the amount of benefit provided by TLS
2431 depends greatly on the strength of the algorithms negotiated during
2432 the TLS handshake. For example some TLS cipher mechanisms don't
2433 provide connection confidentiality. To achieve reasonable levels of
2434 protections, clients should use only Strong TLS algorithms. "Web
2435 Security Context: User Interface Guidelines"
2436 [W3C.REC-wsc-ui-20100812] discusses what constitutes Strong TLS
2437 algorithms. [RFC5246] provides additional guidance in Appendix A.5
2438 and Appendix D.3.
2440 10.7. Handling of invalid data
2442 Incoming data MUST always be validated by both clients and servers.
2443 If at any time an endpoint is faced with data that it does not
2444 understand, or that violates some criteria by which the endpoint
2445 determines safety of input, or when the endpoint sees an opening
2446 handshake that does not correspond to the values it is expecting
2447 (e.g. incorrect path or origin in the client request), the endpoint
2448 MAY drop the TCP connection. If the invalid data received after a
2449 successful WebSocket handshake, the endpoint SHOULD send a Close
2450 frame with an appropriate status code Section 7.4 before proceeding
2451 to _Close the WebSocket Connection_. Use of a Close frame with an
2452 appropriate status code can help in diagnosing the problem. If the
2453 invalid data is sent during the WebSocket handshake the server SHOULD
2454 return an appropriate HTTP [RFC2616] status code.
2456 A common class of security problems arise when sending text data
2457 using using the wrong encoding. This protocol specifies that
2458 messages with a Text data type (as opposed to Binary or other types)
2459 contain UTF-8 encoded data. Although the length is still indicated
2460 and applications implementing this protocol should use the length to
2461 determine where the frame actually ends, sending data in an improper
2462 encoding may still break assumptions applications built on top of
2463 this protocol may make, leading from anything to misinterpretation of
2464 data to loss of data to potential security bugs.
2466 10.8. Use of SHA-1 by the WebSocket handshake
2468 The WebSocket handshake described in this document doesn't depend on
2469 any security properties of SHA-1, such as collision resistance or
2470 resistance to the second pre-image attack (as described in
2471 [RFC4270]).
2473 11. IANA Considerations
2475 11.1. Registration of new URI Schemes
2477 11.1.1. Registration of "ws" Scheme
2479 A |ws| URI identifies a WebSocket server and resource name.
2481 URI scheme name.
2482 ws
2484 Status.
2485 Permanent.
2487 URI scheme syntax.
2488 In ABNF [RFC5234] terms using the terminals from the URI
2489 specifications: [RFC5234] [RFC3986]
2491 "ws:" "//" authority path-abempty [ "?" query ]
2493 The and [RFC3986] components form the
2494 resource name sent to the server to identify the kind of service
2495 desired. Other components have the meanings described in RFC3986.
2497 URI scheme semantics.
2498 The only operation for this scheme is to open a connection using
2499 the WebSocket protocol.
2501 Encoding considerations.
2502 Characters in the host component that are excluded by the syntax
2503 defined above MUST be converted from Unicode to ASCII as specified
2504 in [RFC3987] or its replacement. For the purposes of scheme-based
2505 normalization IDN forms of the host component and their
2506 conversions to punycode are considered equivalent (see Section
2507 5.3.3 of [RFC3987]).
2509 Characters in other components that are excluded by the syntax
2510 defined above MUST be converted from Unicode to ASCII by first
2511 encoding the characters as UTF-8 and then replacing the
2512 corresponding bytes using their percent-encoded form as defined in
2513 the URI and IRI specifications. [RFC3986] [RFC3987]
2515 Applications/protocols that use this URI scheme name.
2516 WebSocket protocol.
2518 Interoperability considerations.
2519 Use of WebSocket requires use of HTTP version 1.1 or higher.
2521 Security considerations.
2522 See "Security considerations" section above.
2524 Contact.
2525 HYBI WG
2527 Author/Change controller.
2528 IETF
2530 References.
2531 RFC XXXX
2533 11.1.2. Registration of "wss" Scheme
2535 A |wss| URI identifies a WebSocket server and resource name, and
2536 indicates that traffic over that connection is to be protected via
2537 TLS (including standard benefits of TLS such as data confidentiality
2538 and integrity, and endpoint authentication).
2540 URI scheme name.
2541 wss
2543 Status.
2544 Permanent.
2546 URI scheme syntax.
2547 In ABNF [RFC5234] terms using the terminals from the URI
2548 specifications: [RFC5234] [RFC3986]
2550 "wss:" "//" authority path-abempty [ "?" query ]
2552 The and components form the resource name
2553 sent to the server to identify the kind of service desired. Other
2554 components have the meanings described in RFC3986.
2556 URI scheme semantics.
2557 The only operation for this scheme is to open a connection using
2558 the WebSocket protocol, encrypted using TLS.
2560 Encoding considerations.
2561 Characters in the host component that are excluded by the syntax
2562 defined above MUST be converted from Unicode to ASCII as specified
2563 in [RFC3987] or its replacement. For the purposes of scheme-based
2564 normalization IDN forms of the host component and their
2565 conversions to punycode are considered equivalent (see Section
2566 5.3.3 of [RFC3987]).
2568 Characters in other components that are excluded by the syntax
2569 defined above MUST be converted from Unicode to ASCII by first
2570 encoding the characters as UTF-8 and then replacing the
2571 corresponding bytes using their percent-encoded form as defined in
2572 the URI and IRI specification. [RFC3986] [RFC3987]
2574 Applications/protocols that use this URI scheme name.
2575 WebSocket protocol over TLS.
2577 Interoperability considerations.
2578 Use of WebSocket requires use of HTTP version 1.1 or higher.
2580 Security considerations.
2581 See "Security considerations" section above.
2583 Contact.
2584 HYBI WG
2586 Author/Change controller.
2587 IETF
2589 References.
2590 RFC XXXX
2592 11.2. Registration of the "WebSocket" HTTP Upgrade Keyword
2594 This section defines a keyword for registration in the "HTTP Upgrade
2595 Tokens" registry as per RFC 2817 [RFC2817].
2597 Name of token.
2598 WebSocket
2600 Author/Change controller.
2601 IETF
2603 Contact.
2604 HYBI
2606 References.
2607 RFC XXXX
2609 11.3. Registration of new HTTP Header Fields
2610 11.3.1. Sec-WebSocket-Key
2612 This section describes a header field for registration in the
2613 Permanent Message Header Field Registry. [RFC3864]
2615 Header field name
2616 Sec-WebSocket-Key
2618 Applicable protocol
2619 http
2621 Status
2622 standard
2624 Author/Change controller
2625 IETF
2627 Specification document(s)
2628 RFC XXXX
2630 Related information
2631 This header field is only used for WebSocket opening handshake.
2633 The |Sec-WebSocket-Key| header field is used in the WebSocket opening
2634 handshake. It is sent from the client to the server to provide part
2635 of the information used by the server to prove that it received a
2636 valid WebSocket opening handshake. This helps ensure that the server
2637 does not accept connections from non-WebSocket clients (e.g. HTTP
2638 clients) that are being abused to send data to unsuspecting WebSocket
2639 servers.
2641 The |Sec-WebSocket-Key| header field MUST NOT appear more than once
2642 in an HTTP request.
2644 11.3.2. Sec-WebSocket-Extensions
2646 This section describes a header field for registration in the
2647 Permanent Message Header Field Registry. [RFC3864]
2649 Header field name
2650 Sec-WebSocket-Extensions
2652 Applicable protocol
2653 http
2655 Status
2656 standard
2658 Author/Change controller
2659 IETF
2661 Specification document(s)
2662 RFC XXXX
2664 Related information
2665 This header field is only used for WebSocket opening handshake.
2667 The |Sec-WebSocket-Extensions| header field is used in the WebSocket
2668 opening handshake. It is initially sent from the client to the
2669 server, and then subsequently sent from the server to the client, to
2670 agree on a set of protocol-level extensions to use for the duration
2671 of the connection.
2673 The |Sec-WebSocket-Extensions| header field MAY appear multiple times
2674 in an HTTP request (which is logically the same as a single |Sec-
2675 WebSocket-Extensions| header field that contains all values. However
2676 the |Sec-WebSocket-Extensions| header field MUST NOT appear more than
2677 once in an HTTP response.
2679 11.3.3. Sec-WebSocket-Accept
2681 This section describes a header field for registration in the
2682 Permanent Message Header Field Registry. [RFC3864]
2684 Header field name
2685 Sec-WebSocket-Accept
2687 Applicable protocol
2688 http
2690 Status
2691 standard
2693 Author/Change controller
2694 IETF
2696 Specification document(s)
2697 RFC XXXX
2699 Related information
2700 This header field is only used for WebSocket opening handshake.
2702 The |Sec-WebSocket-Accept| header field is used in the WebSocket
2703 opening handshake. It is sent from the server to the client to
2704 confirm that the server is willing to initiate the WebSocket
2705 connection.
2707 The |Sec-WebSocket-Accept| header MUST NOT appear more than once in
2708 an HTTP response.
2710 11.3.4. Sec-WebSocket-Protocol
2712 This section describes a header field for registration in the
2713 Permanent Message Header Field Registry. [RFC3864]
2715 Header field name
2716 Sec-WebSocket-Protocol
2718 Applicable protocol
2719 http
2721 Status
2722 standard
2724 Author/Change controller
2725 IETF
2727 Specification document(s)
2728 RFC XXXX
2730 Related information
2731 This header field is only used for WebSocket opening handshake.
2733 The |Sec-WebSocket-Protocol| header field is used in the WebSocket
2734 opening handshake. It is sent from the client to the server and back
2735 from the server to the client to confirm the subprotocol of the
2736 connection. This enables scripts to both select a subprotocol and be
2737 sure that the server agreed to serve that subprotocol.
2739 The |Sec-WebSocket-Protocol| header field MAY appear multiple times
2740 in an HTTP request (which is logically the same as a single |Sec-
2741 WebSocket-Protocol| header field that contains all values. However
2742 the |Sec-WebSocket-Protocol| header field MUST NOT appear more than
2743 once in an HTTP response.
2745 11.3.5. Sec-WebSocket-Version
2747 This section describes a header field for registration in the
2748 Permanent Message Header Field Registry [RFC3864].
2750 Header field name
2751 Sec-WebSocket-Version
2753 Applicable protocol
2754 http
2756 Status
2757 standard
2759 Author/Change controller
2760 IETF
2762 Specification document(s)
2763 RFC XXXX
2765 Related information
2766 This header field is only used for WebSocket opening handshake.
2768 The |Sec-WebSocket-Version| header field is used in the WebSocket
2769 opening handshake. It is sent from the client to the server to
2770 indicate the protocol version of the connection. This enables
2771 servers to correctly interpret the opening handshake and subsequent
2772 data being sent from the data, and close the connection if the server
2773 cannot interpret that data in a safe manner. The |Sec-WebSocket-
2774 Version| header field is also sent from the server to the client on
2775 WebSocket handshake error, when the version received from the client
2776 does not match a version understood by the server. In such a case
2777 the header field includes the protocol version(s) supported by the
2778 server.
2780 Note that there is no expectation that higher version numbers are
2781 necessarily backward compatible with lower version numbers.
2783 The |Sec-WebSocket-Version| header field MAY appear multiple times in
2784 an HTTP response (which is logically the same as a single |Sec-
2785 WebSocket-Version| header field that contains all values. However
2786 the |Sec-WebSocket-Version| header field MUST NOT appear more than
2787 once in an HTTP request.
2789 11.4. WebSocket Extension Name Registry
2791 This specification requests the creation of a new IANA registry for
2792 WebSocket Extension names to be used with the WebSocket protocol in
2793 accordance with the principles set out in RFC 5226 [RFC5226].
2795 As part of this registry IANA will maintain the following
2796 information:
2798 Extension Identifier
2799 The identifier of the extension, as will be used in the Sec-
2800 WebSocket-Extension header field registered in Section 11.3.2 of
2801 this specification. The value must conform to the requirements
2802 for an extension-token as defined in Section 9.1 of this
2803 specification.
2805 Extension Common Name
2806 The name of the extension, as the extension is generally referred
2807 to.
2809 Extension Definition
2810 A reference to the document in which the extension being used with
2811 the WebSocket protocol is defined.
2813 Known Incompatible Extensions
2814 A list of extension identifiers with which this extension is known
2815 to be incompatible.
2817 WebSocket Extension names are to be subject to "First Come First
2818 Served" IANA registration policy [RFC5226].
2820 There are no initial values in this registry.
2822 11.5. WebSocket Subprotocol Name Registry
2824 This specification requests the creation of a new IANA registry for
2825 WebSocket Subprotocol names to be used with the WebSocket protocol in
2826 accordance with the principles set out in RFC 5226 [RFC5226].
2828 As part of this registry IANA will maintain the following
2829 information:
2831 Subprotocol Identifier
2832 The identifier of the subprotocol, as will be used in the Sec-
2833 WebSocket-Protocol header field registered in Section 11.3.4 of
2834 this specification. The value must conform to the requirements
2835 given in Paragraph 10 of Section 4.1 of this specification, namely
2836 the value must be a token as defined by RFC 2616 [RFC2616].
2838 Subprotocol Common Name
2839 The name of the subprotocol, as the subprotocol is generally
2840 referred to.
2842 Subprotocol Definition
2843 A reference to the document in which the subprotocol being used
2844 with the WebSocket protocol is defined.
2846 WebSocket Subprotocol names are to be subject to "First Come First
2847 Served" IANA registration policy [RFC5226].
2849 11.6. WebSocket Version Number Registry
2851 This specification requests the creation of a new IANA registry for
2852 WebSocket Version Numbers to be used with the WebSocket protocol in
2853 accordance with the principles set out in RFC 5226 [RFC5226].
2855 As part of this registry IANA will maintain the following
2856 information:
2858 Version Number
2859 The version number to be used in the Sec-WebSocket-Version as
2860 specified in Section 4.1 of this specification. The value must be
2861 a non negative integer in the range between 0 and 255 (inclusive).
2863 Reference
2864 The RFC requesting a new version number.
2866 WebSocket Version Numbers are to be subject to "IETF Review" IANA
2867 registration policy [RFC5226]. In order to improve interoperability
2868 with intermediate versions published in Internet Drafts, version
2869 numbers associated with such drafts might be registered in this
2870 registry. Note that "IETF Review" applies to registrations
2871 corresponding to Internet Drafts.
2873 IANA is asked to add initial values to the registry, with suggested
2874 numerical values as these have been used in past versions of this
2875 protocol.
2877 Version Number | Reference
2878 -+----------------+-----------------------------------------+-
2879 | 0 + draft-ietf-hybi-thewebsocketprotocol-00 |
2880 -+----------------+-----------------------------------------+-
2881 | 1 + draft-ietf-hybi-thewebsocketprotocol-01 |
2882 -+----------------+-----------------------------------------+-
2883 | 2 + draft-ietf-hybi-thewebsocketprotocol-02 |
2884 -+----------------+-----------------------------------------+-
2885 | 3 + draft-ietf-hybi-thewebsocketprotocol-03 |
2886 -+----------------+-----------------------------------------+-
2887 | 4 + draft-ietf-hybi-thewebsocketprotocol-04 |
2888 -+----------------+-----------------------------------------+-
2889 | 5 + draft-ietf-hybi-thewebsocketprotocol-05 |
2890 -+----------------+-----------------------------------------+-
2891 | 6 + draft-ietf-hybi-thewebsocketprotocol-06 |
2892 -+----------------+-----------------------------------------+-
2893 | 7 + draft-ietf-hybi-thewebsocketprotocol-07 |
2894 -+----------------+-----------------------------------------+-
2895 | 8 + draft-ietf-hybi-thewebsocketprotocol-08 |
2896 -+----------------+-----------------------------------------+-
2897 | 9 + Reserved |
2898 -+----------------+-----------------------------------------+-
2899 | 10 + Reserved |
2900 -+----------------+-----------------------------------------+-
2901 | 11 + Reserved |
2902 -+----------------+-----------------------------------------+-
2903 | 12 + Reserved |
2904 -+----------------+-----------------------------------------+-
2905 | 13 + RFCXXXX (RFC Editor: please update) |
2906 -+----------------+-----------------------------------------+-
2908 11.7. WebSocket Close Code Number Registry
2910 This specification requests the creation of a new IANA registry for
2911 WebSocket Connection Close Code Numbers in accordance with the
2912 principles set out in RFC 5226 [RFC5226].
2914 As part of this registry IANA will maintain the following
2915 information:
2917 Status Code
2918 The Status Code which denotes a reason for a WebSocket connection
2919 closure as per Section 7.4 of this document. The status code is
2920 an integer number between 1000 and 4999 (inclusive).
2922 Meaning
2923 The meaning of the status code. Each status code has to have a
2924 unique meaning.
2926 Contact
2927 A contact for the entity reserving the status code.
2929 Reference
2930 The stable document requesting the status codes and defining their
2931 meaning. This is required for status codes in the range 1000-
2932 2999, and recommended for status codes in the range 3000-3999.
2934 WebSocket Close Code Numbers are to be subject to different
2935 registration requirements depending on their range. Unless otherwise
2936 specified, requests are subject to "Standards Action" IANA
2937 registration policy [RFC5226]. Requests for status codes for use by
2938 this protocol, its subsequent versions or extensions are subject to
2939 any one of "Standards Action", "Specification Required" (which
2940 implies "Designated Expert") or "IESG Review" IANA registration
2941 policies and should be granted status codes in the range 1000-2999.
2942 Requests for status codes for use by libraries, frameworks and
2943 applications are subject to "First Come First Served" IANA
2944 registration policy and should be granted in the range 3000-3999.
2945 The range of status codes from 4000-4999 is designated for Private
2946 Use. Requests should indicate whether they are requesting status
2947 codes for use by the WebSocket protocol (or a future version of the
2948 protocol) or by extensions, or by libraries/frameworks/applications.
2950 IANA is asked to add initial values to the registry, with suggested
2951 numerical values as these have been used in past versions of this
2952 protocol.
2954 |Status Code | Meaning | Contact | Reference |
2955 -+------------+-----------------+---------------+-----------|
2956 | 1000 | Normal Closure | hybi@ietf.org | RFC XXXX |
2957 -+------------+-----------------+---------------+-----------|
2958 | 1001 | Going Away | hybi@ietf.org | RFC XXXX |
2959 -+------------+-----------------+---------------+-----------|
2960 | 1002 | Protocol error | hybi@ietf.org | RFC XXXX |
2961 -+------------+-----------------+---------------+-----------|
2962 | 1003 | Unsupported Data| hybi@ietf.org | RFC XXXX |
2963 -+------------+-----------------+---------------+-----------|
2964 | 1004 | ---Reserved---- | hybi@ietf.org | RFC XXXX |
2965 -+------------+-----------------+---------------+-----------|
2966 | 1005 | No Status Rcvd | hybi@ietf.org | RFC XXXX |
2967 -+------------+-----------------+---------------+-----------|
2968 | 1006 | Abnormal Closure| hybi@ietf.org | RFC XXXX |
2969 -+------------+-----------------+---------------+-----------|
2970 | 1007 | Invalid frame | hybi@ietf.org | RFC XXXX |
2971 | | payload data | | |
2972 -+------------+-----------------+---------------+-----------|
2973 | 1008 | Policy Violation| hybi@ietf.org | RFC XXXX |
2974 -+------------+-----------------+---------------+-----------|
2975 | 1009 | Message Too Big | hybi@ietf.org | RFC XXXX |
2976 -+------------+-----------------+---------------+-----------|
2977 | 1010 | Mandatory Ext. | hybi@ietf.org | RFC XXXX |
2978 -+------------+-----------------+---------------+-----------|
2980 11.8. WebSocket Opcode Registry
2982 This specification requests the creation of a new IANA registry for
2983 WebSocket Opcodes in accordance with the principles set out in RFC
2984 5226 [RFC5226].
2986 As part of this registry IANA will maintain the following
2987 information:
2989 Opcode
2990 The opcode denotes the frame type of the WebSocket frame, as
2991 defined in Section 5.2. The status code is an integer number
2992 between 0 and 15, inclusive.
2994 Meaning
2995 The meaning of the opcode code.
2997 Reference
2998 The specification requesting the opcode.
3000 WebSocket Opcode numbers are subject to "Standards Action" IANA
3001 registration policy [RFC5226].
3003 IANA is asked to add initial values to the registry, with suggested
3004 numerical values as these have been used in past versions of this
3005 protocol.
3007 |Opcode | Meaning | Reference |
3008 -+--------+-------------------------------------+-----------|
3009 | 0 | Continuation Frame | RFC XXXX |
3010 -+--------+-------------------------------------+-----------|
3011 | 1 | Text Frame | RFC XXXX |
3012 -+--------+-------------------------------------+-----------|
3013 | 2 | Binary Frame | RFC XXXX |
3014 -+--------+-------------------------------------+-----------|
3015 | 8 | Connection Close Frame | RFC XXXX |
3016 -+--------+-------------------------------------+-----------|
3017 | 9 | Ping Frame | RFC XXXX |
3018 -+--------+-------------------------------------+-----------|
3019 | 10 | Pong Frame | RFC XXXX |
3020 -+--------+-------------------------------------+-----------|
3022 11.9. WebSocket Framing Header Bits Registry
3024 This specification requests the creation of a new IANA registry for
3025 WebSocket Framing Header Bits in accordance with the principles set
3026 out in RFC 5226 [RFC5226]. This registry controls assignment of the
3027 bits marked RSV1, RSV2, and RSV3 in Section 5.2.
3029 These bits are reserved for future versions or extensions of this
3030 specification.
3032 WebSocket Framing Header Bits assignments are subject to "Standards
3033 Action" IANA registration policy [RFC5226].
3035 12. Using the WebSocket protocol from Other Specifications
3037 The WebSocket protocol is intended to be used by another
3038 specification to provide a generic mechanism for dynamic author-
3039 defined content, e.g. in a specification defining a scripted API.
3041 Such a specification first needs to _Establish a WebSocket
3042 Connection_, providing that algorithm with:
3044 o The destination, consisting of a /host/ and a /port/.
3046 o A /resource name/, which allows for multiple services to be
3047 identified at one host and port.
3049 o A /secure/ flag, which is true if the connection is to be
3050 encrypted, and false otherwise.
3052 o An ASCII serialization of an origin that is being made responsible
3053 for the connection. [I-D.ietf-websec-origin]
3055 o Optionally a string identifying a protocol that is to be layered
3056 over the WebSocket connection.
3058 The /host/, /port/, /resource name/, and /secure/ flag are usually
3059 obtained from a URI using the steps to parse a WebSocket URI's
3060 components. These steps fail if the URI does not specify a
3061 WebSocket.
3063 If at any time the connection is to be closed, then the specification
3064 needs to use the _Close the WebSocket Connection_ algorithm
3065 (Section 7.1.1).
3067 Section 7.1.4 defines when _The WebSocket Connection is Closed_.
3069 While a connection is open, the specification will need to handle the
3070 cases when _A WebSocket Message Has Been Received_ (Section 6.2).
3072 To send some data /data/ to an open connection, the specification
3073 needs to _Send a WebSocket Message_ (Section 6.1).
3075 13. Acknowledgements
3077 Special thanks are due to Ian Hickson, who was the original author
3078 and editor of this protocol. The initial design of this
3079 specification benefitted from the participation of many people in the
3080 WHATWG and WHATWG mailing list. Contributions to that specification
3081 are not tracked by section, but a list of all who contributed to that
3082 specification is given in the WHATWG HTML specification at
3083 http://whatwg.org/html5.
3085 Special thanks also to John Tamplin for providing a significant
3086 amount of text for the Data Framing section of this specification.
3088 Special thanks also to Adam Barth for providing a significant amount
3089 of text and background research for the Data Masking section of this
3090 specification.
3092 Special thanks to Lisa Dusseault for the Apps Area review (and for
3093 helping to start this work), Richard Barnes for the Gen-Art review
3094 and Magnus Westerlund for the Transport Area Review. Special thanks
3095 to HYBI WG past and present WG chairs who tirelessly worked behind
3096 the scene to move this work toward completion: Joe Hildebrand,
3097 Salvatore Loreto and Gabriel Montenegro. And last but not least,
3098 special thank you to the responsible Area Director Peter Saint-Andre.
3100 Thank you to the following people who participated in discussions on
3101 the HYBI WG mailing list and contributed ideas and/or provided
3102 detailed reviews (the list is likely to be incomplete): Greg Wilkins,
3103 John Tamplin, Willy Tarreau, Maciej Stachowiak, Jamie Lokier, Scott
3104 Ferguson, Bjoern Hoehrmann, Julian Reschke, Dave Cridland, Andy
3105 Green, Eric Rescorla, Inaki Baz Castillo, Martin Thomson, Roberto
3106 Peon, Patrick McManus, Zhong Yu, Bruce Atherton, Takeshi Yoshino,
3107 Martin J. Duerst, James Graham, Simon Pieters, Roy T. Fielding,
3108 Mykyta Yevstifeyev, Len Holgate, Paul Colomiets, Piotr Kulaga, Brian
3109 Raymor, Jan Koehler, Joonas Lehtolahti, Sylvain Hellegouarch, Stephen
3110 Farrell, Sean Turner, Pete Resnick, Peter Thorson, Joe Mason, John
3111 Fallows, Alexander Philippou. Note that people listed above didn't
3112 necessarily endorse the end result of this work.
3114 14. References
3116 14.1. Normative References
3118 [ANSI.X3-4.1986]
3119 American National Standards Institute, "Coded Character
3120 Set - 7-bit American Standard Code for Information
3121 Interchange", ANSI X3.4, 1986.
3123 [FIPS.180-2.2002]
3124 National Institute of Standards and Technology, "Secure
3125 Hash Standard", FIPS PUB 180-2, August 2002, .
3128 [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and
3129 L. Jones, "SOCKS Protocol Version 5", RFC 1928,
3130 March 1996.
3132 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
3133 Requirement Levels", BCP 14, RFC 2119, March 1997.
3135 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
3136 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
3137 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
3139 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within
3140 HTTP/1.1", RFC 2817, May 2000.
3142 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
3144 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
3145 10646", STD 63, RFC 3629, November 2003.
3147 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
3148 Procedures for Message Header Fields", BCP 90, RFC 3864,
3149 September 2004.
3151 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
3152 Resource Identifier (URI): Generic Syntax", STD 66,
3153 RFC 3986, January 2005.
3155 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
3156 Identifiers (IRIs)", RFC 3987, January 2005.
3158 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
3159 Requirements for Security", BCP 106, RFC 4086, June 2005.
3161 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
3162 (TLS) Protocol Version 1.2", RFC 5246, August 2008.
3164 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions:
3165 Extension Definitions", RFC 6066, January 2011.
3167 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
3168 Encodings", RFC 4648, October 2006.
3170 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
3171 IANA Considerations Section in RFCs", BCP 26, RFC 5226,
3172 May 2008.
3174 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
3175 Specifications: ABNF", STD 68, RFC 5234, January 2008.
3177 [I-D.ietf-websec-origin]
3178 Barth, A., "The Web Origin Concept",
3179 draft-ietf-websec-origin-05 (work in progress),
3180 September 2011.
3182 14.2. Informative References
3184 [WSAPI] Hickson, I., "The Web Sockets API", August 2010,
3185 .
3187 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
3188 Unique IDentifier (UUID) URN Namespace", RFC 4122,
3189 July 2005.
3191 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
3192 April 2011.
3194 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
3195 October 2008.
3197 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins,
3198 "Known Issues and Best Practices for the Use of Long
3199 Polling and Streaming in Bidirectional HTTP", RFC 6202,
3200 April 2011.
3202 [RFC4270] Hoffman, P. and B. Schneier, "Attacks on Cryptographic
3203 Hashes in Internet Protocols", RFC 4270, November 2005.
3205 [W3C.REC-wsc-ui-20100812]
3206 Roessler, T. and A. Saldhana, "Web Security Context: User
3207 Interface Guidelines", World Wide Web Consortium
3208 Recommendation REC-wsc-ui-20100812, August 2010,
3209 .
3211 [TALKING] Huang, L-S., Chen, E., Barth, A., and E. Rescorla,
3212 "Talking to Yourself for Fun and Profit", 2010, .
3216 [XMLHttpRequest]
3217 van Kesteren, A., Ed., "XMLHttpRequest", August 2010,
3218 .
3220 Authors' Addresses
3222 Ian Fette
3223 Google, Inc.
3225 Email: ifette+ietf@google.com
3226 URI: http://www.ianfette.com/
3228 Alexey Melnikov
3229 Isode Ltd
3230 5 Castle Business Village
3231 36 Station Road
3232 Hampton, Middlesex TW12 2BX
3233 UK
3235 Email: Alexey.Melnikov@isode.com