idnits 2.17.1 draft-hixie-thewebsocketprotocol-27.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 (July 29, 2009) is 5375 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 July 29, 2009 5 Expires: January 30, 2010 7 The Web Socket protocol 8 draft-hixie-thewebsocketprotocol-27 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 January 30, 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 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.1. Security model . . . . . . . . . . . . . . . . . . . . . . 4 62 1.2. Relationship to TCP/IP and HTTP . . . . . . . . . . . . . 4 63 1.3. Establishing a connection . . . . . . . . . . . . . . . . 5 64 1.4. The Web Socket protocol . . . . . . . . . . . . . . . . . 5 65 2. Conformance requirements . . . . . . . . . . . . . . . . . . . 7 66 3. Client-side requirements . . . . . . . . . . . . . . . . . . . 8 67 3.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 8 68 3.2. Data framing . . . . . . . . . . . . . . . . . . . . . . . 15 69 3.3. Handling errors in UTF-8 . . . . . . . . . . . . . . . . . 16 70 4. Server-side requirements . . . . . . . . . . . . . . . . . . . 17 71 4.1. Minimal handshake . . . . . . . . . . . . . . . . . . . . 17 72 4.2. Handshake details . . . . . . . . . . . . . . . . . . . . 18 73 4.3. Data framing . . . . . . . . . . . . . . . . . . . . . . . 19 74 5. Closing the connection . . . . . . . . . . . . . . . . . . . . 20 75 6. Security considerations . . . . . . . . . . . . . . . . . . . 21 76 7. IANA considerations . . . . . . . . . . . . . . . . . . . . . 22 77 8. Normative References . . . . . . . . . . . . . . . . . . . . . 23 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 24 80 1. Introduction 82 _This section is non-normative._ 84 The Web Socket protocol is designed on the principle that there 85 should be minimal framing (the only framing that exists is to make 86 the protocol frame-based instead of stream-based, and to support a 87 distinction between Unicode text and binary frames). It is expected 88 that metadata would be layered on top of Web Socket by the 89 application layer, in the same way that metadata is layered on top of 90 TCP/IP by the application layer (HTTP). 92 Conceptually, Web Socket is really just a layer on top of TCP/IP that 93 adds a Web "origin"-based security model for browsers; adds an 94 addressing and protocol naming mechanism to support multiple services 95 on one port and multiple host names on one IP address; and layers a 96 framing mechanism on top of TCP to get back to the IP packet 97 mechanism that TCP is built on, but without length limits. Other 98 than that, it adds nothing. Basically it is intended to be as close 99 as possible to just exposing raw TCP/IP to script as possible given 100 the constraints of the Web. It's also designed in such a way that its 101 servers can share a port with HTTP servers, by having its handshake 102 be a valid HTTP Upgrade handshake also. 104 1.1. Security model 106 _This section is non-normative._ 108 The Web Socket protocol uses the origin model used by Web browsers to 109 restrict which Web pages can contact a Web Socket server when the Web 110 Socket protocol is used from a Web page. Naturally, when the Web 111 Socket protocol is used directly (not from a Web page), the origin 112 model is not useful, as the client can provide any arbitrary origin 113 string. 115 1.2. Relationship to TCP/IP and HTTP 117 _This section is non-normative._ 119 The Web Socket protocol is an independent TCP-based protocol. Its 120 only relationship to HTTP is that its handshake is interpreted by 121 HTTP servers as an Upgrade request. 123 The Web Socket protocol by default uses port 81 for regular Web 124 Socket connections and port 815 for Web Socket connections tunneled 125 over TLS. 127 1.3. Establishing a connection 129 _This section is non-normative._ 131 There are several options for establishing a Web Socket connection. 133 The simplest method is to use port 81 to get a direct connection to a 134 Web Socket server. However, this port may be blocked by firewalls. 136 The second simplest method is to use TLS encryption and port 815 to 137 connect directly to a Web Socket server. This is the preferred 138 solution, as it is secure and correct. However, TLS encryption can 139 be computationally expensive, and port 815 might also be blocked by 140 firewalls. 142 To avoid firewalls, ports 80 and 443 might be used instead. These 143 are the HTTP and HTTPS ports. Port 80 traffic, however, will often 144 be intercepted by HTTP proxies, which can lead to the connection 145 failing to be established. 147 Port 443, using encryption, is therefore the most reliable solution. 148 It is unlikely to be blocked by a firewall or intercepted by a proxy. 149 However, again, TLS encryption can be computationally expensive. 151 When a connection is to be made to a port that is shared by an HTTP 152 server (a situation that is quite likely to occur with traffic to 153 ports 80 and 443), the connection will appear to the HTTP server to 154 be a regular GET request with an Upgrade offer. In relatively simple 155 setups with just one IP address and a single server for all traffic 156 to a single hostname, this might allow a practical way for systems 157 based on the Web Socket protocol to be deployed. In more elaborate 158 setups (e.g. with load balancers and multiple servers), a dedicated 159 set of hosts for Web Socket connections separate from the HTTP 160 servers is probably easier to manage. 162 1.4. The Web Socket protocol 164 _This section is non-normative._ 166 The protocol has two parts: a handshake, and then the data transfer. 168 The handshake from the client looks as follows: 170 GET /demo HTTP/1.1 171 Upgrade: WebSocket 172 Connection: Upgrade 173 Host: example.com 174 Origin: http://example.com 175 WebSocket-Protocol: sample 177 The handshake from the server looks as follows: 179 HTTP/1.1 101 Web Socket Protocol Handshake 180 Upgrade: WebSocket 181 Connection: Upgrade 182 WebSocket-Origin: http://example.com 183 WebSocket-Location: ws://example.com/demo 184 WebSocket-Protocol: sample 186 Once the client and server have both sent their handshakes, and if 187 the handshake was successful, then the data transfer part starts. 188 This is a two-way communication channel where each side can, 189 independently from the other, send data at will. 191 Data is sent in the form of UTF-8 text. Each frame of data starts 192 with a 0x00 byte and ends with a 0xFF byte, with the UTF-8 text in 193 between. 195 2. Conformance requirements 197 All diagrams, examples, and notes in this specification are non- 198 normative, as are all sections explicitly marked non-normative. 199 Everything else in this specification is normative. 201 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 202 "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this 203 document are to be interpreted as described in RFC2119. For 204 readability, these words do not appear in all uppercase letters in 205 this specification. [RFC2119] 207 Requirements phrased in the imperative as part of algorithms (such as 208 "strip any leading space characters" or "return false and abort these 209 steps") are to be interpreted with the meaning of the key word 210 ("must", "should", "may", etc) used in introducing the algorithm. 212 Conformance requirements phrased as algorithms or specific steps may 213 be implemented in any manner, so long as the end result is 214 equivalent. (In particular, the algorithms defined in this 215 specification are intended to be easy to follow, and not intended to 216 be performant.) 218 Implementations may impose implementation-specific limits on 219 otherwise unconstrained inputs, e.g. to prevent denial of service 220 attacks, to guard against running out of memory, or to work around 221 platform-specific limitations. 223 The conformance classes defined by this specification are user agents 224 and servers. 226 3. Client-side requirements 228 _This section only applies to user agents, not to servers._ 230 NOTE: This specification doesn't currently define a limit to the 231 number of simultaneous connections that a client can establish to a 232 server. 234 3.1. Handshake 236 When the user agent is to *establish a Web Socket connection* to a 237 host /host/, optionally on port /port/, from an origin /origin/, with 238 a flag /secure/, with a particular /resource name/, and optionally 239 with a particular /protocol/, it must run the following steps. 241 NOTE: The /host/ and /origin/ strings will be all-lowercase when this 242 algorithm is invoked. 244 1. If there is no explicit /port/, then: if /secure/ is false, let 245 /port/ be 81, otherwise let /port/ be 815. 247 2. If the user agent already has a Web Socket connection to the 248 remote host (IP address) identified by /host/, even if known by 249 another name, wait until that connection has been established or 250 for that connection to have failed. 252 NOTE: This makes it harder for a script to perform a denial of 253 service attack by just opening a large number of Web Socket 254 connections to a remote host. 256 NOTE: There is no limit to the number of established Web Socket 257 connections a user agent can have with a single remote host. 258 Servers can refuse to connect users with an excessive number of 259 connections, or disconnect resource-hogging users when suffering 260 high load. 262 3. If the user agent is configured to use a proxy when using the 263 Web Socket protocol to connect to host /host/ and/or port 264 /port/, then connect to that proxy and ask it to open a TCP/IP 265 connection to the host given by /host/ and the port given by 266 /port/. 268 EXAMPLE: For example, if the user agent uses an HTTP proxy 269 for all traffic, then if it was to try to connect to port 80 270 on server example.com, it might send the following lines to 271 the proxy server: 273 CONNECT example.com:80 HTTP/1.1 274 Host: example.com 276 If there was a password, the connection might look like: 278 CONNECT example.com:80 HTTP/1.1 279 Host: example.com 280 Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE= 282 Otherwise, if the user agent is not configured to use a proxy, 283 then open a TCP/IP connection to the host given by /host/ and 284 the port given by /port/. 286 NOTE: Implementations that do not expose explicit UI for 287 selecting a proxy for Web Socket connections separate from other 288 proxies are encouraged to use a SOCKS proxy for Web Socket 289 connections, if available, or failing that, to prefer the proxy 290 configured for HTTPS connections over the proxy configured for 291 HTTP connections. 293 4. If the connection could not be opened, then fail the Web Socket 294 connection and abort these steps. 296 5. If /secure/ is true, perform a TLS handshake over the 297 connection. If this fails (e.g. the server's certificate could 298 not be verified), then fail the Web Socket connection and abort 299 these steps. Otherwise, all further communication on this 300 channel must run through the encrypted tunnel. [RFC2246] 302 6. Send the following bytes to the remote side (the server): 304 47 45 54 20 306 Send the /resource name/ value, encoded as US-ASCII. 308 Send the following bytes: 310 20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61 311 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43 312 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61 313 64 65 0d 0a 315 NOTE: The string "GET ", the path, " HTTP/1.1", CRLF, the string 316 "Upgrade: WebSocket", CRLF, and the string "Connection: 317 Upgrade", CRLF. 319 7. Send the following bytes: 321 48 6f 73 74 3a 20 323 Send the /host/ value, encoded as US-ASCII. 325 Send the following bytes: 327 0d 0a 329 NOTE: The string "Host: ", the host, and CRLF. 331 8. Send the following bytes: 333 4f 72 69 67 69 6e 3a 20 335 Send the /origin/ value, encoded as US-ASCII. 337 NOTE: The /origin/ value is a string that was passed to this 338 algorithm. 340 Send the following bytes: 342 0d 0a 344 NOTE: The string "Origin: ", the origin, and CRLF. 346 9. If there is no /protocol/, then skip this step. 348 Otherwise, send the following bytes: 350 57 65 62 53 6f 63 6b 65 74 2d 50 72 6f 74 6f 63 351 6f 6c 3a 20 353 Send the /protocol/ value, encoded as US-ASCII. 355 Send the following bytes: 357 0d 0a 359 NOTE: The string "WebSocket-Protocol: ", the protocol, and CRLF. 361 10. If the client has any authentication information or cookies that 362 would be relevant to a resource accessed over HTTP, if /secure/ 363 is false, or HTTPS, if it is true, on host /host/, port /port/, 364 with /resource name/ as the path (and possibly query 365 parameters), then HTTP headers that would be appropriate for 366 that information should be sent at this point. [RFC2616] 367 [RFC2109] [RFC2965] 368 Each header must be on a line of its own (each ending with a CR 369 LF sequence). For the purposes of this step, each header must 370 not be split into multiple lines (despite HTTP otherwise 371 allowing this with continuation lines). 373 EXAMPLE: For example, if the server had a username and 374 password that applied to |http://example.com/socket|, and the 375 Web Socket was being opened to |ws://example.com:80/socket|, 376 it could send them: 378 Authorization: Basic d2FsbGU6ZXZl 380 However, it would not send them if the Web Socket was being 381 opened to |ws://example.com/socket|, as that uses a different 382 port (81, not 80). 384 11. Send the following bytes: 386 0d 0a 388 NOTE: Just a CRLF (a blank line). 390 12. Read the first 85 bytes from the server. If the connection 391 closes before 85 bytes are received, or if the first 85 bytes 392 aren't exactly equal to the following bytes, then fail the Web 393 Socket connection and abort these steps. 395 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 396 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 397 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 398 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 399 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 400 61 64 65 0d 0a 402 NOTE: The string "HTTP/1.1 101 Web Socket Protocol Handshake", 403 CRLF, the string "Upgrade: WebSocket", CRLF, the string 404 "Connection: Upgrade", CRLF. 406 User agents may apply a timeout to this step, failing the Web 407 Socket connection if the server does not respond with the above 408 bytes within a suitable time period. 410 13. Let /headers/ be a list of name-value pairs, initially empty. 412 14. _Header_: Let /name/ and /value/ be empty byte arrays. 414 15. Read a byte from the server. 416 If the connection closes before this byte is received, then fail 417 the Web Socket connection and abort these steps. 419 Otherwise, handle the byte as described in the appropriate entry 420 below: 422 -> If the byte is 0x0d (ASCII CR) 423 If the /name/ byte array is empty, then jump to the headers 424 processing step. Otherwise, fail the Web Socket connection 425 and abort these steps. 427 -> If the byte is 0x0a (ASCII LF) 428 Fail the Web Socket connection and abort these steps. 430 -> If the byte is 0x3a (ASCII ":") 431 Move on to the next step. 433 -> If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z") 434 Append a byte whose value is the byte's value plus 0x20 to 435 the /name/ byte array and redo this step for the next byte. 437 -> Otherwise 438 Append the byte to the /name/ byte array and redo this step 439 for the next byte. 441 NOTE: This reads a header name, terminated by a colon, 442 converting upper-case ASCII letters to lowercase, and aborting 443 if a stray CR or LF is found. 445 16. Read a byte from the server. 447 If the connection closes before this byte is received, then fail 448 the Web Socket connection and abort these steps. 450 Otherwise, handle the byte as described in the appropriate entry 451 below: 453 -> If the byte is 0x20 (ASCII space) 454 Ignore the byte and move on to the next step. 456 -> Otherwise 457 Treat the byte as described by the list in the next step, 458 then move on to that next step for real. 460 NOTE: This skips past a space character after the colon, if 461 necessary. 463 17. Read a byte from the server. 465 If the connection closes before this byte is received, then fail 466 the Web Socket connection and abort these steps. 468 Otherwise, handle the byte as described in the appropriate entry 469 below: 471 -> If the byte is 0x0d (ASCII CR) 472 Move on to the next step. 474 -> If the byte is 0x0a (ASCII LF) 475 Fail the Web Socket connection and abort these steps. 477 -> Otherwise 478 Append the byte to the /value/ byte array and redo this step 479 for the next byte. 481 NOTE: This reads a header value, terminated by a CRLF. 483 18. Read a byte from the server. 485 If the connection closes before this byte is received, or if the 486 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 487 connection and abort these steps. 489 NOTE: This skips past the LF byte of the CRLF after the header. 491 19. Append an entry to the /headers/ list that has the name given by 492 the string obtained by interpreting the /name/ byte array as a 493 UTF-8 byte stream and the value given by the string obtained by 494 interpreting the /value/ byte array as a UTF-8 byte stream. 496 20. Return to the "Header" step above. 498 21. _Headers processing_: If there is not exactly one entry in the 499 /headers/ list whose name is "websocket-origin", or if there is 500 not exactly one entry in the /headers/ list whose name is 501 "websocket-location", or if the /protocol/ was specified but 502 there is not exactly one entry in the /headers/ list whose name 503 is "websocket-protocol", or if there are any entries in the 504 /headers/ list whose names are the empty string, then fail the 505 Web Socket connection and abort these steps. 507 22. Read a byte from the server. 509 If the connection closes before this byte is received, or if the 510 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 511 connection and abort these steps. 513 NOTE: This skips past the LF byte of the CRLF after the blank 514 line after the headers. 516 23. Handle each entry in the /headers/ list as follows: 518 -> If the entry's name is "websocket-origin" 519 If the value is not exactly equal to /origin/, converted to 520 ASCII lowercase, then fail the Web Socket connection and 521 abort these steps. 523 -> If the entry's name is "websocket-location" 524 If the value is not exactly equal to a string consisting of 525 the following components in the same order, then fail the Web 526 Socket connection and abort these steps: 528 1. The string "ws" if /secure/ is false and "wss" if 529 /secure/ is true 531 2. The three characters "://". 533 3. The value of /host/. 535 4. If /secure/ is false and /port/ is not 81, or if /secure/ 536 is true and /port/ is not 815: a ":" character followed 537 by the value of /port/. 539 5. The value of /resource name/. 541 -> If the entry's name is "websocket-protocol" 542 If there was a /protocol/ specified, and the value is not 543 exactly equal to /protocol/, then fail the Web Socket 544 connection and abort these steps. (If no /protocol/ was 545 specified, the header is ignored.) 547 -> If the entry's name is "set-cookie" or "set-cookie2" or 548 another cookie-related header name 549 Handle the cookie as defined by the appropriate spec, with 550 the resource being the one with the host /host/, the port 551 /port/, the path (and possibly query parameters) /resource 552 name/, and the scheme |http| if /secure/ is false and |https| 553 if /secure/ is true. [RFC2109] [RFC2965] 555 -> Any other name 556 Ignore it. 558 24. The *Web Socket connection is established*. Now the user agent 559 must send and receive to and from the connection as described in 560 the next section. 562 To *fail the Web Socket connection*, the user agent must close the 563 Web Socket connection, and may report the problem to the user (which 564 would be especially useful for developers). However, user agents 565 must not convey the failure information to the script that attempted 566 the connection in a way distinguishable from the Web Socket being 567 closed normally. 569 3.2. Data framing 571 Once a Web Socket connection is established, the user agent must run 572 through the following state machine for the bytes sent by the server. 574 1. Try to read a byte from the server. Let /frame type/ be that 575 byte. 577 If no byte could be read because the Web Socket connection is 578 closed, then abort. 580 2. Handle the /frame type/ byte as follows: 582 If the high-order bit of the /frame type/ byte is set (i.e. if 583 /frame type/ _and_ed with 0x80 returns 0x80) 584 Run these steps. If at any point during these steps a read is 585 attempted but fails because the Web Socket connection is 586 closed, then abort. 588 1. Let /length/ be zero. 590 2. _Length_: Read a byte, let /b/ be that byte. 592 3. Let /b_v/ be integer corresponding to the low 7 bits of 593 /b/ (the value you would get by _and_ing /b/ with 0x7f). 595 4. Multiply /length/ by 128, add /b_v/ to that result, and 596 store the final result in /length/. 598 5. If the high-order bit of /b/ is set (i.e. if /b/ _and_ed 599 with 0x80 returns 0x80), then return to the step above 600 labeled _length_. 602 6. Read /length/ bytes. 604 7. Discard the read bytes. 606 If the high-order bit of the /frame type/ byte is _not_ set (i.e. 607 if /frame type/ _and_ed with 0x80 returns 0x00) 608 Run these steps. If at any point during these steps a read is 609 attempted but fails because the Web Socket connection is 610 closed, then abort. 612 1. Let /raw data/ be an empty byte array. 614 2. _Data_: Read a byte, let /b/ be that byte. 616 3. If /b/ is not 0xff, then append /b/ to /raw data/ and 617 return to the previous step (labeled _data_). 619 4. Interpret /raw data/ as a UTF-8 string, and store that 620 string in /data/. 622 5. If /frame type/ is 0x00, then *a message has been 623 received* with text /data/. Otherwise, discard the data. 625 3. Return to the first step to read the next byte. 627 If the user agent is faced with content that is too large to be 628 handled appropriately, then it must fail the Web Socket connection. 630 Once a Web Socket connection is established, the user agent must use 631 the following steps to *send /data/ using the Web Socket*: 633 1. Send a 0x00 byte to the server. 635 2. Encode /data/ using UTF-8 and send the resulting byte stream to 636 the server. 638 3. Send a 0xff byte to the server. 640 If at any point there is a fatal problem with sending data to the 641 server, the user agent must fail the Web Socket connection. 643 3.3. Handling errors in UTF-8 645 When a client is to interpret a byte stream as UTF-8 but finds that 646 the byte stream is not in fact a valid UTF-8 stream, then any bytes 647 or sequences of bytes that are not valid UTF-8 sequences must be 648 interpreted as a U+FFFD REPLACEMENT CHARACTER. 650 4. Server-side requirements 652 _This section only applies to servers._ 654 4.1. Minimal handshake 656 NOTE: This section describes the minimal requirements for a server- 657 side implementation of Web Sockets. 659 Listen on a port for TCP/IP. Upon receiving a connection request, 660 open a connection and send the following bytes back to the client: 662 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 663 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 664 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 665 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 666 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 667 61 64 65 0d 0a 669 Send the string "WebSocket-Origin" followed by a U+003A COLON (":") 670 followed by the ASCII serialization of the origin from which the 671 server is willing to accept connections, followed by a CRLF pair 672 (0x0d 0x0a). 674 For instance: 676 WebSocket-Origin: http://example.com 678 Send the string "WebSocket-Location" followed by a U+003A COLON (":") 679 followed by the URL of the Web Socket script, followed by a CRLF pair 680 (0x0d 0x0a). 682 For instance: 684 WebSocket-Location: ws://example.com:80/demo 686 Send another CRLF pair (0x0d 0x0a). 688 Read data from the client until four bytes 0x0d 0x0a 0x0d 0x0a are 689 read. This data must either be discarded or handled as described in 690 the following section describing the handshake details. 692 If the connection isn't dropped at this point, go to the data framing 693 section. 695 4.2. Handshake details 697 The previous section ignores the data that is transmitted by the 698 client during the handshake. 700 The data sent by the client consists of a number of fields separated 701 by CR LF pairs (bytes 0x0d 0x0a). 703 The first field consists of three tokens separated by space 704 characters (byte 0x20). The middle token is the path being opened. 705 If the server supports multiple paths, then the server should echo 706 the value of this field in the initial handshake, as part of the URL 707 given on the |WebSocket-Location| line (after the appropriate scheme 708 and host). 710 If the first field does not have three tokens, the server should 711 abort the connection as it probably represents an errorneous client. 713 The remaining fields consist of name-value pairs, with the name part 714 separated from the value part by a colon and a space (bytes 0x3a 715 0x20). Of these, several are interesting: 717 Host (bytes 48 6f 73 74) 718 The value gives the hostname that the client intended to use when 719 opening the Web Socket. It would be of interest in particular to 720 virtual hosting environments, where one server might serve 721 multiple hosts, and might therefore want to return different data. 723 The right host has to be output as part of the URL given on the 724 |WebSocket-Location| line of the handshake described above, to 725 verify that the server knows that it is really representing that 726 host. 728 Origin (bytes 4f 72 69 67 69 6e) 729 The value gives the scheme, hostname, and port (if it's not the 730 default port for the given scheme) of the page that asked the 731 client to open the Web Socket. It would be interesting if the 732 server's operator had deals with operators of other sites, since 733 the server could then decide how to respond (or indeed, _whether_ 734 to respond) based on which site was requesting a connection. 736 If the server supports connections from more than one origin, then 737 the server should echo the value of this field in the initial 738 handshake, on the |WebSocket-Origin| line. 740 Other fields 741 Other fields can be used, such as "Cookie" or "Authorization", for 742 authentication purposes. 744 Any fields that lack the colon-space separator should be discarded 745 and may cause the server to disconnect. 747 4.3. Data framing 749 NOTE: This section only describes how to handle content that this 750 specification allows user agents to send (text). It doesn't handle 751 any arbitrary content in the same way that the requirements on user 752 agents defined earlier handle any content including possible future 753 extensions to the protocols. 755 The server must run through the following steps to process the bytes 756 sent by the client: 758 1. Read a byte from the client. Assuming everything is going 759 according to plan, it will be a 0x00 byte. If the byte is not a 760 0x00 byte, then the server may disconnect. 762 2. Let /raw data/ be an empty byte array. 764 3. _Data_: Read a byte, let /b/ be that byte. 766 4. If /b/ is not 0xff, then append /b/ to /raw data/ and return to 767 the previous step (labeled _data_). 769 5. Interpret /raw data/ as a UTF-8 string, and apply whatever 770 server-specific processing is to occur for the resulting string. 772 6. Return to the first step to read the next byte. 774 The server must run through the following steps to send strings to 775 the client: 777 1. Send a 0x00 byte to the client to indicate the start of a string. 779 2. Encode /data/ using UTF-8 and send the resulting byte stream to 780 the client. 782 3. Send a 0xff byte to the client to indicate the end of the 783 message. 785 5. Closing the connection 787 To *close the Web Socket connection*, either the user agent or the 788 server closes the TCP/IP connection. There is no closing handshake. 789 Whether the user agent or the server closes the connection, it is 790 said that the *Web Socket connection is closed*. 792 Servers may close the Web Socket connection whenever desired. 794 User agents should not close the Web Socket connection arbitrarily. 796 6. Security considerations 798 ** ISSUE ** ... 800 7. IANA considerations 802 ** ISSUE ** ...(two URI schemes, two ports, HTTP Upgrade keyword) 804 8. Normative References 806 [HTML5] Hickson, I., "HTML5", July 2009. 808 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 809 Mechanism", RFC 2109, February 1997. 811 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 812 Requirement Levels", BCP 14, RFC 2119, March 1997. 814 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 815 RFC 2246, January 1999. 817 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 818 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 819 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 821 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 822 Mechanism", RFC 2965, October 2000. 824 Author's Address 826 Ian Hickson 827 Google, Inc. 829 Email: ian@hixie.ch 830 URI: http://ln.hixie.ch/