idnits 2.17.1 draft-hixie-thewebsocketprotocol-32.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-32 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 . . . . . . . . . . . . . . . . . . 19 75 4.4. Handling errors in UTF-8 . . . . . . . . . . . . . . . . . 19 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 either "301", "302", "303", 484 "307", then let /mode/ be _redirect_. 486 If /code/, interpreted as ASCII, is "401", then let /mode/ be 487 _authenticate_. 489 Otherwise, fail the Web Socket connection and abort these steps. 491 13. If /mode/ is _normal_, then read 41 bytes from the server. 493 If the connection closes before 41 bytes are received, or if the 494 41 bytes aren't exactly equal to the following bytes, then fail 495 the Web Socket connection and abort these steps. 497 55 70 67 72 61 64 65 3a 20 57 65 62 53 6f 63 6b 498 65 74 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 499 55 70 67 72 61 64 65 0d 0a 501 NOTE: The string "Upgrade: WebSocket", CRLF, the string 502 "Connection: Upgrade", CRLF. 504 User agents may apply a timeout to this step, failing the Web 505 Socket connection if the server does not respond with the above 506 bytes within a suitable time period. 508 NOTE: This step is skipped if /mode/ is _redirect_ or 509 _authenticate_. 511 14. Let /headers/ be a list of name-value pairs, initially empty. 513 15. _Header_: Let /name/ and /value/ be empty byte arrays. 515 16. Read a byte from the server. 517 If the connection closes before this byte is received, then fail 518 the Web Socket connection and abort these steps. 520 Otherwise, handle the byte as described in the appropriate entry 521 below: 523 -> If the byte is 0x0d (ASCII CR) 524 If the /name/ byte array is empty, then jump to the headers 525 processing step. Otherwise, fail the Web Socket connection 526 and abort these steps. 528 -> If the byte is 0x0a (ASCII LF) 529 Fail the Web Socket connection and abort these steps. 531 -> If the byte is 0x3a (ASCII ":") 532 Move on to the next step. 534 -> If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z") 535 Append a byte whose value is the byte's value plus 0x20 to 536 the /name/ byte array and redo this step for the next byte. 538 -> Otherwise 539 Append the byte to the /name/ byte array and redo this step 540 for the next byte. 542 NOTE: This reads a header name, terminated by a colon, 543 converting upper-case ASCII letters to lowercase, and aborting 544 if a stray CR or LF is found. 546 17. Read a byte from the server. 548 If the connection closes before this byte is received, then fail 549 the Web Socket connection and abort these steps. 551 Otherwise, handle the byte as described in the appropriate entry 552 below: 554 -> If the byte is 0x20 (ASCII space) 555 Ignore the byte and move on to the next step. 557 -> Otherwise 558 Treat the byte as described by the list in the next step, 559 then move on to that next step for real. 561 NOTE: This skips past a space character after the colon, if 562 necessary. 564 18. Read a byte from the server. 566 If the connection closes before this byte is received, then fail 567 the Web Socket connection and abort these steps. 569 Otherwise, handle the byte as described in the appropriate entry 570 below: 572 -> If the byte is 0x0d (ASCII CR) 573 Move on to the next step. 575 -> If the byte is 0x0a (ASCII LF) 576 Fail the Web Socket connection and abort these steps. 578 -> Otherwise 579 Append the byte to the /value/ byte array and redo this step 580 for the next byte. 582 NOTE: This reads a header value, terminated by a CRLF. 584 19. Read a byte from the server. 586 If the connection closes before this byte is received, or if the 587 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 588 connection and abort these steps. 590 NOTE: This skips past the LF byte of the CRLF after the header. 592 20. Append an entry to the /headers/ list that has the name given by 593 the string obtained by interpreting the /name/ byte array as a 594 UTF-8 byte stream and the value given by the string obtained by 595 interpreting the /value/ byte array as a UTF-8 byte stream. 597 21. Return to the "Header" step above. 599 22. _Headers processing_: Read a byte from the server. 601 If the connection closes before this byte is received, or if the 602 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 603 connection and abort these steps. 605 NOTE: This skips past the LF byte of the CRLF after the blank 606 line after the headers. 608 23. If /mode/ is _normal_, then: If there is not exactly one entry 609 in the /headers/ list whose name is "websocket-origin", or if 610 there is not exactly one entry in the /headers/ list whose name 611 is "websocket-location", or if the /protocol/ was specified but 612 there is not exactly one entry in the /headers/ list whose name 613 is "websocket-protocol", or if there are any entries in the 614 /headers/ list whose names are the empty string, then fail the 615 Web Socket connection and abort these steps. Otherwise, handle 616 each entry in the /headers/ list as follows: 618 -> If the entry's name is "websocket-origin" 619 If the value is not exactly equal to /origin/, converted to 620 ASCII lowercase, then fail the Web Socket connection and 621 abort these steps. 623 -> If the entry's name is "websocket-location" 624 If the value is not exactly equal to a string consisting of 625 the following components in the same order, then fail the Web 626 Socket connection and abort these steps: 628 1. The string "ws" if /secure/ is false and "wss" if 629 /secure/ is true 631 2. The three characters "://". 633 3. The value of /host/. 635 4. If /secure/ is false and /port/ is not 81, or if /secure/ 636 is true and /port/ is not 815: a ":" character followed 637 by the value of /port/. 639 5. The value of /resource name/. 641 -> If the entry's name is "websocket-protocol" 642 If there was a /protocol/ specified, and the value is not 643 exactly equal to /protocol/, then fail the Web Socket 644 connection and abort these steps. (If no /protocol/ was 645 specified, the header is ignored.) 647 -> If the entry's name is "set-cookie" or "set-cookie2" or 648 another cookie-related header name 649 Handle the cookie as defined by the appropriate spec, with 650 the resource being the one with the host /host/, the port 651 /port/, the path (and possibly query parameters) /resource 652 name/, and the scheme |http| if /secure/ is false and |https| 653 if /secure/ is true. [RFC2109] [RFC2965] 655 -> Any other name 656 Ignore it. 658 If /mode/ is _redirect_, then: If there is not exactly one entry 659 in the /headers/ list whose name is "location", then fail the 660 Web Socket connection and abort these steps. Otherwise, handle 661 each entry in the /headers/ list as follows: 663 -> If the entry's name is "location" 665 1. Let /was secure/ have the value of /secure/. 667 2. Parse a Web Socket URL's components from the /url/ 668 argument, to obtain new values for /host/, /port/, 669 /resource name/, and /secure/. If this fails, fail the 670 Web Socket connection and abort these steps. 672 3. If /was secure/ is true but /secure/ is now false, fail 673 the Web Socket connection and abort these steps. 675 4. If /port/ is a port to which the user agent is configured 676 to block access, then fail the Web Socket connection and 677 abort these steps. (User agents typically block access 678 to well-known ports like SMTP.) 680 5. Close the connection if the server has not already done 681 so. 683 6. Jump back to the first step of the overall algorithm (the 684 very top of the handshake). 686 -> Any other name 687 Ignore it. 689 If /mode/ is _authenticate_, then: If there is not exactly one 690 entry in the /headers/ list whose name is "www-authenticate", 691 then fail the Web Socket connection and abort these steps. 692 Otherwise, handle each entry in the /headers/ list as follows: 694 -> If the entry's name is "www-authenticate" 695 Obtain credentials in a manner consistent with the 696 requirements for handling the |WWW-Authenticate| header in 697 HTTP, and then close the connection (if the server has not 698 already done so) and jump back to the step labeled _connect_, 699 including the relevant authentication headers in the new 700 request. [RFC2616] 702 -> Any other name 703 Ignore it. 705 24. The *Web Socket connection is established*. Now the user agent 706 must send and receive to and from the connection as described in 707 the next section. 709 4.2. Data framing 711 Once a Web Socket connection is established, the user agent must run 712 through the following state machine for the bytes sent by the server. 714 1. Try to read a byte from the server. Let /frame type/ be that 715 byte. 717 If no byte could be read because the Web Socket connection is 718 closed, then abort. 720 2. Handle the /frame type/ byte as follows: 722 If the high-order bit of the /frame type/ byte is set (i.e. if 723 /frame type/ _and_ed with 0x80 returns 0x80) 724 Run these steps. If at any point during these steps a read is 725 attempted but fails because the Web Socket connection is 726 closed, then abort. 728 1. Let /length/ be zero. 730 2. _Length_: Read a byte, let /b/ be that byte. 732 3. Let /b_v/ be integer corresponding to the low 7 bits of 733 /b/ (the value you would get by _and_ing /b/ with 0x7f). 735 4. Multiply /length/ by 128, add /b_v/ to that result, and 736 store the final result in /length/. 738 5. If the high-order bit of /b/ is set (i.e. if /b/ _and_ed 739 with 0x80 returns 0x80), then return to the step above 740 labeled _length_. 742 6. Read /length/ bytes. 744 7. Discard the read bytes. 746 If the high-order bit of the /frame type/ byte is _not_ set (i.e. 747 if /frame type/ _and_ed with 0x80 returns 0x00) 748 Run these steps. If at any point during these steps a read is 749 attempted but fails because the Web Socket connection is 750 closed, then abort. 752 1. Let /raw data/ be an empty byte array. 754 2. _Data_: Read a byte, let /b/ be that byte. If the client 755 runs out of resources for buffering the incoming data, or 756 hits an artificial resource limit intended to avoid 757 resource starvation, then it must fail the Web Socket 758 connection and abort these steps. 760 3. If /b/ is not 0xff, then append /b/ to /raw data/ and 761 return to the previous step (labeled _data_). 763 4. Interpret /raw data/ as a UTF-8 string, and store that 764 string in /data/. 766 5. If /frame type/ is 0x00, then *a message has been 767 received* with text /data/. Otherwise, discard the data. 769 3. Return to the first step to read the next byte. 771 If the user agent is faced with content that is too large to be 772 handled appropriately, then it must fail the Web Socket connection. 774 Once a Web Socket connection is established, the user agent must use 775 the following steps to *send /data/ using the Web Socket*: 777 1. Send a 0x00 byte to the server. 779 2. Encode /data/ using UTF-8 and send the resulting byte stream to 780 the server. 782 3. Send a 0xff byte to the server. 784 If at any point there is a fatal problem with sending data to the 785 server, the user agent must fail the Web Socket connection. 787 4.3. Closing the connection 789 To *fail the Web Socket connection*, the user agent must close the 790 Web Socket connection, and may report the problem to the user (which 791 would be especially useful for developers). However, user agents 792 must not convey the failure information to the script that attempted 793 the connection in a way distinguishable from the Web Socket being 794 closed normally. 796 Except as indicated above or as specified by the application layer 797 (e.g. a script using the Web Socket API), user agents should not 798 close the connection. 800 4.4. Handling errors in UTF-8 802 When a client is to interpret a byte stream as UTF-8 but finds that 803 the byte stream is not in fact a valid UTF-8 stream, then any bytes 804 or sequences of bytes that are not valid UTF-8 sequences must be 805 interpreted as a U+FFFD REPLACEMENT CHARACTER. 807 5. Server-side requirements 809 _This section only applies to servers._ 811 5.1. Minimal handshake 813 NOTE: This section describes the minimal requirements for a server- 814 side implementation of Web Sockets. 816 Listen on a port for TCP/IP. Upon receiving a connection request, 817 open a connection and send the following bytes back to the client: 819 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 820 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 821 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 822 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 823 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 824 61 64 65 0d 0a 826 Send the string "WebSocket-Origin" followed by a U+003A COLON (":") 827 followed by the ASCII serialization of the origin from which the 828 server is willing to accept connections, followed by a CRLF pair 829 (0x0d 0x0a). 831 For instance: 833 WebSocket-Origin: http://example.com 835 Send the string "WebSocket-Location" followed by a U+003A COLON (":") 836 followed by the URL of the Web Socket script, followed by a CRLF pair 837 (0x0d 0x0a). 839 For instance: 841 WebSocket-Location: ws://example.com:80/demo 843 Send another CRLF pair (0x0d 0x0a). 845 Read data from the client until four bytes 0x0d 0x0a 0x0d 0x0a are 846 read. This data must either be discarded or handled as described in 847 the following section describing the handshake details. 849 If the connection isn't dropped at this point, go to the data framing 850 section. 852 5.2. Handshake details 854 The previous section ignores the data that is transmitted by the 855 client during the handshake. 857 The data sent by the client consists of a number of fields separated 858 by CR LF pairs (bytes 0x0d 0x0a). 860 The first field consists of three tokens separated by space 861 characters (byte 0x20). The middle token is the path being opened. 862 If the server supports multiple paths, then the server should echo 863 the value of this field in the initial handshake, as part of the URL 864 given on the |WebSocket-Location| line (after the appropriate scheme 865 and host). 867 If the first field does not have three tokens, the server should 868 abort the connection as it probably represents an errorneous client. 870 The remaining fields consist of name-value pairs, with the name part 871 separated from the value part by a colon and a space (bytes 0x3a 872 0x20). Of these, several are interesting: 874 Host (bytes 48 6f 73 74) 875 The value gives the hostname that the client intended to use when 876 opening the Web Socket. It would be of interest in particular to 877 virtual hosting environments, where one server might serve 878 multiple hosts, and might therefore want to return different data. 880 The right host has to be output as part of the URL given on the 881 |WebSocket-Location| line of the handshake described above, to 882 verify that the server knows that it is really representing that 883 host. 885 Origin (bytes 4f 72 69 67 69 6e) 886 The value gives the scheme, hostname, and port (if it's not the 887 default port for the given scheme) of the page that asked the 888 client to open the Web Socket. It would be interesting if the 889 server's operator had deals with operators of other sites, since 890 the server could then decide how to respond (or indeed, _whether_ 891 to respond) based on which site was requesting a connection. 893 If the server supports connections from more than one origin, then 894 the server should echo the value of this field in the initial 895 handshake, on the |WebSocket-Origin| line. 897 Other fields 898 Other fields can be used, such as "Cookie" or "Authorization", for 899 authentication purposes. 901 Any fields that lack the colon-space separator should be discarded 902 and may cause the server to disconnect. 904 5.3. Data framing 906 NOTE: This section only describes how to handle content that this 907 specification allows user agents to send (text). It doesn't handle 908 any arbitrary content in the same way that the requirements on user 909 agents defined earlier handle any content including possible future 910 extensions to the protocols. 912 The server must run through the following steps to process the bytes 913 sent by the client: 915 1. Read a byte from the client. Assuming everything is going 916 according to plan, it will be a 0x00 byte. If the byte is not a 917 0x00 byte, then the server may disconnect. 919 2. Let /raw data/ be an empty byte array. 921 3. _Data_: Read a byte, let /b/ be that byte. 923 4. If /b/ is not 0xff, then append /b/ to /raw data/ and return to 924 the previous step (labeled _data_). 926 5. Interpret /raw data/ as a UTF-8 string, and apply whatever 927 server-specific processing is to occur for the resulting string. 929 6. Return to the first step to read the next byte. 931 The server must run through the following steps to send strings to 932 the client: 934 1. Send a 0x00 byte to the client to indicate the start of a string. 936 2. Encode /data/ using UTF-8 and send the resulting byte stream to 937 the client. 939 3. Send a 0xff byte to the client to indicate the end of the 940 message. 942 6. Closing the connection 944 To *close the Web Socket connection*, either the user agent or the 945 server closes the TCP/IP connection. There is no closing handshake. 946 Whether the user agent or the server closes the connection, it is 947 said that the *Web Socket connection is closed*. 949 Servers may close the Web Socket connection whenever desired. 951 User agents should not close the Web Socket connection arbitrarily. 953 7. Security considerations 955 While this protocol is intended to be used by scripts in Web pages, 956 it can also be used directly by hosts. Such hosts are acting on 957 their own behalf, and can therefore send fake "Origin" headers, 958 misleading the server. Servers should therefore be careful about 959 assuming that they are talking directly to scripts from known 960 origins, and must consider that they might be accessed in unexpected 961 ways. In particular, a server should not trust that any input is 962 valid. 964 EXAMPLE: For example, if the server uses input as part of SQL 965 queries, all input text should be escaped before being passed to the 966 SQL server, lest the server be susceptible to SQL injection. 968 Servers that are not intended to process input from any Web page but 969 only for certain sites should verify the "Origin" header is an origin 970 they expect, and should only respond with the corresponding 971 "WebSocket-Origin" if it is an accepted origin. Servers that only 972 accept input from one origin can just send back that value in the 973 "WebSocket-Origin" header, without bothering to check the client's 974 value. 976 If at any time a server is faced with data that it does not 977 understand, or that violates some criteria by which the server 978 determines safety of input, or when the server sees a handshake that 979 does not correspond to the values the server is expecting (e.g. 980 incorrect path or origin), the server should just disconnect. It is 981 always safe to disconnect. 983 8. IANA considerations 985 8.1. Registration of ws: scheme 987 A |ws:| URL identifies a Web Socket server and resource name. 989 URI scheme name. 990 ws 992 Status. 993 Permanent. 995 URI scheme syntax. 996 In ABNF terms using the terminals from the IRI specifications: 997 [RFC5238] [RFC3987] 999 "ws" ":" ihier-part [ "?" iquery ] 1001 URI scheme semantics. 1002 The only operation for this scheme is to open a connection using 1003 the Web Socket protocol. 1005 Encoding considerations. 1006 UTF-8 only. 1008 Applications/protocols that use this URI scheme name. 1009 Web Socket protocol. 1011 Interoperability considerations. 1012 None. 1014 Security considerations. 1015 See "Security considerations" section above. 1017 Contact. 1018 Ian Hickson 1020 Author/Change controller. 1021 Ian Hickson 1023 References. 1024 This document. 1026 8.2. Registration of wss: scheme 1028 A |wss:| URL identifies a Web Socket server and resource name, and 1029 indicates that traffic over that connection is to be encrypted. 1031 URI scheme name. 1032 wss 1034 Status. 1035 Permanent. 1037 URI scheme syntax. 1038 In ABNF terms using the terminals from the IRI specifications: 1039 [RFC5238] [RFC3987] 1041 "ws" ":" ihier-part [ "?" iquery ] 1043 URI scheme semantics. 1044 The only operation for this scheme is to open a connection using 1045 the Web Socket protocol, encrypted using TLS. 1047 Encoding considerations. 1048 UTF-8 only. 1050 Applications/protocols that use this URI scheme name. 1051 Web Socket protocol over TLS. 1053 Interoperability considerations. 1054 None. 1056 Security considerations. 1057 See "Security considerations" section above. 1059 Contact. 1060 Ian Hickson 1062 Author/Change controller. 1063 Ian Hickson 1065 References. 1066 This document. 1068 8.3. Registration of ports 81 and 815 1070 See IANA ticket #257454 for port 81 and IANA ticket #257455 for port 1071 815. 1073 8.4. Registration of the "WebSocket" HTTP Upgrade keyword 1075 Name of token. 1076 WebSocket 1078 Author/Change controller. 1079 Ian Hickson 1081 Contact. 1082 Ian Hickson 1084 References. 1085 This document. 1087 9. Normative References 1089 [HTML5] Hickson, I., "HTML5", August 2009. 1091 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 1092 Mechanism", RFC 2109, February 1997. 1094 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1095 Requirement Levels", BCP 14, RFC 2119, March 1997. 1097 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1098 RFC 2246, January 1999. 1100 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1101 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1102 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1104 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 1105 Mechanism", RFC 2965, October 2000. 1107 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1108 Identifiers (IRIs)", RFC 3987, January 2005. 1110 [RFC5238] Phelan, T., "Datagram Transport Layer Security (DTLS) over 1111 the Datagram Congestion Control Protocol (DCCP)", 1112 RFC 5238, May 2008. 1114 [WEBADDRESSES] 1115 Connolly, D. and C. Sperberg-McQueen, "Web addresses in 1116 HTML 5", May 2009. 1118 Author's Address 1120 Ian Hickson 1121 Google, Inc. 1123 Email: ian@hixie.ch 1124 URI: http://ln.hixie.ch/