idnits 2.17.1 draft-hixie-thewebsocketprotocol-28.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 30, 2009) is 5382 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 30, 2009 5 Expires: January 31, 2010 7 The Web Socket protocol 8 draft-hixie-thewebsocketprotocol-28 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 31, 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 . . . . . . . . . . . . . . . . . . . . . . . 15 72 3.3. Handling errors in UTF-8 . . . . . . . . . . . . . . . . . 16 73 4. Server-side requirements . . . . . . . . . . . . . . . . . . . 17 74 4.1. Minimal handshake . . . . . . . . . . . . . . . . . . . . 17 75 4.2. Handshake details . . . . . . . . . . . . . . . . . . . . 18 76 4.3. Data framing . . . . . . . . . . . . . . . . . . . . . . . 19 77 5. Closing the connection . . . . . . . . . . . . . . . . . . . . 20 78 6. Security considerations . . . . . . . . . . . . . . . . . . . 21 79 7. IANA considerations . . . . . . . . . . . . . . . . . . . . . 22 80 8. Normative References . . . . . . . . . . . . . . . . . . . . . 23 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 24 83 1. Introduction 85 _This section is non-normative._ 87 The Web Socket protocol is designed on the principle that there 88 should be minimal framing (the only framing that exists is to make 89 the protocol frame-based instead of stream-based, and to support a 90 distinction between Unicode text and binary frames). It is expected 91 that metadata would be layered on top of Web Socket by the 92 application layer, in the same way that metadata is layered on top of 93 TCP/IP by the application layer (HTTP). 95 Conceptually, Web Socket is really just a layer on top of TCP/IP that 96 adds a Web "origin"-based security model for browsers; adds an 97 addressing and protocol naming mechanism to support multiple services 98 on one port and multiple host names on one IP address; and layers a 99 framing mechanism on top of TCP to get back to the IP packet 100 mechanism that TCP is built on, but without length limits. Other 101 than that, it adds nothing. Basically it is intended to be as close 102 as possible to just exposing raw TCP/IP to script as possible given 103 the constraints of the Web. It's also designed in such a way that its 104 servers can share a port with HTTP servers, by having its handshake 105 be a valid HTTP Upgrade handshake also. 107 1.1. Security model 109 _This section is non-normative._ 111 The Web Socket protocol uses the origin model used by Web browsers to 112 restrict which Web pages can contact a Web Socket server when the Web 113 Socket protocol is used from a Web page. Naturally, when the Web 114 Socket protocol is used directly (not from a Web page), the origin 115 model is not useful, as the client can provide any arbitrary origin 116 string. 118 1.2. Relationship to TCP/IP and HTTP 120 _This section is non-normative._ 122 The Web Socket protocol is an independent TCP-based protocol. Its 123 only relationship to HTTP is that its handshake is interpreted by 124 HTTP servers as an Upgrade request. 126 The Web Socket protocol by default uses port 81 for regular Web 127 Socket connections and port 815 for Web Socket connections tunneled 128 over TLS. 130 1.3. Establishing a connection 132 _This section is non-normative._ 134 There are several options for establishing a Web Socket connection. 136 The simplest method is to use port 81 to get a direct connection to a 137 Web Socket server. However, this port may be blocked by firewalls. 139 The second simplest method is to use TLS encryption and port 815 to 140 connect directly to a Web Socket server. This is the preferred 141 solution, as it is secure and correct. However, TLS encryption can 142 be computationally expensive, and port 815 might also be blocked by 143 firewalls. 145 To avoid firewalls, ports 80 and 443 might be used instead. These 146 are the HTTP and HTTPS ports. Port 80 traffic, however, will often 147 be intercepted by HTTP proxies, which can lead to the connection 148 failing to be established. 150 Port 443, using encryption, is therefore the most reliable solution. 151 It is unlikely to be blocked by a firewall or intercepted by a proxy. 152 However, again, TLS encryption can be computationally expensive. 154 When a connection is to be made to a port that is shared by an HTTP 155 server (a situation that is quite likely to occur with traffic to 156 ports 80 and 443), the connection will appear to the HTTP server to 157 be a regular GET request with an Upgrade offer. In relatively simple 158 setups with just one IP address and a single server for all traffic 159 to a single hostname, this might allow a practical way for systems 160 based on the Web Socket protocol to be deployed. In more elaborate 161 setups (e.g. with load balancers and multiple servers), a dedicated 162 set of hosts for Web Socket connections separate from the HTTP 163 servers is probably easier to manage. 165 1.4. The Web Socket protocol 167 _This section is non-normative._ 169 The protocol has two parts: a handshake, and then the data transfer. 171 The handshake from the client looks as follows: 173 GET /demo HTTP/1.1 174 Upgrade: WebSocket 175 Connection: Upgrade 176 Host: example.com 177 Origin: http://example.com 178 WebSocket-Protocol: sample 180 The handshake from the server looks as follows: 182 HTTP/1.1 101 Web Socket Protocol Handshake 183 Upgrade: WebSocket 184 Connection: Upgrade 185 WebSocket-Origin: http://example.com 186 WebSocket-Location: ws://example.com/demo 187 WebSocket-Protocol: sample 189 Once the client and server have both sent their handshakes, and if 190 the handshake was successful, then the data transfer part starts. 191 This is a two-way communication channel where each side can, 192 independently from the other, send data at will. 194 Data is sent in the form of UTF-8 text. Each frame of data starts 195 with a 0x00 byte and ends with a 0xFF byte, with the UTF-8 text in 196 between. 198 2. Conformance requirements 200 All diagrams, examples, and notes in this specification are non- 201 normative, as are all sections explicitly marked non-normative. 202 Everything else in this specification is normative. 204 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 205 "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this 206 document are to be interpreted as described in RFC2119. For 207 readability, these words do not appear in all uppercase letters in 208 this specification. [RFC2119] 210 Requirements phrased in the imperative as part of algorithms (such as 211 "strip any leading space characters" or "return false and abort these 212 steps") are to be interpreted with the meaning of the key word 213 ("must", "should", "may", etc) used in introducing the algorithm. 215 Conformance requirements phrased as algorithms or specific steps may 216 be implemented in any manner, so long as the end result is 217 equivalent. (In particular, the algorithms defined in this 218 specification are intended to be easy to follow, and not intended to 219 be performant.) 221 Implementations may impose implementation-specific limits on 222 otherwise unconstrained inputs, e.g. to prevent denial of service 223 attacks, to guard against running out of memory, or to work around 224 platform-specific limitations. 226 The conformance classes defined by this specification are user agents 227 and servers. 229 3. Client-side requirements 231 _This section only applies to user agents, not to servers._ 233 NOTE: This specification doesn't currently define a limit to the 234 number of simultaneous connections that a client can establish to a 235 server. 237 3.1. Handshake 239 When the user agent is to *establish a Web Socket connection* to a 240 host /host/, optionally on port /port/, from an origin /origin/, with 241 a flag /secure/, with a particular /resource name/, and optionally 242 with a particular /protocol/, it must run the following steps. 244 NOTE: The /host/ and /origin/ strings will be all-lowercase when this 245 algorithm is invoked. 247 1. If there is no explicit /port/, then: if /secure/ is false, let 248 /port/ be 81, otherwise let /port/ be 815. 250 2. If the user agent already has a Web Socket connection to the 251 remote host (IP address) identified by /host/, even if known by 252 another name, wait until that connection has been established or 253 for that connection to have failed. 255 NOTE: This makes it harder for a script to perform a denial of 256 service attack by just opening a large number of Web Socket 257 connections to a remote host. 259 NOTE: There is no limit to the number of established Web Socket 260 connections a user agent can have with a single remote host. 261 Servers can refuse to connect users with an excessive number of 262 connections, or disconnect resource-hogging users when suffering 263 high load. 265 3. If the user agent is configured to use a proxy when using the 266 Web Socket protocol to connect to host /host/ and/or port 267 /port/, then connect to that proxy and ask it to open a TCP/IP 268 connection to the host given by /host/ and the port given by 269 /port/. 271 EXAMPLE: For example, if the user agent uses an HTTP proxy 272 for all traffic, then if it was to try to connect to port 80 273 on server example.com, it might send the following lines to 274 the proxy server: 276 CONNECT example.com:80 HTTP/1.1 277 Host: example.com 279 If there was a password, the connection might look like: 281 CONNECT example.com:80 HTTP/1.1 282 Host: example.com 283 Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE= 285 Otherwise, if the user agent is not configured to use a proxy, 286 then open a TCP/IP connection to the host given by /host/ and 287 the port given by /port/. 289 NOTE: Implementations that do not expose explicit UI for 290 selecting a proxy for Web Socket connections separate from other 291 proxies are encouraged to use a SOCKS proxy for Web Socket 292 connections, if available, or failing that, to prefer the proxy 293 configured for HTTPS connections over the proxy configured for 294 HTTP connections. 296 4. If the connection could not be opened, then fail the Web Socket 297 connection and abort these steps. 299 5. If /secure/ is true, perform a TLS handshake over the 300 connection. If this fails (e.g. the server's certificate could 301 not be verified), then fail the Web Socket connection and abort 302 these steps. Otherwise, all further communication on this 303 channel must run through the encrypted tunnel. [RFC2246] 305 6. Send the following bytes to the remote side (the server): 307 47 45 54 20 309 Send the /resource name/ value, encoded as US-ASCII. 311 Send the following bytes: 313 20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61 314 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43 315 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61 316 64 65 0d 0a 318 NOTE: The string "GET ", the path, " HTTP/1.1", CRLF, the string 319 "Upgrade: WebSocket", CRLF, and the string "Connection: 320 Upgrade", CRLF. 322 7. Send the following bytes: 324 48 6f 73 74 3a 20 326 Send the /host/ value, encoded as US-ASCII. 328 Send the following bytes: 330 0d 0a 332 NOTE: The string "Host: ", the host, and CRLF. 334 8. Send the following bytes: 336 4f 72 69 67 69 6e 3a 20 338 Send the /origin/ value, encoded as US-ASCII. 340 NOTE: The /origin/ value is a string that was passed to this 341 algorithm. 343 Send the following bytes: 345 0d 0a 347 NOTE: The string "Origin: ", the origin, and CRLF. 349 9. If there is no /protocol/, then skip this step. 351 Otherwise, send the following bytes: 353 57 65 62 53 6f 63 6b 65 74 2d 50 72 6f 74 6f 63 354 6f 6c 3a 20 356 Send the /protocol/ value, encoded as US-ASCII. 358 Send the following bytes: 360 0d 0a 362 NOTE: The string "WebSocket-Protocol: ", the protocol, and CRLF. 364 10. If the client has any authentication information or cookies that 365 would be relevant to a resource accessed over HTTP, if /secure/ 366 is false, or HTTPS, if it is true, on host /host/, port /port/, 367 with /resource name/ as the path (and possibly query 368 parameters), then HTTP headers that would be appropriate for 369 that information should be sent at this point. [RFC2616] 370 [RFC2109] [RFC2965] 371 Each header must be on a line of its own (each ending with a CR 372 LF sequence). For the purposes of this step, each header must 373 not be split into multiple lines (despite HTTP otherwise 374 allowing this with continuation lines). 376 EXAMPLE: For example, if the server had a username and 377 password that applied to |http://example.com/socket|, and the 378 Web Socket was being opened to |ws://example.com:80/socket|, 379 it could send them: 381 Authorization: Basic d2FsbGU6ZXZl 383 However, it would not send them if the Web Socket was being 384 opened to |ws://example.com/socket|, as that uses a different 385 port (81, not 80). 387 11. Send the following bytes: 389 0d 0a 391 NOTE: Just a CRLF (a blank line). 393 12. Read the first 85 bytes from the server. If the connection 394 closes before 85 bytes are received, or if the first 85 bytes 395 aren't exactly equal to the following bytes, then fail the Web 396 Socket connection and abort these steps. 398 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 399 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 400 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 401 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 402 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 403 61 64 65 0d 0a 405 NOTE: The string "HTTP/1.1 101 Web Socket Protocol Handshake", 406 CRLF, the string "Upgrade: WebSocket", CRLF, the string 407 "Connection: Upgrade", CRLF. 409 User agents may apply a timeout to this step, failing the Web 410 Socket connection if the server does not respond with the above 411 bytes within a suitable time period. 413 13. Let /headers/ be a list of name-value pairs, initially empty. 415 14. _Header_: Let /name/ and /value/ be empty byte arrays. 417 15. Read a byte from the server. 419 If the connection closes before this byte is received, then fail 420 the Web Socket connection and abort these steps. 422 Otherwise, handle the byte as described in the appropriate entry 423 below: 425 -> If the byte is 0x0d (ASCII CR) 426 If the /name/ byte array is empty, then jump to the headers 427 processing step. Otherwise, fail the Web Socket connection 428 and abort these steps. 430 -> If the byte is 0x0a (ASCII LF) 431 Fail the Web Socket connection and abort these steps. 433 -> If the byte is 0x3a (ASCII ":") 434 Move on to the next step. 436 -> If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z") 437 Append a byte whose value is the byte's value plus 0x20 to 438 the /name/ byte array and redo this step for the next byte. 440 -> Otherwise 441 Append the byte to the /name/ byte array and redo this step 442 for the next byte. 444 NOTE: This reads a header name, terminated by a colon, 445 converting upper-case ASCII letters to lowercase, and aborting 446 if a stray CR or LF is found. 448 16. Read a byte from the server. 450 If the connection closes before this byte is received, then fail 451 the Web Socket connection and abort these steps. 453 Otherwise, handle the byte as described in the appropriate entry 454 below: 456 -> If the byte is 0x20 (ASCII space) 457 Ignore the byte and move on to the next step. 459 -> Otherwise 460 Treat the byte as described by the list in the next step, 461 then move on to that next step for real. 463 NOTE: This skips past a space character after the colon, if 464 necessary. 466 17. Read a byte from the server. 468 If the connection closes before this byte is received, then fail 469 the Web Socket connection and abort these steps. 471 Otherwise, handle the byte as described in the appropriate entry 472 below: 474 -> If the byte is 0x0d (ASCII CR) 475 Move on to the next step. 477 -> If the byte is 0x0a (ASCII LF) 478 Fail the Web Socket connection and abort these steps. 480 -> Otherwise 481 Append the byte to the /value/ byte array and redo this step 482 for the next byte. 484 NOTE: This reads a header value, terminated by a CRLF. 486 18. Read a byte from the server. 488 If the connection closes before this byte is received, or if the 489 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 490 connection and abort these steps. 492 NOTE: This skips past the LF byte of the CRLF after the header. 494 19. Append an entry to the /headers/ list that has the name given by 495 the string obtained by interpreting the /name/ byte array as a 496 UTF-8 byte stream and the value given by the string obtained by 497 interpreting the /value/ byte array as a UTF-8 byte stream. 499 20. Return to the "Header" step above. 501 21. _Headers processing_: If there is not exactly one entry in the 502 /headers/ list whose name is "websocket-origin", or if there is 503 not exactly one entry in the /headers/ list whose name is 504 "websocket-location", or if the /protocol/ was specified but 505 there is not exactly one entry in the /headers/ list whose name 506 is "websocket-protocol", or if there are any entries in the 507 /headers/ list whose names are the empty string, then fail the 508 Web Socket connection and abort these steps. 510 22. Read a byte from the server. 512 If the connection closes before this byte is received, or if the 513 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 514 connection and abort these steps. 516 NOTE: This skips past the LF byte of the CRLF after the blank 517 line after the headers. 519 23. Handle each entry in the /headers/ list as follows: 521 -> If the entry's name is "websocket-origin" 522 If the value is not exactly equal to /origin/, converted to 523 ASCII lowercase, then fail the Web Socket connection and 524 abort these steps. 526 -> If the entry's name is "websocket-location" 527 If the value is not exactly equal to a string consisting of 528 the following components in the same order, then fail the Web 529 Socket connection and abort these steps: 531 1. The string "ws" if /secure/ is false and "wss" if 532 /secure/ is true 534 2. The three characters "://". 536 3. The value of /host/. 538 4. If /secure/ is false and /port/ is not 81, or if /secure/ 539 is true and /port/ is not 815: a ":" character followed 540 by the value of /port/. 542 5. The value of /resource name/. 544 -> If the entry's name is "websocket-protocol" 545 If there was a /protocol/ specified, and the value is not 546 exactly equal to /protocol/, then fail the Web Socket 547 connection and abort these steps. (If no /protocol/ was 548 specified, the header is ignored.) 550 -> If the entry's name is "set-cookie" or "set-cookie2" or 551 another cookie-related header name 552 Handle the cookie as defined by the appropriate spec, with 553 the resource being the one with the host /host/, the port 554 /port/, the path (and possibly query parameters) /resource 555 name/, and the scheme |http| if /secure/ is false and |https| 556 if /secure/ is true. [RFC2109] [RFC2965] 558 -> Any other name 559 Ignore it. 561 24. The *Web Socket connection is established*. Now the user agent 562 must send and receive to and from the connection as described in 563 the next section. 565 To *fail the Web Socket connection*, the user agent must close the 566 Web Socket connection, and may report the problem to the user (which 567 would be especially useful for developers). However, user agents 568 must not convey the failure information to the script that attempted 569 the connection in a way distinguishable from the Web Socket being 570 closed normally. 572 3.2. Data framing 574 Once a Web Socket connection is established, the user agent must run 575 through the following state machine for the bytes sent by the server. 577 1. Try to read a byte from the server. Let /frame type/ be that 578 byte. 580 If no byte could be read because the Web Socket connection is 581 closed, then abort. 583 2. Handle the /frame type/ byte as follows: 585 If the high-order bit of the /frame type/ byte is set (i.e. if 586 /frame type/ _and_ed with 0x80 returns 0x80) 587 Run these steps. If at any point during these steps a read is 588 attempted but fails because the Web Socket connection is 589 closed, then abort. 591 1. Let /length/ be zero. 593 2. _Length_: Read a byte, let /b/ be that byte. 595 3. Let /b_v/ be integer corresponding to the low 7 bits of 596 /b/ (the value you would get by _and_ing /b/ with 0x7f). 598 4. Multiply /length/ by 128, add /b_v/ to that result, and 599 store the final result in /length/. 601 5. If the high-order bit of /b/ is set (i.e. if /b/ _and_ed 602 with 0x80 returns 0x80), then return to the step above 603 labeled _length_. 605 6. Read /length/ bytes. 607 7. Discard the read bytes. 609 If the high-order bit of the /frame type/ byte is _not_ set (i.e. 610 if /frame type/ _and_ed with 0x80 returns 0x00) 611 Run these steps. If at any point during these steps a read is 612 attempted but fails because the Web Socket connection is 613 closed, then abort. 615 1. Let /raw data/ be an empty byte array. 617 2. _Data_: Read a byte, let /b/ be that byte. 619 3. If /b/ is not 0xff, then append /b/ to /raw data/ and 620 return to the previous step (labeled _data_). 622 4. Interpret /raw data/ as a UTF-8 string, and store that 623 string in /data/. 625 5. If /frame type/ is 0x00, then *a message has been 626 received* with text /data/. Otherwise, discard the data. 628 3. Return to the first step to read the next byte. 630 If the user agent is faced with content that is too large to be 631 handled appropriately, then it must fail the Web Socket connection. 633 Once a Web Socket connection is established, the user agent must use 634 the following steps to *send /data/ using the Web Socket*: 636 1. Send a 0x00 byte to the server. 638 2. Encode /data/ using UTF-8 and send the resulting byte stream to 639 the server. 641 3. Send a 0xff byte to the server. 643 If at any point there is a fatal problem with sending data to the 644 server, the user agent must fail the Web Socket connection. 646 3.3. Handling errors in UTF-8 648 When a client is to interpret a byte stream as UTF-8 but finds that 649 the byte stream is not in fact a valid UTF-8 stream, then any bytes 650 or sequences of bytes that are not valid UTF-8 sequences must be 651 interpreted as a U+FFFD REPLACEMENT CHARACTER. 653 4. Server-side requirements 655 _This section only applies to servers._ 657 4.1. Minimal handshake 659 NOTE: This section describes the minimal requirements for a server- 660 side implementation of Web Sockets. 662 Listen on a port for TCP/IP. Upon receiving a connection request, 663 open a connection and send the following bytes back to the client: 665 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 666 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 667 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 668 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 669 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 670 61 64 65 0d 0a 672 Send the string "WebSocket-Origin" followed by a U+003A COLON (":") 673 followed by the ASCII serialization of the origin from which the 674 server is willing to accept connections, followed by a CRLF pair 675 (0x0d 0x0a). 677 For instance: 679 WebSocket-Origin: http://example.com 681 Send the string "WebSocket-Location" followed by a U+003A COLON (":") 682 followed by the URL of the Web Socket script, followed by a CRLF pair 683 (0x0d 0x0a). 685 For instance: 687 WebSocket-Location: ws://example.com:80/demo 689 Send another CRLF pair (0x0d 0x0a). 691 Read data from the client until four bytes 0x0d 0x0a 0x0d 0x0a are 692 read. This data must either be discarded or handled as described in 693 the following section describing the handshake details. 695 If the connection isn't dropped at this point, go to the data framing 696 section. 698 4.2. Handshake details 700 The previous section ignores the data that is transmitted by the 701 client during the handshake. 703 The data sent by the client consists of a number of fields separated 704 by CR LF pairs (bytes 0x0d 0x0a). 706 The first field consists of three tokens separated by space 707 characters (byte 0x20). The middle token is the path being opened. 708 If the server supports multiple paths, then the server should echo 709 the value of this field in the initial handshake, as part of the URL 710 given on the |WebSocket-Location| line (after the appropriate scheme 711 and host). 713 If the first field does not have three tokens, the server should 714 abort the connection as it probably represents an errorneous client. 716 The remaining fields consist of name-value pairs, with the name part 717 separated from the value part by a colon and a space (bytes 0x3a 718 0x20). Of these, several are interesting: 720 Host (bytes 48 6f 73 74) 721 The value gives the hostname that the client intended to use when 722 opening the Web Socket. It would be of interest in particular to 723 virtual hosting environments, where one server might serve 724 multiple hosts, and might therefore want to return different data. 726 The right host has to be output as part of the URL given on the 727 |WebSocket-Location| line of the handshake described above, to 728 verify that the server knows that it is really representing that 729 host. 731 Origin (bytes 4f 72 69 67 69 6e) 732 The value gives the scheme, hostname, and port (if it's not the 733 default port for the given scheme) of the page that asked the 734 client to open the Web Socket. It would be interesting if the 735 server's operator had deals with operators of other sites, since 736 the server could then decide how to respond (or indeed, _whether_ 737 to respond) based on which site was requesting a connection. 739 If the server supports connections from more than one origin, then 740 the server should echo the value of this field in the initial 741 handshake, on the |WebSocket-Origin| line. 743 Other fields 744 Other fields can be used, such as "Cookie" or "Authorization", for 745 authentication purposes. 747 Any fields that lack the colon-space separator should be discarded 748 and may cause the server to disconnect. 750 4.3. Data framing 752 NOTE: This section only describes how to handle content that this 753 specification allows user agents to send (text). It doesn't handle 754 any arbitrary content in the same way that the requirements on user 755 agents defined earlier handle any content including possible future 756 extensions to the protocols. 758 The server must run through the following steps to process the bytes 759 sent by the client: 761 1. Read a byte from the client. Assuming everything is going 762 according to plan, it will be a 0x00 byte. If the byte is not a 763 0x00 byte, then the server may disconnect. 765 2. Let /raw data/ be an empty byte array. 767 3. _Data_: Read a byte, let /b/ be that byte. 769 4. If /b/ is not 0xff, then append /b/ to /raw data/ and return to 770 the previous step (labeled _data_). 772 5. Interpret /raw data/ as a UTF-8 string, and apply whatever 773 server-specific processing is to occur for the resulting string. 775 6. Return to the first step to read the next byte. 777 The server must run through the following steps to send strings to 778 the client: 780 1. Send a 0x00 byte to the client to indicate the start of a string. 782 2. Encode /data/ using UTF-8 and send the resulting byte stream to 783 the client. 785 3. Send a 0xff byte to the client to indicate the end of the 786 message. 788 5. Closing the connection 790 To *close the Web Socket connection*, either the user agent or the 791 server closes the TCP/IP connection. There is no closing handshake. 792 Whether the user agent or the server closes the connection, it is 793 said that the *Web Socket connection is closed*. 795 Servers may close the Web Socket connection whenever desired. 797 User agents should not close the Web Socket connection arbitrarily. 799 6. Security considerations 801 ** ISSUE ** ... 803 7. IANA considerations 805 ** ISSUE ** ...(two URI schemes, two ports, HTTP Upgrade keyword) 807 8. Normative References 809 [HTML5] Hickson, I., "HTML5", July 2009. 811 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 812 Mechanism", RFC 2109, February 1997. 814 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 815 Requirement Levels", BCP 14, RFC 2119, March 1997. 817 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 818 RFC 2246, January 1999. 820 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 821 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 822 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 824 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 825 Mechanism", RFC 2965, October 2000. 827 Author's Address 829 Ian Hickson 830 Google, Inc. 832 Email: ian@hixie.ch 833 URI: http://ln.hixie.ch/