idnits 2.17.1 draft-hixie-thewebsocketprotocol-31.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 7, 2009) is 5373 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) Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 2 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 7, 2009 5 Expires: February 8, 2010 7 The Web Socket protocol 8 draft-hixie-thewebsocketprotocol-31 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 8, 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 3. Client-side requirements . . . . . . . . . . . . . . . . . . . 8 70 3.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 8 71 3.2. Data framing . . . . . . . . . . . . . . . . . . . . . . . 17 72 3.3. Closing the connection . . . . . . . . . . . . . . . . . . 18 73 3.4. Handling errors in UTF-8 . . . . . . . . . . . . . . . . . 19 74 4. Server-side requirements . . . . . . . . . . . . . . . . . . . 20 75 4.1. Minimal handshake . . . . . . . . . . . . . . . . . . . . 20 76 4.2. Handshake details . . . . . . . . . . . . . . . . . . . . 21 77 4.3. Data framing . . . . . . . . . . . . . . . . . . . . . . . 22 78 5. Closing the connection . . . . . . . . . . . . . . . . . . . . 23 79 6. Security considerations . . . . . . . . . . . . . . . . . . . 24 80 7. IANA considerations . . . . . . . . . . . . . . . . . . . . . 25 81 7.1. Registration of ws: scheme . . . . . . . . . . . . . . . . 25 82 7.2. Registration of wss: scheme . . . . . . . . . . . . . . . 25 83 7.3. Registration of ports 81 and 815 . . . . . . . . . . . . . 26 84 7.4. Registration of the "WebSocket" HTTP Upgrade keyword . . . 26 85 8. Normative References . . . . . . . . . . . . . . . . . . . . . 27 86 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28 88 1. Introduction 90 _This section is non-normative._ 92 The Web Socket protocol is designed on the principle that there 93 should be minimal framing (the only framing that exists is to make 94 the protocol frame-based instead of stream-based, and to support a 95 distinction between Unicode text and binary frames). It is expected 96 that metadata would be layered on top of Web Socket by the 97 application layer, in the same way that metadata is layered on top of 98 TCP/IP by the application layer (HTTP). 100 Conceptually, Web Socket is really just a layer on top of TCP/IP that 101 adds a Web "origin"-based security model for browsers; adds an 102 addressing and protocol naming mechanism to support multiple services 103 on one port and multiple host names on one IP address; and layers a 104 framing mechanism on top of TCP to get back to the IP packet 105 mechanism that TCP is built on, but without length limits. Other 106 than that, it adds nothing. Basically it is intended to be as close 107 as possible to just exposing raw TCP/IP to script as possible given 108 the constraints of the Web. It's also designed in such a way that its 109 servers can share a port with HTTP servers, by having its handshake 110 be a valid HTTP Upgrade handshake also. 112 1.1. Security model 114 _This section is non-normative._ 116 The Web Socket protocol uses the origin model used by Web browsers to 117 restrict which Web pages can contact a Web Socket server when the Web 118 Socket protocol is used from a Web page. Naturally, when the Web 119 Socket protocol is used directly (not from a Web page), the origin 120 model is not useful, as the client can provide any arbitrary origin 121 string. 123 1.2. Relationship to TCP/IP and HTTP 125 _This section is non-normative._ 127 The Web Socket protocol is an independent TCP-based protocol. Its 128 only relationship to HTTP is that its handshake is interpreted by 129 HTTP servers as an Upgrade request. 131 The Web Socket protocol by default uses port 81 for regular Web 132 Socket connections and port 815 for Web Socket connections tunneled 133 over TLS. 135 1.3. Establishing a connection 137 _This section is non-normative._ 139 There are several options for establishing a Web Socket connection. 141 The simplest method is to use port 81 to get a direct connection to a 142 Web Socket server. However, this port may be blocked by firewalls. 144 The second simplest method is to use TLS encryption and port 815 to 145 connect directly to a Web Socket server. This is the preferred 146 solution, as it is secure and correct. However, TLS encryption can 147 be computationally expensive, and port 815 might also be blocked by 148 firewalls. 150 To avoid firewalls, ports 80 and 443 might be used instead. These 151 are the HTTP and HTTPS ports. Port 80 traffic, however, will often 152 be intercepted by HTTP proxies, which can lead to the connection 153 failing to be established. 155 Port 443, using encryption, is therefore the most reliable solution. 156 It is unlikely to be blocked by a firewall or intercepted by a proxy. 157 However, again, TLS encryption can be computationally expensive. 159 When a connection is to be made to a port that is shared by an HTTP 160 server (a situation that is quite likely to occur with traffic to 161 ports 80 and 443), the connection will appear to the HTTP server to 162 be a regular GET request with an Upgrade offer. In relatively simple 163 setups with just one IP address and a single server for all traffic 164 to a single hostname, this might allow a practical way for systems 165 based on the Web Socket protocol to be deployed. In more elaborate 166 setups (e.g. with load balancers and multiple servers), a dedicated 167 set of hosts for Web Socket connections separate from the HTTP 168 servers is probably easier to manage. 170 1.4. The Web Socket protocol 172 _This section is non-normative._ 174 The protocol has two parts: a handshake, and then the data transfer. 176 The handshake from the client looks as follows: 178 GET /demo HTTP/1.1 179 Upgrade: WebSocket 180 Connection: Upgrade 181 Host: example.com 182 Origin: http://example.com 183 WebSocket-Protocol: sample 185 The handshake from the server looks as follows: 187 HTTP/1.1 101 Web Socket Protocol Handshake 188 Upgrade: WebSocket 189 Connection: Upgrade 190 WebSocket-Origin: http://example.com 191 WebSocket-Location: ws://example.com/demo 192 WebSocket-Protocol: sample 194 Once the client and server have both sent their handshakes, and if 195 the handshake was successful, then the data transfer part starts. 196 This is a two-way communication channel where each side can, 197 independently from the other, send data at will. 199 Data is sent in the form of UTF-8 text. Each frame of data starts 200 with a 0x00 byte and ends with a 0xFF byte, with the UTF-8 text in 201 between. 203 2. Conformance requirements 205 All diagrams, examples, and notes in this specification are non- 206 normative, as are all sections explicitly marked non-normative. 207 Everything else in this specification is normative. 209 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 210 "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this 211 document are to be interpreted as described in RFC2119. For 212 readability, these words do not appear in all uppercase letters in 213 this specification. [RFC2119] 215 Requirements phrased in the imperative as part of algorithms (such as 216 "strip any leading space characters" or "return false and abort these 217 steps") are to be interpreted with the meaning of the key word 218 ("must", "should", "may", etc) used in introducing the algorithm. 220 Conformance requirements phrased as algorithms or specific steps may 221 be implemented in any manner, so long as the end result is 222 equivalent. (In particular, the algorithms defined in this 223 specification are intended to be easy to follow, and not intended to 224 be performant.) 226 Implementations may impose implementation-specific limits on 227 otherwise unconstrained inputs, e.g. to prevent denial of service 228 attacks, to guard against running out of memory, or to work around 229 platform-specific limitations. 231 The conformance classes defined by this specification are user agents 232 and servers. 234 3. Client-side requirements 236 _This section only applies to user agents, not to servers._ 238 NOTE: This specification doesn't currently define a limit to the 239 number of simultaneous connections that a client can establish to a 240 server. 242 3.1. Handshake 244 When the user agent is to *establish a Web Socket connection* to a 245 host /host/, optionally on port /port/, from an origin /origin/, with 246 a flag /secure/, with a particular /resource name/, and optionally 247 with a particular /protocol/, it must run the following steps. 249 NOTE: The /host/ and /origin/ strings will be all-lowercase when this 250 algorithm is invoked. 252 1. If there is no explicit /port/, then: if /secure/ is false, let 253 /port/ be 81, otherwise let /port/ be 815. 255 2. If the user agent already has a Web Socket connection to the 256 remote host (IP address) identified by /host/, even if known by 257 another name, wait until that connection has been established or 258 for that connection to have failed. 260 NOTE: This makes it harder for a script to perform a denial of 261 service attack by just opening a large number of Web Socket 262 connections to a remote host. 264 NOTE: There is no limit to the number of established Web Socket 265 connections a user agent can have with a single remote host. 266 Servers can refuse to connect users with an excessive number of 267 connections, or disconnect resource-hogging users when suffering 268 high load. 270 3. _Connect_: If the user agent is configured to use a proxy when 271 using the Web Socket protocol to connect to host /host/ and/or 272 port /port/, then connect to that proxy and ask it to open a 273 TCP/IP connection to the host given by /host/ and the port given 274 by /port/. 276 EXAMPLE: For example, if the user agent uses an HTTP proxy 277 for all traffic, then if it was to try to connect to port 80 278 on server example.com, it might send the following lines to 279 the proxy server: 281 CONNECT example.com:80 HTTP/1.1 282 Host: example.com 284 If there was a password, the connection might look like: 286 CONNECT example.com:80 HTTP/1.1 287 Host: example.com 288 Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE= 290 Otherwise, if the user agent is not configured to use a proxy, 291 then open a TCP/IP connection to the host given by /host/ and 292 the port given by /port/. 294 NOTE: Implementations that do not expose explicit UI for 295 selecting a proxy for Web Socket connections separate from other 296 proxies are encouraged to use a SOCKS proxy for Web Socket 297 connections, if available, or failing that, to prefer the proxy 298 configured for HTTPS connections over the proxy configured for 299 HTTP connections. 301 4. If the connection could not be opened, then fail the Web Socket 302 connection and abort these steps. 304 5. If /secure/ is true, perform a TLS handshake over the 305 connection. If this fails (e.g. the server's certificate could 306 not be verified), then fail the Web Socket connection and abort 307 these steps. Otherwise, all further communication on this 308 channel must run through the encrypted tunnel. [RFC2246] 310 6. Send the following bytes to the remote side (the server): 312 47 45 54 20 314 Send the /resource name/ value, encoded as US-ASCII. 316 Send the following bytes: 318 20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61 319 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43 320 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61 321 64 65 0d 0a 323 NOTE: The string "GET ", the path, " HTTP/1.1", CRLF, the string 324 "Upgrade: WebSocket", CRLF, and the string "Connection: 325 Upgrade", CRLF. 327 7. Send the following bytes: 329 48 6f 73 74 3a 20 331 Send the /host/ value, encoded as US-ASCII. 333 Send the following bytes: 335 0d 0a 337 NOTE: The string "Host: ", the host, and CRLF. 339 8. Send the following bytes: 341 4f 72 69 67 69 6e 3a 20 343 Send the /origin/ value, encoded as US-ASCII. 345 NOTE: The /origin/ value is a string that was passed to this 346 algorithm. 348 Send the following bytes: 350 0d 0a 352 NOTE: The string "Origin: ", the origin, and CRLF. 354 9. If there is no /protocol/, then skip this step. 356 Otherwise, send the following bytes: 358 57 65 62 53 6f 63 6b 65 74 2d 50 72 6f 74 6f 63 359 6f 6c 3a 20 361 Send the /protocol/ value, encoded as US-ASCII. 363 Send the following bytes: 365 0d 0a 367 NOTE: The string "WebSocket-Protocol: ", the protocol, and CRLF. 369 10. If the client has any authentication information or cookies that 370 would be relevant to a resource accessed over HTTP, if /secure/ 371 is false, or HTTPS, if it is true, on host /host/, port /port/, 372 with /resource name/ as the path (and possibly query 373 parameters), then HTTP headers that would be appropriate for 374 that information should be sent at this point. [RFC2616] 375 [RFC2109] [RFC2965] 376 Each header must be on a line of its own (each ending with a CR 377 LF sequence). For the purposes of this step, each header must 378 not be split into multiple lines (despite HTTP otherwise 379 allowing this with continuation lines). 381 EXAMPLE: For example, if the server had a username and 382 password that applied to |http://example.com/socket|, and the 383 Web Socket was being opened to |ws://example.com:80/socket|, 384 it could send them: 386 Authorization: Basic d2FsbGU6ZXZl 388 However, it would not send them if the Web Socket was being 389 opened to |ws://example.com/socket|, as that uses a different 390 port (81, not 80). 392 11. Send the following bytes: 394 0d 0a 396 NOTE: Just a CRLF (a blank line). 398 12. Read bytes from the server until either the connection closes, 399 or a 0x0a byte is read. Let /header/ be these bytes, including 400 the 0x0a byte. 402 If /header/ is not at least two bytes long, or if the last two 403 bytes aren't 0x0d and 0x0a respectively, then fail the Web 404 Socket connection and abort these steps. 406 User agents may apply a timeout to this step, failing the Web 407 Socket connection if the server does not send back data in a 408 suitable time period. 410 13. If /header/ consists of 44 bytes that exactly match the 411 following, then let /mode/ be _normal_. 413 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 414 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 415 20 48 61 6e 64 73 68 61 6b 65 0d 0a 417 NOTE: The string "HTTP/1.1 101 Web Socket Protocol Handshake" 418 followed by a CRLF pair. 420 Otherwise, let /code/ be the substring of /header/ that starts 421 from the byte after the first 0x20 byte, and ends with the byte 422 before the second 0x20 byte. If there are not at least two 0x20 423 bytes in /header/, then fail the Web Socket connection and abort 424 these steps. 426 If /code/, interpreted as ASCII, is either "301", "302", "303", 427 "307", then let /mode/ be _redirect_. 429 If /code/, interpreted as ASCII, is "401", then let /mode/ be 430 _authenticate_. 432 Otherwise, fail the Web Socket connection and abort these steps. 434 14. If /mode/ is _normal_, then read 41 bytes from the server. 436 If the connection closes before 41 bytes are received, or if the 437 41 bytes aren't exactly equal to the following bytes, then fail 438 the Web Socket connection and abort these steps. 440 55 70 67 72 61 64 65 3a 20 57 65 62 53 6f 63 6b 441 65 74 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 442 55 70 67 72 61 64 65 0d 0a 444 NOTE: The string "Upgrade: WebSocket", CRLF, the string 445 "Connection: Upgrade", CRLF. 447 User agents may apply a timeout to this step, failing the Web 448 Socket connection if the server does not respond with the above 449 bytes within a suitable time period. 451 NOTE: This step is skipped if /mode/ is _redirect_ or 452 _authenticate_. 454 15. Let /headers/ be a list of name-value pairs, initially empty. 456 16. _Header_: Let /name/ and /value/ be empty byte arrays. 458 17. Read a byte from the server. 460 If the connection closes before this byte is received, then fail 461 the Web Socket connection and abort these steps. 463 Otherwise, handle the byte as described in the appropriate entry 464 below: 466 -> If the byte is 0x0d (ASCII CR) 467 If the /name/ byte array is empty, then jump to the headers 468 processing step. Otherwise, fail the Web Socket connection 469 and abort these steps. 471 -> If the byte is 0x0a (ASCII LF) 472 Fail the Web Socket connection and abort these steps. 474 -> If the byte is 0x3a (ASCII ":") 475 Move on to the next step. 477 -> If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z") 478 Append a byte whose value is the byte's value plus 0x20 to 479 the /name/ byte array and redo this step for the next byte. 481 -> Otherwise 482 Append the byte to the /name/ byte array and redo this step 483 for the next byte. 485 NOTE: This reads a header name, terminated by a colon, 486 converting upper-case ASCII letters to lowercase, and aborting 487 if a stray CR or LF is found. 489 18. Read a byte from the server. 491 If the connection closes before this byte is received, then fail 492 the Web Socket connection and abort these steps. 494 Otherwise, handle the byte as described in the appropriate entry 495 below: 497 -> If the byte is 0x20 (ASCII space) 498 Ignore the byte and move on to the next step. 500 -> Otherwise 501 Treat the byte as described by the list in the next step, 502 then move on to that next step for real. 504 NOTE: This skips past a space character after the colon, if 505 necessary. 507 19. Read a byte from the server. 509 If the connection closes before this byte is received, then fail 510 the Web Socket connection and abort these steps. 512 Otherwise, handle the byte as described in the appropriate entry 513 below: 515 -> If the byte is 0x0d (ASCII CR) 516 Move on to the next step. 518 -> If the byte is 0x0a (ASCII LF) 519 Fail the Web Socket connection and abort these steps. 521 -> Otherwise 522 Append the byte to the /value/ byte array and redo this step 523 for the next byte. 525 NOTE: This reads a header value, terminated by a CRLF. 527 20. Read a byte from the server. 529 If the connection closes before this byte is received, or if the 530 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 531 connection and abort these steps. 533 NOTE: This skips past the LF byte of the CRLF after the header. 535 21. Append an entry to the /headers/ list that has the name given by 536 the string obtained by interpreting the /name/ byte array as a 537 UTF-8 byte stream and the value given by the string obtained by 538 interpreting the /value/ byte array as a UTF-8 byte stream. 540 22. Return to the "Header" step above. 542 23. _Headers processing_: Read a byte from the server. 544 If the connection closes before this byte is received, or if the 545 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 546 connection and abort these steps. 548 NOTE: This skips past the LF byte of the CRLF after the blank 549 line after the headers. 551 24. If /mode/ is _normal_, then: If there is not exactly one entry 552 in the /headers/ list whose name is "websocket-origin", or if 553 there is not exactly one entry in the /headers/ list whose name 554 is "websocket-location", or if the /protocol/ was specified but 555 there is not exactly one entry in the /headers/ list whose name 556 is "websocket-protocol", or if there are any entries in the 557 /headers/ list whose names are the empty string, then fail the 558 Web Socket connection and abort these steps. Otherwise, handle 559 each entry in the /headers/ list as follows: 561 -> If the entry's name is "websocket-origin" 562 If the value is not exactly equal to /origin/, converted to 563 ASCII lowercase, then fail the Web Socket connection and 564 abort these steps. 566 -> If the entry's name is "websocket-location" 567 If the value is not exactly equal to a string consisting of 568 the following components in the same order, then fail the Web 569 Socket connection and abort these steps: 571 1. The string "ws" if /secure/ is false and "wss" if 572 /secure/ is true 574 2. The three characters "://". 576 3. The value of /host/. 578 4. If /secure/ is false and /port/ is not 81, or if /secure/ 579 is true and /port/ is not 815: a ":" character followed 580 by the value of /port/. 582 5. The value of /resource name/. 584 -> If the entry's name is "websocket-protocol" 585 If there was a /protocol/ specified, and the value is not 586 exactly equal to /protocol/, then fail the Web Socket 587 connection and abort these steps. (If no /protocol/ was 588 specified, the header is ignored.) 590 -> If the entry's name is "set-cookie" or "set-cookie2" or 591 another cookie-related header name 592 Handle the cookie as defined by the appropriate spec, with 593 the resource being the one with the host /host/, the port 594 /port/, the path (and possibly query parameters) /resource 595 name/, and the scheme |http| if /secure/ is false and |https| 596 if /secure/ is true. [RFC2109] [RFC2965] 598 -> Any other name 599 Ignore it. 601 If /mode/ is _redirect_, then: If there is not exactly one entry 602 in the /headers/ list whose name is "location", then fail the 603 Web Socket connection and abort these steps. Otherwise, handle 604 each entry in the /headers/ list as follows: 606 -> If the entry's name is "location" 607 Parse the value of the entry. If this fails, or if the 608 parsed URL does not have a component whose value is 609 either "ws" or "wss", when compared in an ASCII case- 610 insensitive manner, then fail the Web Socket connection and 611 abort these steps. 613 If /secure/ is true but the newly parsed URL's 614 component is an ASCII case-insensitive match for "ws", then 615 fail the Web Socket connection and abort these steps. 616 Otherwise, if /secure/ is false but the newly parsed URL's 617 component is an ASCII case-insensitive match for 618 "wss", then set /secure/ to true. 620 Let /host/ be the value of the component of /url/, 621 converted to ASCII lowercase. 623 If /url/ has a component, then let /port/ be that 624 component's value; otherwise, there is no explicit /port/. 626 If there is an explicit /port/ and the user agent is 627 configured to block access to that port, then fail the Web 628 Socket connection and abort these steps. 630 Let /resource name/ be the value of the component 631 (which might be empty) of /url/. 633 If /resource name/ is the empty string, set it to a single 634 character U+002F SOLIDUS (/). 636 If /url/ has a component, then append a single U+003F 637 QUESTION MARK (?) character to /resource name/, followed by 638 the value of the component. 640 Close the connection if the server has not already done so. 642 Jump back to the first step of this algorithm. 644 -> Any other name 645 Ignore it. 647 If /mode/ is _authenticate_, then: If there is not exactly one 648 entry in the /headers/ list whose name is "www-authenticate", 649 then fail the Web Socket connection and abort these steps. 650 Otherwise, handle each entry in the /headers/ list as follows: 652 -> If the entry's name is "www-authenticate" 653 Obtain credentials in a manner consistent with the 654 requirements for handling the |WWW-Authenticate| header in 655 HTTP, and then close the connection (if the server has not 656 already done so) and jump back to the step labeled _connect_, 657 including the relevant authentication headers in the new 658 request. [RFC2616] 660 -> Any other name 661 Ignore it. 663 25. The *Web Socket connection is established*. Now the user agent 664 must send and receive to and from the connection as described in 665 the next section. 667 3.2. Data framing 669 Once a Web Socket connection is established, the user agent must run 670 through the following state machine for the bytes sent by the server. 672 1. Try to read a byte from the server. Let /frame type/ be that 673 byte. 675 If no byte could be read because the Web Socket connection is 676 closed, then abort. 678 2. Handle the /frame type/ byte as follows: 680 If the high-order bit of the /frame type/ byte is set (i.e. if 681 /frame type/ _and_ed with 0x80 returns 0x80) 682 Run these steps. If at any point during these steps a read is 683 attempted but fails because the Web Socket connection is 684 closed, then abort. 686 1. Let /length/ be zero. 688 2. _Length_: Read a byte, let /b/ be that byte. 690 3. Let /b_v/ be integer corresponding to the low 7 bits of 691 /b/ (the value you would get by _and_ing /b/ with 0x7f). 693 4. Multiply /length/ by 128, add /b_v/ to that result, and 694 store the final result in /length/. 696 5. If the high-order bit of /b/ is set (i.e. if /b/ _and_ed 697 with 0x80 returns 0x80), then return to the step above 698 labeled _length_. 700 6. Read /length/ bytes. 702 7. Discard the read bytes. 704 If the high-order bit of the /frame type/ byte is _not_ set (i.e. 705 if /frame type/ _and_ed with 0x80 returns 0x00) 706 Run these steps. If at any point during these steps a read is 707 attempted but fails because the Web Socket connection is 708 closed, then abort. 710 1. Let /raw data/ be an empty byte array. 712 2. _Data_: Read a byte, let /b/ be that byte. If the client 713 runs out of resources for buffering the incoming data, or 714 hits an artificial resource limit intended to avoid 715 resource starvation, then it must fail the Web Socket 716 connection and abort these steps. 718 3. If /b/ is not 0xff, then append /b/ to /raw data/ and 719 return to the previous step (labeled _data_). 721 4. Interpret /raw data/ as a UTF-8 string, and store that 722 string in /data/. 724 5. If /frame type/ is 0x00, then *a message has been 725 received* with text /data/. Otherwise, discard the data. 727 3. Return to the first step to read the next byte. 729 If the user agent is faced with content that is too large to be 730 handled appropriately, then it must fail the Web Socket connection. 732 Once a Web Socket connection is established, the user agent must use 733 the following steps to *send /data/ using the Web Socket*: 735 1. Send a 0x00 byte to the server. 737 2. Encode /data/ using UTF-8 and send the resulting byte stream to 738 the server. 740 3. Send a 0xff byte to the server. 742 If at any point there is a fatal problem with sending data to the 743 server, the user agent must fail the Web Socket connection. 745 3.3. Closing the connection 747 To *fail the Web Socket connection*, the user agent must close the 748 Web Socket connection, and may report the problem to the user (which 749 would be especially useful for developers). However, user agents 750 must not convey the failure information to the script that attempted 751 the connection in a way distinguishable from the Web Socket being 752 closed normally. 754 Except as indicated above or as specified by the application layer 755 (e.g. a script using the Web Socket API), user agents should not 756 close the connection. 758 3.4. Handling errors in UTF-8 760 When a client is to interpret a byte stream as UTF-8 but finds that 761 the byte stream is not in fact a valid UTF-8 stream, then any bytes 762 or sequences of bytes that are not valid UTF-8 sequences must be 763 interpreted as a U+FFFD REPLACEMENT CHARACTER. 765 4. Server-side requirements 767 _This section only applies to servers._ 769 4.1. Minimal handshake 771 NOTE: This section describes the minimal requirements for a server- 772 side implementation of Web Sockets. 774 Listen on a port for TCP/IP. Upon receiving a connection request, 775 open a connection and send the following bytes back to the client: 777 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 778 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 779 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 780 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 781 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 782 61 64 65 0d 0a 784 Send the string "WebSocket-Origin" followed by a U+003A COLON (":") 785 followed by the ASCII serialization of the origin from which the 786 server is willing to accept connections, followed by a CRLF pair 787 (0x0d 0x0a). 789 For instance: 791 WebSocket-Origin: http://example.com 793 Send the string "WebSocket-Location" followed by a U+003A COLON (":") 794 followed by the URL of the Web Socket script, followed by a CRLF pair 795 (0x0d 0x0a). 797 For instance: 799 WebSocket-Location: ws://example.com:80/demo 801 Send another CRLF pair (0x0d 0x0a). 803 Read data from the client until four bytes 0x0d 0x0a 0x0d 0x0a are 804 read. This data must either be discarded or handled as described in 805 the following section describing the handshake details. 807 If the connection isn't dropped at this point, go to the data framing 808 section. 810 4.2. Handshake details 812 The previous section ignores the data that is transmitted by the 813 client during the handshake. 815 The data sent by the client consists of a number of fields separated 816 by CR LF pairs (bytes 0x0d 0x0a). 818 The first field consists of three tokens separated by space 819 characters (byte 0x20). The middle token is the path being opened. 820 If the server supports multiple paths, then the server should echo 821 the value of this field in the initial handshake, as part of the URL 822 given on the |WebSocket-Location| line (after the appropriate scheme 823 and host). 825 If the first field does not have three tokens, the server should 826 abort the connection as it probably represents an errorneous client. 828 The remaining fields consist of name-value pairs, with the name part 829 separated from the value part by a colon and a space (bytes 0x3a 830 0x20). Of these, several are interesting: 832 Host (bytes 48 6f 73 74) 833 The value gives the hostname that the client intended to use when 834 opening the Web Socket. It would be of interest in particular to 835 virtual hosting environments, where one server might serve 836 multiple hosts, and might therefore want to return different data. 838 The right host has to be output as part of the URL given on the 839 |WebSocket-Location| line of the handshake described above, to 840 verify that the server knows that it is really representing that 841 host. 843 Origin (bytes 4f 72 69 67 69 6e) 844 The value gives the scheme, hostname, and port (if it's not the 845 default port for the given scheme) of the page that asked the 846 client to open the Web Socket. It would be interesting if the 847 server's operator had deals with operators of other sites, since 848 the server could then decide how to respond (or indeed, _whether_ 849 to respond) based on which site was requesting a connection. 851 If the server supports connections from more than one origin, then 852 the server should echo the value of this field in the initial 853 handshake, on the |WebSocket-Origin| line. 855 Other fields 856 Other fields can be used, such as "Cookie" or "Authorization", for 857 authentication purposes. 859 Any fields that lack the colon-space separator should be discarded 860 and may cause the server to disconnect. 862 4.3. Data framing 864 NOTE: This section only describes how to handle content that this 865 specification allows user agents to send (text). It doesn't handle 866 any arbitrary content in the same way that the requirements on user 867 agents defined earlier handle any content including possible future 868 extensions to the protocols. 870 The server must run through the following steps to process the bytes 871 sent by the client: 873 1. Read a byte from the client. Assuming everything is going 874 according to plan, it will be a 0x00 byte. If the byte is not a 875 0x00 byte, then the server may disconnect. 877 2. Let /raw data/ be an empty byte array. 879 3. _Data_: Read a byte, let /b/ be that byte. 881 4. If /b/ is not 0xff, then append /b/ to /raw data/ and return to 882 the previous step (labeled _data_). 884 5. Interpret /raw data/ as a UTF-8 string, and apply whatever 885 server-specific processing is to occur for the resulting string. 887 6. Return to the first step to read the next byte. 889 The server must run through the following steps to send strings to 890 the client: 892 1. Send a 0x00 byte to the client to indicate the start of a string. 894 2. Encode /data/ using UTF-8 and send the resulting byte stream to 895 the client. 897 3. Send a 0xff byte to the client to indicate the end of the 898 message. 900 5. Closing the connection 902 To *close the Web Socket connection*, either the user agent or the 903 server closes the TCP/IP connection. There is no closing handshake. 904 Whether the user agent or the server closes the connection, it is 905 said that the *Web Socket connection is closed*. 907 Servers may close the Web Socket connection whenever desired. 909 User agents should not close the Web Socket connection arbitrarily. 911 6. Security considerations 913 While this protocol is intended to be used by scripts in Web pages, 914 it can also be used directly by hosts. Such hosts are acting on 915 their own behalf, and can therefore send fake "Origin" headers, 916 misleading the server. Servers should therefore be careful about 917 assuming that they are talking directly to scripts from known 918 origins, and must consider that they might be accessed in unexpected 919 ways. In particular, a server should not trust that any input is 920 valid. 922 EXAMPLE: For example, if the server uses input as part of SQL 923 queries, all input text should be escaped before being passed to the 924 SQL server, lest the server be susceptible to SQL injection. 926 Servers that are not intended to process input from any Web page but 927 only for certain sites should verify the "Origin" header is an origin 928 they expect, and should only respond with the corresponding 929 "WebSocket-Origin" if it is an accepted origin. Servers that only 930 accept input from one origin can just send back that value in the 931 "WebSocket-Origin" header, without bothering to check the client's 932 value. 934 If at any time a server is faced with data that it does not 935 understand, or that violates some criteria by which the server 936 determines safety of input, or when the server sees a handshake that 937 does not correspond to the values the server is expecting (e.g. 938 incorrect path or origin), the server should just disconnect. It is 939 always safe to disconnect. 941 7. IANA considerations 943 7.1. Registration of ws: scheme 945 URI scheme name. 946 ws 948 Status. 949 Permanent. 951 URI scheme syntax. 952 "ws" ":" hier-part [ "?" query ] 954 URI scheme semantics. 955 The only operation for this scheme is to open a connection using 956 the Web Socket protocol. 958 Encoding considerations. 959 UTF-8 only. 961 Applications/protocols that use this URI scheme name. 962 Web Socket protocol. 964 Interoperability considerations. 965 None. 967 Security considerations. 968 See "Security considerations" section above. 970 Contact. 971 Ian Hickson 973 Author/Change controller. 974 Ian Hickson 976 References. 977 This document. 979 7.2. Registration of wss: scheme 981 URI scheme name. 982 wss 984 Status. 985 Permanent. 987 URI scheme syntax. 988 "wss" ":" hier-part [ "?" query ] 990 URI scheme semantics. 991 The only operation for this scheme is to open a connection using 992 the Web Socket protocol, encrypted using TLS. 994 Encoding considerations. 995 UTF-8 only. 997 Applications/protocols that use this URI scheme name. 998 Web Socket protocol over TLS. 1000 Interoperability considerations. 1001 None. 1003 Security considerations. 1004 See "Security considerations" section above. 1006 Contact. 1007 Ian Hickson 1009 Author/Change controller. 1010 Ian Hickson 1012 References. 1013 This document. 1015 7.3. Registration of ports 81 and 815 1017 See IANA ticket #257454 for port 81 and IANA ticket #257455 for port 1018 815. 1020 7.4. Registration of the "WebSocket" HTTP Upgrade keyword 1022 Name of token. 1023 WebSocket 1025 Author/Change controller. 1026 Ian Hickson 1028 Contact. 1029 Ian Hickson 1031 References. 1032 This document. 1034 8. Normative References 1036 [HTML5] Hickson, I., "HTML5", August 2009. 1038 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 1039 Mechanism", RFC 2109, February 1997. 1041 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1042 Requirement Levels", BCP 14, RFC 2119, March 1997. 1044 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1045 RFC 2246, January 1999. 1047 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1048 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1049 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1051 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 1052 Mechanism", RFC 2965, October 2000. 1054 Author's Address 1056 Ian Hickson 1057 Google, Inc. 1059 Email: ian@hixie.ch 1060 URI: http://ln.hixie.ch/