idnits 2.17.1 draft-hixie-thewebsocketprotocol-33.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([HTML5]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet has text resembling RFC 2119 boilerplate text. -- The document date (August 14, 2009) is 5369 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'HTML5' ** Obsolete normative reference: RFC 2109 (Obsoleted by RFC 2965) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2965 (Obsoleted by RFC 6265) -- Possible downref: Non-RFC (?) normative reference: ref. 'WEBADDRESSES' Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group I. Hickson 3 Internet-Draft Google, Inc. 4 Intended status: Standards Track August 14, 2009 5 Expires: February 15, 2010 7 The Web Socket protocol 8 draft-hixie-thewebsocketprotocol-33 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on February 15, 2010. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 This protocol enables two-way communication between a user agent 47 running untrusted code running in a controlled environment to a 48 remote host that understands the protocol. It is intended to fail to 49 communicate with servers of pre-existing protocols like SMTP or HTTP, 50 while allowing HTTP servers to opt-in to supporting this protocol if 51 desired. It is designed to be easy to implement on the server side. 53 Author's note 55 This document is automatically generated from the same source 56 document as the HTML5 specification. [HTML5] 58 Please send feedback to either the hybi@ietf.org list or the 59 whatwg@whatwg.org list. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.1. Security model . . . . . . . . . . . . . . . . . . . . . . 4 65 1.2. Relationship to TCP/IP and HTTP . . . . . . . . . . . . . 4 66 1.3. Establishing a connection . . . . . . . . . . . . . . . . 5 67 1.4. The Web Socket protocol . . . . . . . . . . . . . . . . . 5 68 2. Conformance requirements . . . . . . . . . . . . . . . . . . . 7 69 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 70 3. Parsing Web Socket URLs . . . . . . . . . . . . . . . . . . . 8 71 4. Client-side requirements . . . . . . . . . . . . . . . . . . . 9 72 4.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 9 73 4.2. Data framing . . . . . . . . . . . . . . . . . . . . . . . 17 74 4.3. Closing the connection . . . . . . . . . . . . . . . . . . 18 75 4.4. Handling errors in UTF-8 . . . . . . . . . . . . . . . . . 18 76 5. Server-side requirements . . . . . . . . . . . . . . . . . . . 20 77 5.1. Minimal handshake . . . . . . . . . . . . . . . . . . . . 20 78 5.2. Handshake details . . . . . . . . . . . . . . . . . . . . 21 79 5.3. Data framing . . . . . . . . . . . . . . . . . . . . . . . 22 80 6. Closing the connection . . . . . . . . . . . . . . . . . . . . 23 81 7. Security considerations . . . . . . . . . . . . . . . . . . . 24 82 8. IANA considerations . . . . . . . . . . . . . . . . . . . . . 25 83 8.1. Registration of ws: scheme . . . . . . . . . . . . . . . . 25 84 8.2. Registration of wss: scheme . . . . . . . . . . . . . . . 25 85 8.3. Registration of ports 81 and 815 . . . . . . . . . . . . . 26 86 8.4. Registration of the "WebSocket" HTTP Upgrade keyword . . . 26 87 9. Normative References . . . . . . . . . . . . . . . . . . . . . 28 88 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 29 90 1. Introduction 92 _This section is non-normative._ 94 The Web Socket protocol is designed on the principle that there 95 should be minimal framing (the only framing that exists is to make 96 the protocol frame-based instead of stream-based, and to support a 97 distinction between Unicode text and binary frames). It is expected 98 that metadata would be layered on top of Web Socket by the 99 application layer, in the same way that metadata is layered on top of 100 TCP/IP by the application layer (HTTP). 102 Conceptually, Web Socket is really just a layer on top of TCP/IP that 103 adds a Web "origin"-based security model for browsers; adds an 104 addressing and protocol naming mechanism to support multiple services 105 on one port and multiple host names on one IP address; and layers a 106 framing mechanism on top of TCP to get back to the IP packet 107 mechanism that TCP is built on, but without length limits. Other 108 than that, it adds nothing. Basically it is intended to be as close 109 as possible to just exposing raw TCP/IP to script as possible given 110 the constraints of the Web. It's also designed in such a way that its 111 servers can share a port with HTTP servers, by having its handshake 112 be a valid HTTP Upgrade handshake also. 114 1.1. Security model 116 _This section is non-normative._ 118 The Web Socket protocol uses the origin model used by Web browsers to 119 restrict which Web pages can contact a Web Socket server when the Web 120 Socket protocol is used from a Web page. Naturally, when the Web 121 Socket protocol is used directly (not from a Web page), the origin 122 model is not useful, as the client can provide any arbitrary origin 123 string. 125 1.2. Relationship to TCP/IP and HTTP 127 _This section is non-normative._ 129 The Web Socket protocol is an independent TCP-based protocol. Its 130 only relationship to HTTP is that its handshake is interpreted by 131 HTTP servers as an Upgrade request. 133 The Web Socket protocol by default uses port 81 for regular Web 134 Socket connections and port 815 for Web Socket connections tunneled 135 over TLS. 137 1.3. Establishing a connection 139 _This section is non-normative._ 141 There are several options for establishing a Web Socket connection. 143 The simplest method is to use port 81 to get a direct connection to a 144 Web Socket server. However, this port may be blocked by firewalls. 146 The second simplest method is to use TLS encryption and port 815 to 147 connect directly to a Web Socket server. This is the preferred 148 solution, as it is secure and correct. However, TLS encryption can 149 be computationally expensive, and port 815 might also be blocked by 150 firewalls. 152 To avoid firewalls, ports 80 and 443 might be used instead. These 153 are the HTTP and HTTPS ports. Port 80 traffic, however, will often 154 be intercepted by HTTP proxies, which can lead to the connection 155 failing to be established. 157 Port 443, using encryption, is therefore the most reliable solution. 158 It is unlikely to be blocked by a firewall or intercepted by a proxy. 159 However, again, TLS encryption can be computationally expensive. 161 When a connection is to be made to a port that is shared by an HTTP 162 server (a situation that is quite likely to occur with traffic to 163 ports 80 and 443), the connection will appear to the HTTP server to 164 be a regular GET request with an Upgrade offer. In relatively simple 165 setups with just one IP address and a single server for all traffic 166 to a single hostname, this might allow a practical way for systems 167 based on the Web Socket protocol to be deployed. In more elaborate 168 setups (e.g. with load balancers and multiple servers), a dedicated 169 set of hosts for Web Socket connections separate from the HTTP 170 servers is probably easier to manage. 172 1.4. The Web Socket protocol 174 _This section is non-normative._ 176 The protocol has two parts: a handshake, and then the data transfer. 178 The handshake from the client looks as follows: 180 GET /demo HTTP/1.1 181 Upgrade: WebSocket 182 Connection: Upgrade 183 Host: example.com 184 Origin: http://example.com 185 WebSocket-Protocol: sample 187 The handshake from the server looks as follows: 189 HTTP/1.1 101 Web Socket Protocol Handshake 190 Upgrade: WebSocket 191 Connection: Upgrade 192 WebSocket-Origin: http://example.com 193 WebSocket-Location: ws://example.com/demo 194 WebSocket-Protocol: sample 196 Once the client and server have both sent their handshakes, and if 197 the handshake was successful, then the data transfer part starts. 198 This is a two-way communication channel where each side can, 199 independently from the other, send data at will. 201 Data is sent in the form of UTF-8 text. Each frame of data starts 202 with a 0x00 byte and ends with a 0xFF byte, with the UTF-8 text in 203 between. 205 2. Conformance requirements 207 All diagrams, examples, and notes in this specification are non- 208 normative, as are all sections explicitly marked non-normative. 209 Everything else in this specification is normative. 211 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 212 "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this 213 document are to be interpreted as described in RFC2119. For 214 readability, these words do not appear in all uppercase letters in 215 this specification. [RFC2119] 217 Requirements phrased in the imperative as part of algorithms (such as 218 "strip any leading space characters" or "return false and abort these 219 steps") are to be interpreted with the meaning of the key word 220 ("must", "should", "may", etc) used in introducing the algorithm. 222 Conformance requirements phrased as algorithms or specific steps may 223 be implemented in any manner, so long as the end result is 224 equivalent. (In particular, the algorithms defined in this 225 specification are intended to be easy to follow, and not intended to 226 be performant.) 228 Implementations may impose implementation-specific limits on 229 otherwise unconstrained inputs, e.g. to prevent denial of service 230 attacks, to guard against running out of memory, or to work around 231 platform-specific limitations. 233 The conformance classes defined by this specification are user agents 234 and servers. 236 2.1. Terminology 238 *Converting a string to ASCII lowercase* means replacing all 239 characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER 240 A to LATIN CAPITAL LETTER Z) with the corresponding characters in the 241 range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL 242 LETTER Z). 244 The term "URL" is used in this section in a manner consistent with 245 the terminology used in HTML, namely, to denote a string that might 246 or might not be a valid URI or IRI and to which certain error 247 handling behaviors will be applied when the string is parsed. 248 [HTML5] 250 3. Parsing Web Socket URLs 252 The steps to *parse a Web Socket URL's components* from a string 253 /url/ are as follows. These steps return either a /host/, a /port/, 254 a /resource name/, and a /secure/ flag, or they fail. 256 1. Parse the /url/ string using the parse a Web address algorithm 257 defined by the Web addresses specification. [WEBADDRESSES] 259 2. If the previous step failed, or if /url/ does not have a 260 component whose value is either "ws" or "wss", when 261 compared in an ASCII case-insensitive manner, then fail this 262 algorithm. 264 3. If /protocol/ is specified but is either the empty string or 265 contains characters that are not in the range U+0021 .. U+007E, 266 then fail this algorithm. 268 4. If the component of /url/ is "ws", set /secure/ to 269 false; otherwise, the component is "wss", set /secure/ 270 to true. 272 5. Let /host/ be the value of the component of /url/, 273 converted to ASCII lowercase. 275 6. If /url/ has a component, then let /port/ be that 276 component's value; otherwise, there is no explicit /port/. 278 7. If there is no explicit /port/, then: if /secure/ is false, let 279 /port/ be 81, otherwise let /port/ be 815. 281 8. Let /resource name/ be the value of the component (which 282 might be empty) of /url/. 284 9. If /resource name/ is the empty string, set it to a single 285 character U+002F SOLIDUS (/). 287 10. If /url/ has a component, then append a single U+003F 288 QUESTION MARK (?) character to /resource name/, followed by the 289 value of the component. 291 11. Return /host/, /port/, /resource name/, and /secure/. 293 4. Client-side requirements 295 _This section only applies to user agents, not to servers._ 297 NOTE: This specification doesn't currently define a limit to the 298 number of simultaneous connections that a client can establish to a 299 server. 301 4.1. Handshake 303 When the user agent is to *establish a Web Socket connection* to a 304 host /host/, on a port /port/, from an origin /origin/, with a flag 305 /secure/, with a particular /resource name/, and optionally with a 306 particular /protocol/, it must run the following steps. 308 NOTE: The /host/ and /origin/ strings will be all-lowercase when this 309 algorithm is invoked. 311 1. If the user agent already has a Web Socket connection to the 312 remote host (IP address) identified by /host/, even if known by 313 another name, wait until that connection has been established or 314 for that connection to have failed. 316 NOTE: This makes it harder for a script to perform a denial of 317 service attack by just opening a large number of Web Socket 318 connections to a remote host. 320 NOTE: There is no limit to the number of established Web Socket 321 connections a user agent can have with a single remote host. 322 Servers can refuse to connect users with an excessive number of 323 connections, or disconnect resource-hogging users when suffering 324 high load. 326 2. _Connect_: If the user agent is configured to use a proxy when 327 using the Web Socket protocol to connect to host /host/ and/or 328 port /port/, then connect to that proxy and ask it to open a 329 TCP/IP connection to the host given by /host/ and the port given 330 by /port/. 332 EXAMPLE: For example, if the user agent uses an HTTP proxy 333 for all traffic, then if it was to try to connect to port 80 334 on server example.com, it might send the following lines to 335 the proxy server: 337 CONNECT example.com:80 HTTP/1.1 338 Host: example.com 340 If there was a password, the connection might look like: 342 CONNECT example.com:80 HTTP/1.1 343 Host: example.com 344 Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE= 346 Otherwise, if the user agent is not configured to use a proxy, 347 then open a TCP/IP connection to the host given by /host/ and 348 the port given by /port/. 350 NOTE: Implementations that do not expose explicit UI for 351 selecting a proxy for Web Socket connections separate from other 352 proxies are encouraged to use a SOCKS proxy for Web Socket 353 connections, if available, or failing that, to prefer the proxy 354 configured for HTTPS connections over the proxy configured for 355 HTTP connections. 357 3. If the connection could not be opened, then fail the Web Socket 358 connection and abort these steps. 360 4. If /secure/ is true, perform a TLS handshake over the 361 connection. If this fails (e.g. the server's certificate could 362 not be verified), then fail the Web Socket connection and abort 363 these steps. Otherwise, all further communication on this 364 channel must run through the encrypted tunnel. [RFC2246] 366 5. Send the following bytes to the remote side (the server): 368 47 45 54 20 370 Send the /resource name/ value, encoded as US-ASCII. 372 Send the following bytes: 374 20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61 375 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43 376 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61 377 64 65 0d 0a 379 NOTE: The string "GET ", the path, " HTTP/1.1", CRLF, the string 380 "Upgrade: WebSocket", CRLF, and the string "Connection: 381 Upgrade", CRLF. 383 6. Send the following bytes: 385 48 6f 73 74 3a 20 387 Send the /host/ value, encoded as US-ASCII. 389 Send the following bytes: 391 0d 0a 393 NOTE: The string "Host: ", the host, and CRLF. 395 7. Send the following bytes: 397 4f 72 69 67 69 6e 3a 20 399 Send the /origin/ value, encoded as US-ASCII. 401 NOTE: The /origin/ value is a string that was passed to this 402 algorithm. 404 Send the following bytes: 406 0d 0a 408 NOTE: The string "Origin: ", the origin, and CRLF. 410 8. If there is no /protocol/, then skip this step. 412 Otherwise, send the following bytes: 414 57 65 62 53 6f 63 6b 65 74 2d 50 72 6f 74 6f 63 415 6f 6c 3a 20 417 Send the /protocol/ value, encoded as US-ASCII. 419 Send the following bytes: 421 0d 0a 423 NOTE: The string "WebSocket-Protocol: ", the protocol, and CRLF. 425 9. If the client has any authentication information or cookies that 426 would be relevant to a resource accessed over HTTP, if /secure/ 427 is false, or HTTPS, if it is true, on host /host/, port /port/, 428 with /resource name/ as the path (and possibly query 429 parameters), then HTTP headers that would be appropriate for 430 that information should be sent at this point. [RFC2616] 431 [RFC2109] [RFC2965] 433 Each header must be on a line of its own (each ending with a CR 434 LF sequence). For the purposes of this step, each header must 435 not be split into multiple lines (despite HTTP otherwise 436 allowing this with continuation lines). 438 EXAMPLE: For example, if the server had a username and 439 password that applied to |http://example.com/socket|, and the 440 Web Socket was being opened to |ws://example.com:80/socket|, 441 it could send them: 443 Authorization: Basic d2FsbGU6ZXZl 445 However, it would not send them if the Web Socket was being 446 opened to |ws://example.com/socket|, as that uses a different 447 port (81, not 80). 449 10. Send the following bytes: 451 0d 0a 453 NOTE: Just a CRLF (a blank line). 455 11. Read bytes from the server until either the connection closes, 456 or a 0x0a byte is read. Let /header/ be these bytes, including 457 the 0x0a byte. 459 If /header/ is not at least two bytes long, or if the last two 460 bytes aren't 0x0d and 0x0a respectively, then fail the Web 461 Socket connection and abort these steps. 463 User agents may apply a timeout to this step, failing the Web 464 Socket connection if the server does not send back data in a 465 suitable time period. 467 12. If /header/ consists of 44 bytes that exactly match the 468 following, then let /mode/ be _normal_. 470 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 471 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 472 20 48 61 6e 64 73 68 61 6b 65 0d 0a 474 NOTE: The string "HTTP/1.1 101 Web Socket Protocol Handshake" 475 followed by a CRLF pair. 477 Otherwise, let /code/ be the substring of /header/ that starts 478 from the byte after the first 0x20 byte, and ends with the byte 479 before the second 0x20 byte. If there are not at least two 0x20 480 bytes in /header/, then fail the Web Socket connection and abort 481 these steps. 483 If /code/, interpreted as ASCII, is "401", then let /mode/ be 484 _authenticate_. 486 Otherwise, fail the Web Socket connection and abort these steps. 488 13. If /mode/ is _normal_, then read 41 bytes from the server. 490 If the connection closes before 41 bytes are received, or if the 491 41 bytes aren't exactly equal to the following bytes, then fail 492 the Web Socket connection and abort these steps. 494 55 70 67 72 61 64 65 3a 20 57 65 62 53 6f 63 6b 495 65 74 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 496 55 70 67 72 61 64 65 0d 0a 498 NOTE: The string "Upgrade: WebSocket", CRLF, the string 499 "Connection: Upgrade", CRLF. 501 User agents may apply a timeout to this step, failing the Web 502 Socket connection if the server does not respond with the above 503 bytes within a suitable time period. 505 NOTE: This step is skipped if /mode/ is _authenticate_. 507 14. Let /headers/ be a list of name-value pairs, initially empty. 509 15. _Header_: Let /name/ and /value/ be empty byte arrays. 511 16. Read a byte from the server. 513 If the connection closes before this byte is received, then fail 514 the Web Socket connection and abort these steps. 516 Otherwise, handle the byte as described in the appropriate entry 517 below: 519 -> If the byte is 0x0d (ASCII CR) 520 If the /name/ byte array is empty, then jump to the headers 521 processing step. Otherwise, fail the Web Socket connection 522 and abort these steps. 524 -> If the byte is 0x0a (ASCII LF) 525 Fail the Web Socket connection and abort these steps. 527 -> If the byte is 0x3a (ASCII ":") 528 Move on to the next step. 530 -> If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z") 531 Append a byte whose value is the byte's value plus 0x20 to 532 the /name/ byte array and redo this step for the next byte. 534 -> Otherwise 535 Append the byte to the /name/ byte array and redo this step 536 for the next byte. 538 NOTE: This reads a header name, terminated by a colon, 539 converting upper-case ASCII letters to lowercase, and aborting 540 if a stray CR or LF is found. 542 17. Read a byte from the server. 544 If the connection closes before this byte is received, then fail 545 the Web Socket connection and abort these steps. 547 Otherwise, handle the byte as described in the appropriate entry 548 below: 550 -> If the byte is 0x20 (ASCII space) 551 Ignore the byte and move on to the next step. 553 -> Otherwise 554 Treat the byte as described by the list in the next step, 555 then move on to that next step for real. 557 NOTE: This skips past a space character after the colon, if 558 necessary. 560 18. Read a byte from the server. 562 If the connection closes before this byte is received, then fail 563 the Web Socket connection and abort these steps. 565 Otherwise, handle the byte as described in the appropriate entry 566 below: 568 -> If the byte is 0x0d (ASCII CR) 569 Move on to the next step. 571 -> If the byte is 0x0a (ASCII LF) 572 Fail the Web Socket connection and abort these steps. 574 -> Otherwise 575 Append the byte to the /value/ byte array and redo this step 576 for the next byte. 578 NOTE: This reads a header value, terminated by a CRLF. 580 19. Read a byte from the server. 582 If the connection closes before this byte is received, or if the 583 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 584 connection and abort these steps. 586 NOTE: This skips past the LF byte of the CRLF after the header. 588 20. Append an entry to the /headers/ list that has the name given by 589 the string obtained by interpreting the /name/ byte array as a 590 UTF-8 byte stream and the value given by the string obtained by 591 interpreting the /value/ byte array as a UTF-8 byte stream. 593 21. Return to the "Header" step above. 595 22. _Headers processing_: Read a byte from the server. 597 If the connection closes before this byte is received, or if the 598 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 599 connection and abort these steps. 601 NOTE: This skips past the LF byte of the CRLF after the blank 602 line after the headers. 604 23. If /mode/ is _normal_, then: If there is not exactly one entry 605 in the /headers/ list whose name is "websocket-origin", or if 606 there is not exactly one entry in the /headers/ list whose name 607 is "websocket-location", or if the /protocol/ was specified but 608 there is not exactly one entry in the /headers/ list whose name 609 is "websocket-protocol", or if there are any entries in the 610 /headers/ list whose names are the empty string, then fail the 611 Web Socket connection and abort these steps. Otherwise, handle 612 each entry in the /headers/ list as follows: 614 -> If the entry's name is "websocket-origin" 615 If the value is not exactly equal to /origin/, converted to 616 ASCII lowercase, then fail the Web Socket connection and 617 abort these steps. 619 -> If the entry's name is "websocket-location" 620 If the value is not exactly equal to a string consisting of 621 the following components in the same order, then fail the Web 622 Socket connection and abort these steps: 624 1. The string "ws" if /secure/ is false and "wss" if 625 /secure/ is true 627 2. The three characters "://". 629 3. The value of /host/. 631 4. If /secure/ is false and /port/ is not 81, or if /secure/ 632 is true and /port/ is not 815: a ":" character followed 633 by the value of /port/. 635 5. The value of /resource name/. 637 -> If the entry's name is "websocket-protocol" 638 If there was a /protocol/ specified, and the value is not 639 exactly equal to /protocol/, then fail the Web Socket 640 connection and abort these steps. (If no /protocol/ was 641 specified, the header is ignored.) 643 -> If the entry's name is "set-cookie" or "set-cookie2" or 644 another cookie-related header name 645 Handle the cookie as defined by the appropriate spec, with 646 the resource being the one with the host /host/, the port 647 /port/, the path (and possibly query parameters) /resource 648 name/, and the scheme |http| if /secure/ is false and |https| 649 if /secure/ is true. [RFC2109] [RFC2965] 651 -> Any other name 652 Ignore it. 654 If /mode/ is _authenticate_, then: If there is not exactly one 655 entry in the /headers/ list whose name is "www-authenticate", 656 then fail the Web Socket connection and abort these steps. 657 Otherwise, handle each entry in the /headers/ list as follows: 659 -> If the entry's name is "www-authenticate" 660 Obtain credentials in a manner consistent with the 661 requirements for handling the |WWW-Authenticate| header in 662 HTTP, and then close the connection (if the server has not 663 already done so) and jump back to the step labeled _connect_, 664 including the relevant authentication headers in the new 665 request. [RFC2616] 667 -> Any other name 668 Ignore it. 670 24. The *Web Socket connection is established*. Now the user agent 671 must send and receive to and from the connection as described in 672 the next section. 674 4.2. Data framing 676 Once a Web Socket connection is established, the user agent must run 677 through the following state machine for the bytes sent by the server. 679 1. Try to read a byte from the server. Let /frame type/ be that 680 byte. 682 If no byte could be read because the Web Socket connection is 683 closed, then abort. 685 2. Handle the /frame type/ byte as follows: 687 If the high-order bit of the /frame type/ byte is set (i.e. if 688 /frame type/ _and_ed with 0x80 returns 0x80) 689 Run these steps. If at any point during these steps a read is 690 attempted but fails because the Web Socket connection is 691 closed, then abort. 693 1. Let /length/ be zero. 695 2. _Length_: Read a byte, let /b/ be that byte. 697 3. Let /b_v/ be integer corresponding to the low 7 bits of 698 /b/ (the value you would get by _and_ing /b/ with 0x7f). 700 4. Multiply /length/ by 128, add /b_v/ to that result, and 701 store the final result in /length/. 703 5. If the high-order bit of /b/ is set (i.e. if /b/ _and_ed 704 with 0x80 returns 0x80), then return to the step above 705 labeled _length_. 707 6. Read /length/ bytes. 709 7. Discard the read bytes. 711 If the high-order bit of the /frame type/ byte is _not_ set (i.e. 712 if /frame type/ _and_ed with 0x80 returns 0x00) 713 Run these steps. If at any point during these steps a read is 714 attempted but fails because the Web Socket connection is 715 closed, then abort. 717 1. Let /raw data/ be an empty byte array. 719 2. _Data_: Read a byte, let /b/ be that byte. If the client 720 runs out of resources for buffering the incoming data, or 721 hits an artificial resource limit intended to avoid 722 resource starvation, then it must fail the Web Socket 723 connection and abort these steps. 725 3. If /b/ is not 0xff, then append /b/ to /raw data/ and 726 return to the previous step (labeled _data_). 728 4. Interpret /raw data/ as a UTF-8 string, and store that 729 string in /data/. 731 5. If /frame type/ is 0x00, then *a message has been 732 received* with text /data/. Otherwise, discard the data. 734 3. Return to the first step to read the next byte. 736 If the user agent is faced with content that is too large to be 737 handled appropriately, then it must fail the Web Socket connection. 739 Once a Web Socket connection is established, the user agent must use 740 the following steps to *send /data/ using the Web Socket*: 742 1. Send a 0x00 byte to the server. 744 2. Encode /data/ using UTF-8 and send the resulting byte stream to 745 the server. 747 3. Send a 0xff byte to the server. 749 If at any point there is a fatal problem with sending data to the 750 server, the user agent must fail the Web Socket connection. 752 4.3. Closing the connection 754 To *fail the Web Socket connection*, the user agent must close the 755 Web Socket connection, and may report the problem to the user (which 756 would be especially useful for developers). However, user agents 757 must not convey the failure information to the script that attempted 758 the connection in a way distinguishable from the Web Socket being 759 closed normally. 761 Except as indicated above or as specified by the application layer 762 (e.g. a script using the Web Socket API), user agents should not 763 close the connection. 765 4.4. Handling errors in UTF-8 767 When a client is to interpret a byte stream as UTF-8 but finds that 768 the byte stream is not in fact a valid UTF-8 stream, then any bytes 769 or sequences of bytes that are not valid UTF-8 sequences must be 770 interpreted as a U+FFFD REPLACEMENT CHARACTER. 772 5. Server-side requirements 774 _This section only applies to servers._ 776 5.1. Minimal handshake 778 NOTE: This section describes the minimal requirements for a server- 779 side implementation of Web Sockets. 781 Listen on a port for TCP/IP. Upon receiving a connection request, 782 open a connection and send the following bytes back to the client: 784 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 785 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 786 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 787 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 788 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 789 61 64 65 0d 0a 791 Send the string "WebSocket-Origin" followed by a U+003A COLON (":") 792 followed by the ASCII serialization of the origin from which the 793 server is willing to accept connections, followed by a CRLF pair 794 (0x0d 0x0a). 796 For instance: 798 WebSocket-Origin: http://example.com 800 Send the string "WebSocket-Location" followed by a U+003A COLON (":") 801 followed by the URL of the Web Socket script, followed by a CRLF pair 802 (0x0d 0x0a). 804 For instance: 806 WebSocket-Location: ws://example.com:80/demo 808 Send another CRLF pair (0x0d 0x0a). 810 Read data from the client until four bytes 0x0d 0x0a 0x0d 0x0a are 811 read. This data must either be discarded or handled as described in 812 the following section describing the handshake details. 814 If the connection isn't dropped at this point, go to the data framing 815 section. 817 5.2. Handshake details 819 The previous section ignores the data that is transmitted by the 820 client during the handshake. 822 The data sent by the client consists of a number of fields separated 823 by CR LF pairs (bytes 0x0d 0x0a). 825 The first field consists of three tokens separated by space 826 characters (byte 0x20). The middle token is the path being opened. 827 If the server supports multiple paths, then the server should echo 828 the value of this field in the initial handshake, as part of the URL 829 given on the |WebSocket-Location| line (after the appropriate scheme 830 and host). 832 If the first field does not have three tokens, the server should 833 abort the connection as it probably represents an errorneous client. 835 The remaining fields consist of name-value pairs, with the name part 836 separated from the value part by a colon and a space (bytes 0x3a 837 0x20). Of these, several are interesting: 839 Host (bytes 48 6f 73 74) 840 The value gives the hostname that the client intended to use when 841 opening the Web Socket. It would be of interest in particular to 842 virtual hosting environments, where one server might serve 843 multiple hosts, and might therefore want to return different data. 845 The right host has to be output as part of the URL given on the 846 |WebSocket-Location| line of the handshake described above, to 847 verify that the server knows that it is really representing that 848 host. 850 Origin (bytes 4f 72 69 67 69 6e) 851 The value gives the scheme, hostname, and port (if it's not the 852 default port for the given scheme) of the page that asked the 853 client to open the Web Socket. It would be interesting if the 854 server's operator had deals with operators of other sites, since 855 the server could then decide how to respond (or indeed, _whether_ 856 to respond) based on which site was requesting a connection. 858 If the server supports connections from more than one origin, then 859 the server should echo the value of this field in the initial 860 handshake, on the |WebSocket-Origin| line. 862 Other fields 863 Other fields can be used, such as "Cookie" or "Authorization", for 864 authentication purposes. 866 Any fields that lack the colon-space separator should be discarded 867 and may cause the server to disconnect. 869 5.3. Data framing 871 NOTE: This section only describes how to handle content that this 872 specification allows user agents to send (text). It doesn't handle 873 any arbitrary content in the same way that the requirements on user 874 agents defined earlier handle any content including possible future 875 extensions to the protocols. 877 The server must run through the following steps to process the bytes 878 sent by the client: 880 1. Read a byte from the client. Assuming everything is going 881 according to plan, it will be a 0x00 byte. If the byte is not a 882 0x00 byte, then the server may disconnect. 884 2. Let /raw data/ be an empty byte array. 886 3. _Data_: Read a byte, let /b/ be that byte. 888 4. If /b/ is not 0xff, then append /b/ to /raw data/ and return to 889 the previous step (labeled _data_). 891 5. Interpret /raw data/ as a UTF-8 string, and apply whatever 892 server-specific processing is to occur for the resulting string. 894 6. Return to the first step to read the next byte. 896 The server must run through the following steps to send strings to 897 the client: 899 1. Send a 0x00 byte to the client to indicate the start of a string. 901 2. Encode /data/ using UTF-8 and send the resulting byte stream to 902 the client. 904 3. Send a 0xff byte to the client to indicate the end of the 905 message. 907 6. Closing the connection 909 To *close the Web Socket connection*, either the user agent or the 910 server closes the TCP/IP connection. There is no closing handshake. 911 Whether the user agent or the server closes the connection, it is 912 said that the *Web Socket connection is closed*. 914 Servers may close the Web Socket connection whenever desired. 916 User agents should not close the Web Socket connection arbitrarily. 918 7. Security considerations 920 While this protocol is intended to be used by scripts in Web pages, 921 it can also be used directly by hosts. Such hosts are acting on 922 their own behalf, and can therefore send fake "Origin" headers, 923 misleading the server. Servers should therefore be careful about 924 assuming that they are talking directly to scripts from known 925 origins, and must consider that they might be accessed in unexpected 926 ways. In particular, a server should not trust that any input is 927 valid. 929 EXAMPLE: For example, if the server uses input as part of SQL 930 queries, all input text should be escaped before being passed to the 931 SQL server, lest the server be susceptible to SQL injection. 933 Servers that are not intended to process input from any Web page but 934 only for certain sites should verify the "Origin" header is an origin 935 they expect, and should only respond with the corresponding 936 "WebSocket-Origin" if it is an accepted origin. Servers that only 937 accept input from one origin can just send back that value in the 938 "WebSocket-Origin" header, without bothering to check the client's 939 value. 941 If at any time a server is faced with data that it does not 942 understand, or that violates some criteria by which the server 943 determines safety of input, or when the server sees a handshake that 944 does not correspond to the values the server is expecting (e.g. 945 incorrect path or origin), the server should just disconnect. It is 946 always safe to disconnect. 948 8. IANA considerations 950 8.1. Registration of ws: scheme 952 A |ws:| URL identifies a Web Socket server and resource name. 954 URI scheme name. 955 ws 957 Status. 958 Permanent. 960 URI scheme syntax. 961 In ABNF terms using the terminals from the IRI specifications: 962 [RFC5238] [RFC3987] 964 "ws" ":" ihier-part [ "?" iquery ] 966 URI scheme semantics. 967 The only operation for this scheme is to open a connection using 968 the Web Socket protocol. 970 Encoding considerations. 971 UTF-8 only. 973 Applications/protocols that use this URI scheme name. 974 Web Socket protocol. 976 Interoperability considerations. 977 None. 979 Security considerations. 980 See "Security considerations" section above. 982 Contact. 983 Ian Hickson 985 Author/Change controller. 986 Ian Hickson 988 References. 989 This document. 991 8.2. Registration of wss: scheme 993 A |wss:| URL identifies a Web Socket server and resource name, and 994 indicates that traffic over that connection is to be encrypted. 996 URI scheme name. 997 wss 999 Status. 1000 Permanent. 1002 URI scheme syntax. 1003 In ABNF terms using the terminals from the IRI specifications: 1004 [RFC5238] [RFC3987] 1006 "ws" ":" ihier-part [ "?" iquery ] 1008 URI scheme semantics. 1009 The only operation for this scheme is to open a connection using 1010 the Web Socket protocol, encrypted using TLS. 1012 Encoding considerations. 1013 UTF-8 only. 1015 Applications/protocols that use this URI scheme name. 1016 Web Socket protocol over TLS. 1018 Interoperability considerations. 1019 None. 1021 Security considerations. 1022 See "Security considerations" section above. 1024 Contact. 1025 Ian Hickson 1027 Author/Change controller. 1028 Ian Hickson 1030 References. 1031 This document. 1033 8.3. Registration of ports 81 and 815 1035 See IANA ticket #257454 for port 81 and IANA ticket #257455 for port 1036 815. 1038 8.4. Registration of the "WebSocket" HTTP Upgrade keyword 1040 Name of token. 1041 WebSocket 1043 Author/Change controller. 1044 Ian Hickson 1046 Contact. 1047 Ian Hickson 1049 References. 1050 This document. 1052 9. Normative References 1054 [HTML5] Hickson, I., "HTML5", August 2009. 1056 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 1057 Mechanism", RFC 2109, February 1997. 1059 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1060 Requirement Levels", BCP 14, RFC 2119, March 1997. 1062 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1063 RFC 2246, January 1999. 1065 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1066 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1067 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1069 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 1070 Mechanism", RFC 2965, October 2000. 1072 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1073 Identifiers (IRIs)", RFC 3987, January 2005. 1075 [RFC5238] Phelan, T., "Datagram Transport Layer Security (DTLS) over 1076 the Datagram Congestion Control Protocol (DCCP)", 1077 RFC 5238, May 2008. 1079 [WEBADDRESSES] 1080 Connolly, D. and C. Sperberg-McQueen, "Web addresses in 1081 HTML 5", May 2009. 1083 Author's Address 1085 Ian Hickson 1086 Google, Inc. 1088 Email: ian@hixie.ch 1089 URI: http://ln.hixie.ch/