idnits 2.17.1 draft-hixie-thewebsocketprotocol-35.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 16, 2009) is 5367 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' -- Possible downref: Non-RFC (?) normative reference: ref. 'ORIGIN' ** Obsolete normative reference: RFC 2109 (Obsoleted by RFC 2965) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2965 (Obsoleted by RFC 6265) -- Possible downref: Non-RFC (?) normative reference: ref. 'WEBADDRESSES' Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 4 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 16, 2009 5 Expires: February 17, 2010 7 The Web Socket protocol 8 draft-hixie-thewebsocketprotocol-35 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 17, 2010. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 This protocol enables two-way communication between a user agent 47 running untrusted code running in a controlled environment to a 48 remote host that understands the protocol. It is intended to fail to 49 communicate with servers of pre-existing protocols like SMTP or HTTP, 50 while allowing HTTP servers to opt-in to supporting this protocol if 51 desired. It is designed to be easy to implement on the server side. 53 Author's note 55 This document is automatically generated from the same source 56 document as the HTML5 specification. [HTML5] 58 Please send feedback to either the hybi@ietf.org list or the 59 whatwg@whatwg.org list. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.1. Security model . . . . . . . . . . . . . . . . . . . . . . 4 65 1.2. Relationship to TCP/IP and HTTP . . . . . . . . . . . . . 4 66 1.3. Establishing a connection . . . . . . . . . . . . . . . . 5 67 1.4. The Web Socket protocol . . . . . . . . . . . . . . . . . 5 68 2. Conformance requirements . . . . . . . . . . . . . . . . . . . 7 69 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 70 3. Web Socket URLs . . . . . . . . . . . . . . . . . . . . . . . 8 71 3.1. Parsing Web Socket URLs . . . . . . . . . . . . . . . . . 8 72 3.2. Constructing Web Socket URLs . . . . . . . . . . . . . . . 9 73 4. Client-side requirements . . . . . . . . . . . . . . . . . . . 10 74 4.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 10 75 4.2. Data framing . . . . . . . . . . . . . . . . . . . . . . . 18 76 4.3. Closing the connection . . . . . . . . . . . . . . . . . . 19 77 4.4. Handling errors in UTF-8 . . . . . . . . . . . . . . . . . 19 78 5. Server-side requirements . . . . . . . . . . . . . . . . . . . 21 79 5.1. Minimal handshake . . . . . . . . . . . . . . . . . . . . 21 80 5.2. Handshake details . . . . . . . . . . . . . . . . . . . . 22 81 5.3. Data framing . . . . . . . . . . . . . . . . . . . . . . . 23 82 6. Closing the connection . . . . . . . . . . . . . . . . . . . . 24 83 7. Security considerations . . . . . . . . . . . . . . . . . . . 25 84 8. IANA considerations . . . . . . . . . . . . . . . . . . . . . 26 85 8.1. Registration of ws: scheme . . . . . . . . . . . . . . . . 26 86 8.2. Registration of wss: scheme . . . . . . . . . . . . . . . 26 87 8.3. Registration of ports 81 and 815 . . . . . . . . . . . . . 27 88 8.4. Registration of the "WebSocket" HTTP Upgrade keyword . . . 27 89 9. Using the Web Socket protocol from other specifications . . . 29 90 10. Normative References . . . . . . . . . . . . . . . . . . . . . 30 91 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 31 93 1. Introduction 95 _This section is non-normative._ 97 The Web Socket protocol is designed on the principle that there 98 should be minimal framing (the only framing that exists is to make 99 the protocol frame-based instead of stream-based, and to support a 100 distinction between Unicode text and binary frames). It is expected 101 that metadata would be layered on top of Web Socket by the 102 application layer, in the same way that metadata is layered on top of 103 TCP/IP by the application layer (HTTP). 105 Conceptually, Web Socket is really just a layer on top of TCP/IP that 106 adds a Web "origin"-based security model for browsers; adds an 107 addressing and protocol naming mechanism to support multiple services 108 on one port and multiple host names on one IP address; and layers a 109 framing mechanism on top of TCP to get back to the IP packet 110 mechanism that TCP is built on, but without length limits. Other 111 than that, it adds nothing. Basically it is intended to be as close 112 as possible to just exposing raw TCP/IP to script as possible given 113 the constraints of the Web. It's also designed in such a way that its 114 servers can share a port with HTTP servers, by having its handshake 115 be a valid HTTP Upgrade handshake also. 117 1.1. Security model 119 _This section is non-normative._ 121 The Web Socket protocol uses the origin model used by Web browsers to 122 restrict which Web pages can contact a Web Socket server when the Web 123 Socket protocol is used from a Web page. Naturally, when the Web 124 Socket protocol is used directly (not from a Web page), the origin 125 model is not useful, as the client can provide any arbitrary origin 126 string. 128 1.2. Relationship to TCP/IP and HTTP 130 _This section is non-normative._ 132 The Web Socket protocol is an independent TCP-based protocol. Its 133 only relationship to HTTP is that its handshake is interpreted by 134 HTTP servers as an Upgrade request. 136 The Web Socket protocol by default uses port 81 for regular Web 137 Socket connections and port 815 for Web Socket connections tunneled 138 over TLS. 140 1.3. Establishing a connection 142 _This section is non-normative._ 144 There are several options for establishing a Web Socket connection. 146 The simplest method is to use port 81 to get a direct connection to a 147 Web Socket server. However, this port may be blocked by firewalls. 149 The second simplest method is to use TLS encryption and port 815 to 150 connect directly to a Web Socket server. This is the preferred 151 solution, as it is secure and correct. However, TLS encryption can 152 be computationally expensive, and port 815 might also be blocked by 153 firewalls. 155 To avoid firewalls, ports 80 and 443 might be used instead. These 156 are the HTTP and HTTPS ports. Port 80 traffic, however, will often 157 be intercepted by HTTP proxies, which can lead to the connection 158 failing to be established. 160 Port 443, using encryption, is therefore the most reliable solution. 161 It is unlikely to be blocked by a firewall or intercepted by a proxy. 162 However, again, TLS encryption can be computationally expensive. 164 When a connection is to be made to a port that is shared by an HTTP 165 server (a situation that is quite likely to occur with traffic to 166 ports 80 and 443), the connection will appear to the HTTP server to 167 be a regular GET request with an Upgrade offer. In relatively simple 168 setups with just one IP address and a single server for all traffic 169 to a single hostname, this might allow a practical way for systems 170 based on the Web Socket protocol to be deployed. In more elaborate 171 setups (e.g. with load balancers and multiple servers), a dedicated 172 set of hosts for Web Socket connections separate from the HTTP 173 servers is probably easier to manage. 175 1.4. The Web Socket protocol 177 _This section is non-normative._ 179 The protocol has two parts: a handshake, and then the data transfer. 181 The handshake from the client looks as follows: 183 GET /demo HTTP/1.1 184 Upgrade: WebSocket 185 Connection: Upgrade 186 Host: example.com:81 187 Origin: http://example.com 188 WebSocket-Protocol: sample 190 The handshake from the server looks as follows: 192 HTTP/1.1 101 Web Socket Protocol Handshake 193 Upgrade: WebSocket 194 Connection: Upgrade 195 WebSocket-Origin: http://example.com 196 WebSocket-Location: ws://example.com/demo 197 WebSocket-Protocol: sample 199 Once the client and server have both sent their handshakes, and if 200 the handshake was successful, then the data transfer part starts. 201 This is a two-way communication channel where each side can, 202 independently from the other, send data at will. 204 Data is sent in the form of UTF-8 text. Each frame of data starts 205 with a 0x00 byte and ends with a 0xFF byte, with the UTF-8 text in 206 between. 208 The Web Socket protocol uses this framing so that specifications that 209 use the Web Socket protocol can expose such connections using an 210 event-based mechanism instead of requiring users of those 211 specifications to implement buffering and piecing together of 212 messages manually. 214 2. Conformance requirements 216 All diagrams, examples, and notes in this specification are non- 217 normative, as are all sections explicitly marked non-normative. 218 Everything else in this specification is normative. 220 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 221 "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this 222 document are to be interpreted as described in RFC2119. For 223 readability, these words do not appear in all uppercase letters in 224 this specification. [RFC2119] 226 Requirements phrased in the imperative as part of algorithms (such as 227 "strip any leading space characters" or "return false and abort these 228 steps") are to be interpreted with the meaning of the key word 229 ("must", "should", "may", etc) used in introducing the algorithm. 231 Conformance requirements phrased as algorithms or specific steps may 232 be implemented in any manner, so long as the end result is 233 equivalent. (In particular, the algorithms defined in this 234 specification are intended to be easy to follow, and not intended to 235 be performant.) 237 Implementations may impose implementation-specific limits on 238 otherwise unconstrained inputs, e.g. to prevent denial of service 239 attacks, to guard against running out of memory, or to work around 240 platform-specific limitations. 242 The conformance classes defined by this specification are user agents 243 and servers. 245 2.1. Terminology 247 *Converting a string to ASCII lowercase* means replacing all 248 characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER 249 A to LATIN CAPITAL LETTER Z) with the corresponding characters in the 250 range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL 251 LETTER Z). 253 The term "URL" is used in this section in a manner consistent with 254 the terminology used in HTML, namely, to denote a string that might 255 or might not be a valid URI or IRI and to which certain error 256 handling behaviors will be applied when the string is parsed. 257 [HTML5] 259 3. Web Socket URLs 261 3.1. Parsing Web Socket URLs 263 The steps to *parse a Web Socket URL's components* from a string 264 /url/ are as follows. These steps return either a /host/, a /port/, 265 a /resource name/, and a /secure/ flag, or they fail. 267 1. Parse the /url/ string using the parse a Web address algorithm 268 defined by the Web addresses specification. [WEBADDRESSES] 270 2. If the previous step failed, or if /url/ does not have a 271 component whose value is either "ws" or "wss", when 272 compared in an ASCII case-insensitive manner, then fail this 273 algorithm. 275 3. If /protocol/ is specified but is either the empty string or 276 contains characters that are not in the range U+0021 .. U+007E, 277 then fail this algorithm. 279 4. If the component of /url/ is "ws", set /secure/ to 280 false; otherwise, the component is "wss", set /secure/ 281 to true. 283 5. Let /host/ be the value of the component of /url/, 284 converted to ASCII lowercase. 286 6. If /url/ has a component, then let /port/ be that 287 component's value; otherwise, there is no explicit /port/. 289 7. If there is no explicit /port/, then: if /secure/ is false, let 290 /port/ be 81, otherwise let /port/ be 815. 292 8. Let /resource name/ be the value of the component (which 293 might be empty) of /url/. 295 9. If /resource name/ is the empty string, set it to a single 296 character U+002F SOLIDUS (/). 298 10. If /url/ has a component, then append a single U+003F 299 QUESTION MARK (?) character to /resource name/, followed by the 300 value of the component. 302 11. Return /host/, /port/, /resource name/, and /secure/. 304 3.2. Constructing Web Socket URLs 306 The steps to *construct a Web Socket URL* from a /host/, a /port/, a 307 /resource name/, and a /secure/ flag, are as follows: 309 1. Let /url/ be the empty string. 311 2. If the /secure/ flag is false, then append the string "ws://" to 312 /url/. Otherwise, append the string "wss://" to /url/. 314 3. Append /host/ to /url/. 316 4. If the /secure/ flag is false and port is not 81, or if the 317 /secure/ flag is true and port is not 815, then append the string 318 ":" followed by /port/ to /url/. 320 5. Append /resource name/ to /url/. 322 6. Return /url/. 324 4. Client-side requirements 326 _This section only applies to user agents, not to servers._ 328 NOTE: This specification doesn't currently define a limit to the 329 number of simultaneous connections that a client can establish to a 330 server. 332 4.1. Handshake 334 When the user agent is to *establish a Web Socket connection* to a 335 host /host/, on a port /port/, from an origin whose ASCII 336 serialization is /origin/, with a flag /secure/, with a string giving 337 a /resource name/, and optionally with a string giving a /protocol/, 338 it must run the following steps. The /resource name/ string must 339 start with a U+002F SOLIDUS (/) character. [ORIGIN] 341 1. If the user agent already has a Web Socket connection to the 342 remote host (IP address) identified by /host/, even if known by 343 another name, wait until that connection has been established or 344 for that connection to have failed. 346 NOTE: This makes it harder for a script to perform a denial of 347 service attack by just opening a large number of Web Socket 348 connections to a remote host. 350 NOTE: There is no limit to the number of established Web Socket 351 connections a user agent can have with a single remote host. 352 Servers can refuse to connect users with an excessive number of 353 connections, or disconnect resource-hogging users when suffering 354 high load. 356 2. _Connect_: If the user agent is configured to use a proxy when 357 using the Web Socket protocol to connect to host /host/ and/or 358 port /port/, then connect to that proxy and ask it to open a 359 TCP/IP connection to the host given by /host/ and the port given 360 by /port/. 362 EXAMPLE: For example, if the user agent uses an HTTP proxy 363 for all traffic, then if it was to try to connect to port 80 364 on server example.com, it might send the following lines to 365 the proxy server: 367 CONNECT example.com:80 HTTP/1.1 368 Host: example.com 370 If there was a password, the connection might look like: 372 CONNECT example.com:80 HTTP/1.1 373 Host: example.com 374 Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE= 376 Otherwise, if the user agent is not configured to use a proxy, 377 then open a TCP/IP connection to the host given by /host/ and 378 the port given by /port/. 380 NOTE: Implementations that do not expose explicit UI for 381 selecting a proxy for Web Socket connections separate from other 382 proxies are encouraged to use a SOCKS proxy for Web Socket 383 connections, if available, or failing that, to prefer the proxy 384 configured for HTTPS connections over the proxy configured for 385 HTTP connections. 387 For the purpose of proxy autoconfiguration scripts, the URL to 388 pass the function must be constructed from /host/, /port/, 389 /resource name/, and the /secure/ flag using the steps to 390 construct a Web Socket URL. 392 NOTE: The WebSocket protocol can be identified in proxy 393 autoconfiguration scripts from the scheme ("ws:" for unencrypted 394 connections and "wss:" for encrypted connections). 396 3. If the connection could not be opened, then fail the Web Socket 397 connection and abort these steps. 399 4. If /secure/ is true, perform a TLS handshake over the 400 connection. If this fails (e.g. the server's certificate could 401 not be verified), then fail the Web Socket connection and abort 402 these steps. Otherwise, all further communication on this 403 channel must run through the encrypted tunnel. [RFC2246] 405 5. Send the following bytes to the remote side (the server): 407 47 45 54 20 409 Send the /resource name/ value, encoded as US-ASCII. 411 Send the following bytes: 413 20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61 414 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43 415 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61 416 64 65 0d 0a 418 NOTE: The string "GET ", the path, " HTTP/1.1", CRLF, the string 419 "Upgrade: WebSocket", CRLF, and the string "Connection: 421 Upgrade", CRLF. 423 6. Send the following bytes: 425 48 6f 73 74 3a 20 427 Send the /host/ value, converted to ASCII lowercase, and encoded 428 as US-ASCII. 430 If /secure/ is false, and /port/ is not 80, or if /secure/ is 431 true, and /port/ is not 443, then send an 0x3a byte (":") 432 followed by the value of /port/, expressed as a base-ten 433 integer, encoded as US-ASCII. 435 Send the following bytes: 437 0d 0a 439 NOTE: The string "Host: ", the host, and CRLF. 441 7. Send the following bytes: 443 4f 72 69 67 69 6e 3a 20 445 Send the /origin/ value, converted to ASCII lowercase, encoded 446 as US-ASCII. [ORIGIN] 448 NOTE: The /origin/ value is a string that was passed to this 449 algorithm. 451 Send the following bytes: 453 0d 0a 455 NOTE: The string "Origin: ", the origin, and CRLF. 457 8. If there is no /protocol/, then skip this step. 459 Otherwise, send the following bytes: 461 57 65 62 53 6f 63 6b 65 74 2d 50 72 6f 74 6f 63 462 6f 6c 3a 20 464 Send the /protocol/ value, encoded as US-ASCII. 466 Send the following bytes: 468 0d 0a 470 NOTE: The string "WebSocket-Protocol: ", the protocol, and CRLF. 472 9. If the client has any authentication information or cookies that 473 would be relevant to a resource accessed over HTTP, if /secure/ 474 is false, or HTTPS, if it is true, on host /host/, port /port/, 475 with /resource name/ as the path (and possibly query 476 parameters), then HTTP headers that would be appropriate for 477 that information should be sent at this point. [RFC2616] 478 [RFC2109] [RFC2965] 480 Each header must be on a line of its own (each ending with a CR 481 LF sequence). For the purposes of this step, each header must 482 not be split into multiple lines (despite HTTP otherwise 483 allowing this with continuation lines). 485 EXAMPLE: For example, if the server had a username and 486 password that applied to |http://example.com/socket|, and the 487 Web Socket was being opened to |ws://example.com:80/socket|, 488 it could send them: 490 Authorization: Basic d2FsbGU6ZXZl 492 However, it would not send them if the Web Socket was being 493 opened to |ws://example.com/socket|, as that uses a different 494 port (81, not 80). 496 10. Send the following bytes: 498 0d 0a 500 NOTE: Just a CRLF (a blank line). 502 11. Read bytes from the server until either the connection closes, 503 or a 0x0a byte is read. Let /header/ be these bytes, including 504 the 0x0a byte. 506 If /header/ is not at least two bytes long, or if the last two 507 bytes aren't 0x0d and 0x0a respectively, then fail the Web 508 Socket connection and abort these steps. 510 User agents may apply a timeout to this step, failing the Web 511 Socket connection if the server does not send back data in a 512 suitable time period. 514 12. If /header/ consists of 44 bytes that exactly match the 515 following, then let /mode/ be _normal_. 517 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 518 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 519 20 48 61 6e 64 73 68 61 6b 65 0d 0a 521 NOTE: The string "HTTP/1.1 101 Web Socket Protocol Handshake" 522 followed by a CRLF pair. 524 Otherwise, let /code/ be the substring of /header/ that starts 525 from the byte after the first 0x20 byte, and ends with the byte 526 before the second 0x20 byte. If there are not at least two 0x20 527 bytes in /header/, then fail the Web Socket connection and abort 528 these steps. 530 If /code/, interpreted as ASCII, is "401", then let /mode/ be 531 _authenticate_. 533 Otherwise, fail the Web Socket connection and abort these steps. 535 13. If /mode/ is _normal_, then read 41 bytes from the server. 537 If the connection closes before 41 bytes are received, or if the 538 41 bytes aren't exactly equal to the following bytes, then fail 539 the Web Socket connection and abort these steps. 541 55 70 67 72 61 64 65 3a 20 57 65 62 53 6f 63 6b 542 65 74 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 543 55 70 67 72 61 64 65 0d 0a 545 NOTE: The string "Upgrade: WebSocket", CRLF, the string 546 "Connection: Upgrade", CRLF. 548 User agents may apply a timeout to this step, failing the Web 549 Socket connection if the server does not respond with the above 550 bytes within a suitable time period. 552 NOTE: This step is skipped if /mode/ is _authenticate_. 554 14. Let /headers/ be a list of name-value pairs, initially empty. 556 15. _Header_: Let /name/ and /value/ be empty byte arrays. 558 16. Read a byte from the server. 560 If the connection closes before this byte is received, then fail 561 the Web Socket connection and abort these steps. 563 Otherwise, handle the byte as described in the appropriate entry 564 below: 566 -> If the byte is 0x0d (ASCII CR) 567 If the /name/ byte array is empty, then jump to the headers 568 processing step. Otherwise, fail the Web Socket connection 569 and abort these steps. 571 -> If the byte is 0x0a (ASCII LF) 572 Fail the Web Socket connection and abort these steps. 574 -> If the byte is 0x3a (ASCII ":") 575 Move on to the next step. 577 -> If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z") 578 Append a byte whose value is the byte's value plus 0x20 to 579 the /name/ byte array and redo this step for the next byte. 581 -> Otherwise 582 Append the byte to the /name/ byte array and redo this step 583 for the next byte. 585 NOTE: This reads a header name, terminated by a colon, 586 converting upper-case ASCII letters to lowercase, and aborting 587 if a stray CR or LF is found. 589 17. Read a byte from the server. 591 If the connection closes before this byte is received, then fail 592 the Web Socket connection and abort these steps. 594 Otherwise, handle the byte as described in the appropriate entry 595 below: 597 -> If the byte is 0x20 (ASCII space) 598 Ignore the byte and move on to the next step. 600 -> Otherwise 601 Treat the byte as described by the list in the next step, 602 then move on to that next step for real. 604 NOTE: This skips past a space character after the colon, if 605 necessary. 607 18. Read a byte from the server. 609 If the connection closes before this byte is received, then fail 610 the Web Socket connection and abort these steps. 612 Otherwise, handle the byte as described in the appropriate entry 613 below: 615 -> If the byte is 0x0d (ASCII CR) 616 Move on to the next step. 618 -> If the byte is 0x0a (ASCII LF) 619 Fail the Web Socket connection and abort these steps. 621 -> Otherwise 622 Append the byte to the /value/ byte array and redo this step 623 for the next byte. 625 NOTE: This reads a header value, terminated by a CRLF. 627 19. Read a byte from the server. 629 If the connection closes before this byte is received, or if the 630 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 631 connection and abort these steps. 633 NOTE: This skips past the LF byte of the CRLF after the header. 635 20. Append an entry to the /headers/ list that has the name given by 636 the string obtained by interpreting the /name/ byte array as a 637 UTF-8 byte stream and the value given by the string obtained by 638 interpreting the /value/ byte array as a UTF-8 byte stream. 640 21. Return to the "Header" step above. 642 22. _Headers processing_: Read a byte from the server. 644 If the connection closes before this byte is received, or if the 645 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 646 connection and abort these steps. 648 NOTE: This skips past the LF byte of the CRLF after the blank 649 line after the headers. 651 23. If /mode/ is _normal_, then: If there is not exactly one entry 652 in the /headers/ list whose name is "websocket-origin", or if 653 there is not exactly one entry in the /headers/ list whose name 654 is "websocket-location", or if the /protocol/ was specified but 655 there is not exactly one entry in the /headers/ list whose name 656 is "websocket-protocol", or if there are any entries in the 657 /headers/ list whose names are the empty string, then fail the 658 Web Socket connection and abort these steps. Otherwise, handle 659 each entry in the /headers/ list as follows: 661 -> If the entry's name is "websocket-origin" 662 If the value is not exactly equal to /origin/, converted to 663 ASCII lowercase, then fail the Web Socket connection and 664 abort these steps. [ORIGIN] 666 -> If the entry's name is "websocket-location" 667 If the value is not exactly equal to a string obtained from 668 the steps to construct a Web Socket URL from /host/, /port/, 669 /resource name/, and the /secure/ flag, then fail the Web 670 Socket connection and abort these steps. 672 -> If the entry's name is "websocket-protocol" 673 If there was a /protocol/ specified, and the value is not 674 exactly equal to /protocol/, then fail the Web Socket 675 connection and abort these steps. (If no /protocol/ was 676 specified, the header is ignored.) 678 -> If the entry's name is "set-cookie" or "set-cookie2" or 679 another cookie-related header name 680 Handle the cookie as defined by the appropriate spec, with 681 the resource being the one with the host /host/, the port 682 /port/, the path (and possibly query parameters) /resource 683 name/, and the scheme |http| if /secure/ is false and |https| 684 if /secure/ is true. [RFC2109] [RFC2965] 686 -> Any other name 687 Ignore it. 689 If /mode/ is _authenticate_, then: If there is not exactly one 690 entry in the /headers/ list whose name is "www-authenticate", 691 then fail the Web Socket connection and abort these steps. 692 Otherwise, handle each entry in the /headers/ list as follows: 694 -> If the entry's name is "www-authenticate" 695 Obtain credentials in a manner consistent with the 696 requirements for handling the |WWW-Authenticate| header in 697 HTTP, and then close the connection (if the server has not 698 already done so) and jump back to the step labeled _connect_, 699 including the relevant authentication headers in the new 700 request. [RFC2616] 702 -> Any other name 703 Ignore it. 705 24. The *Web Socket connection is established*. Now the user agent 706 must send and receive to and from the connection as described in 707 the next section. 709 4.2. Data framing 711 Once a Web Socket connection is established, the user agent must run 712 through the following state machine for the bytes sent by the server. 714 1. Try to read a byte from the server. Let /frame type/ be that 715 byte. 717 If no byte could be read because the Web Socket connection is 718 closed, then abort. 720 2. Handle the /frame type/ byte as follows: 722 If the high-order bit of the /frame type/ byte is set (i.e. if 723 /frame type/ _and_ed with 0x80 returns 0x80) 724 Run these steps. If at any point during these steps a read is 725 attempted but fails because the Web Socket connection is 726 closed, then abort. 728 1. Let /length/ be zero. 730 2. _Length_: Read a byte, let /b/ be that byte. 732 3. Let /b_v/ be integer corresponding to the low 7 bits of 733 /b/ (the value you would get by _and_ing /b/ with 0x7f). 735 4. Multiply /length/ by 128, add /b_v/ to that result, and 736 store the final result in /length/. 738 5. If the high-order bit of /b/ is set (i.e. if /b/ _and_ed 739 with 0x80 returns 0x80), then return to the step above 740 labeled _length_. 742 6. Read /length/ bytes. 744 7. Discard the read bytes. 746 If the high-order bit of the /frame type/ byte is _not_ set (i.e. 747 if /frame type/ _and_ed with 0x80 returns 0x00) 748 Run these steps. If at any point during these steps a read is 749 attempted but fails because the Web Socket connection is 750 closed, then abort. 752 1. Let /raw data/ be an empty byte array. 754 2. _Data_: Read a byte, let /b/ be that byte. If the client 755 runs out of resources for buffering the incoming data, or 756 hits an artificial resource limit intended to avoid 757 resource starvation, then it must fail the Web Socket 758 connection and abort these steps. 760 3. If /b/ is not 0xff, then append /b/ to /raw data/ and 761 return to the previous step (labeled _data_). 763 4. Interpret /raw data/ as a UTF-8 string, and store that 764 string in /data/. 766 5. If /frame type/ is 0x00, then *a message has been 767 received* with text /data/. Otherwise, discard the data. 769 3. Return to the first step to read the next byte. 771 If the user agent is faced with content that is too large to be 772 handled appropriately, then it must fail the Web Socket connection. 774 Once a Web Socket connection is established, the user agent must use 775 the following steps to *send /data/ using the Web Socket*: 777 1. Send a 0x00 byte to the server. 779 2. Encode /data/ using UTF-8 and send the resulting byte stream to 780 the server. 782 3. Send a 0xff byte to the server. 784 If at any point there is a fatal problem with sending data to the 785 server, the user agent must fail the Web Socket connection. 787 4.3. Closing the connection 789 To *fail the Web Socket connection*, the user agent must close the 790 Web Socket connection, and may report the problem to the user (which 791 would be especially useful for developers). However, user agents 792 must not convey the failure information to the script that attempted 793 the connection in a way distinguishable from the Web Socket being 794 closed normally. 796 Except as indicated above or as specified by the application layer 797 (e.g. a script using the Web Socket API), user agents should not 798 close the connection. 800 4.4. Handling errors in UTF-8 802 When a client is to interpret a byte stream as UTF-8 but finds that 803 the byte stream is not in fact a valid UTF-8 stream, then any bytes 804 or sequences of bytes that are not valid UTF-8 sequences must be 805 interpreted as a U+FFFD REPLACEMENT CHARACTER. 807 5. Server-side requirements 809 _This section only applies to servers._ 811 5.1. Minimal handshake 813 NOTE: This section describes the minimal requirements for a server- 814 side implementation of Web Sockets. 816 Listen on a port for TCP/IP. Upon receiving a connection request, 817 open a connection and send the following bytes back to the client: 819 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 820 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 821 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 822 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 823 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 824 61 64 65 0d 0a 826 Send the string "WebSocket-Origin" followed by a U+003A COLON (":") 827 and a U+0020 SPACE, followed by the ASCII serialization of the origin 828 from which the server is willing to accept connections, followed by a 829 CRLF pair (0x0d 0x0a). [ORIGIN] 831 For instance: 833 WebSocket-Origin: http://example.com 835 Send the string "WebSocket-Location" followed by a U+003A COLON (":") 836 and a U+0020 SPACE, followed by the URL of the Web Socket script, 837 followed by a CRLF pair (0x0d 0x0a). 839 For instance: 841 WebSocket-Location: ws://example.com:80/demo 843 NOTE: Do not include the port if it is the default port for Web 844 Socket protocol connections of the type in question (81 for 845 unencrypted connections and 815 for encrypted connections). 847 Send another CRLF pair (0x0d 0x0a). 849 Read data from the client until four bytes 0x0d 0x0a 0x0d 0x0a are 850 read. This data must either be discarded or handled as described in 851 the following section describing the handshake details. 853 If the connection isn't dropped at this point, go to the data framing 854 section. 856 5.2. Handshake details 858 The previous section ignores the data that is transmitted by the 859 client during the handshake. 861 The data sent by the client consists of a number of fields separated 862 by CR LF pairs (bytes 0x0d 0x0a). 864 The first field consists of three tokens separated by space 865 characters (byte 0x20). The middle token is the path being opened. 866 If the server supports multiple paths, then the server should echo 867 the value of this field in the initial handshake, as part of the URL 868 given on the |WebSocket-Location| line (after the appropriate scheme 869 and host). 871 If the first field does not have three tokens, the server should 872 abort the connection as it probably represents an errorneous client. 874 The remaining fields consist of name-value pairs, with the name part 875 separated from the value part by a colon and a space (bytes 0x3a 876 0x20). Of these, several are interesting: 878 Host (bytes 48 6f 73 74) 879 The value gives the hostname that the client intended to use when 880 opening the Web Socket. It would be of interest in particular to 881 virtual hosting environments, where one server might serve 882 multiple hosts, and might therefore want to return different data. 884 The right host has to be output as part of the URL given on the 885 |WebSocket-Location| line of the handshake described above, to 886 verify that the server knows that it is really representing that 887 host. 889 Origin (bytes 4f 72 69 67 69 6e) 890 The value gives the scheme, hostname, and port (if it's not the 891 default port for the given scheme) of the page that asked the 892 client to open the Web Socket. It would be interesting if the 893 server's operator had deals with operators of other sites, since 894 the server could then decide how to respond (or indeed, _whether_ 895 to respond) based on which site was requesting a connection. 897 If the server supports connections from more than one origin, then 898 the server should echo the value of this field in the initial 899 handshake, on the |WebSocket-Origin| line. 901 Other fields 902 Other fields can be used, such as "Cookie" or "Authorization", for 903 authentication purposes. 905 Any fields that lack the colon-space separator should be discarded 906 and may cause the server to disconnect. 908 5.3. Data framing 910 NOTE: This section only describes how to handle content that this 911 specification allows user agents to send (text). It doesn't handle 912 any arbitrary content in the same way that the requirements on user 913 agents defined earlier handle any content including possible future 914 extensions to the protocols. 916 The server must run through the following steps to process the bytes 917 sent by the client: 919 1. Read a byte from the client. Assuming everything is going 920 according to plan, it will be a 0x00 byte. If the byte is not a 921 0x00 byte, then the server may disconnect. 923 2. Let /raw data/ be an empty byte array. 925 3. _Data_: Read a byte, let /b/ be that byte. 927 4. If /b/ is not 0xff, then append /b/ to /raw data/ and return to 928 the previous step (labeled _data_). 930 5. Interpret /raw data/ as a UTF-8 string, and apply whatever 931 server-specific processing is to occur for the resulting string. 933 6. Return to the first step to read the next byte. 935 The server must run through the following steps to send strings to 936 the client: 938 1. Send a 0x00 byte to the client to indicate the start of a string. 940 2. Encode /data/ using UTF-8 and send the resulting byte stream to 941 the client. 943 3. Send a 0xff byte to the client to indicate the end of the 944 message. 946 6. Closing the connection 948 To *close the Web Socket connection*, either the user agent or the 949 server closes the TCP/IP connection. There is no closing handshake. 950 Whether the user agent or the server closes the connection, it is 951 said that the *Web Socket connection is closed*. 953 Servers may close the Web Socket connection whenever desired. 955 User agents should not close the Web Socket connection arbitrarily. 957 7. Security considerations 959 While this protocol is intended to be used by scripts in Web pages, 960 it can also be used directly by hosts. Such hosts are acting on 961 their own behalf, and can therefore send fake "Origin" headers, 962 misleading the server. Servers should therefore be careful about 963 assuming that they are talking directly to scripts from known 964 origins, and must consider that they might be accessed in unexpected 965 ways. In particular, a server should not trust that any input is 966 valid. 968 EXAMPLE: For example, if the server uses input as part of SQL 969 queries, all input text should be escaped before being passed to the 970 SQL server, lest the server be susceptible to SQL injection. 972 Servers that are not intended to process input from any Web page but 973 only for certain sites should verify the "Origin" header is an origin 974 they expect, and should only respond with the corresponding 975 "WebSocket-Origin" if it is an accepted origin. Servers that only 976 accept input from one origin can just send back that value in the 977 "WebSocket-Origin" header, without bothering to check the client's 978 value. 980 If at any time a server is faced with data that it does not 981 understand, or that violates some criteria by which the server 982 determines safety of input, or when the server sees a handshake that 983 does not correspond to the values the server is expecting (e.g. 984 incorrect path or origin), the server should just disconnect. It is 985 always safe to disconnect. 987 8. IANA considerations 989 8.1. Registration of ws: scheme 991 A |ws:| URL identifies a Web Socket server and resource name. 993 URI scheme name. 994 ws 996 Status. 997 Permanent. 999 URI scheme syntax. 1000 In ABNF terms using the terminals from the IRI specifications: 1001 [RFC5238] [RFC3987] 1003 "ws" ":" ihier-part [ "?" iquery ] 1005 URI scheme semantics. 1006 The only operation for this scheme is to open a connection using 1007 the Web Socket protocol. 1009 Encoding considerations. 1010 UTF-8 only. 1012 Applications/protocols that use this URI scheme name. 1013 Web Socket protocol. 1015 Interoperability considerations. 1016 None. 1018 Security considerations. 1019 See "Security considerations" section above. 1021 Contact. 1022 Ian Hickson 1024 Author/Change controller. 1025 Ian Hickson 1027 References. 1028 This document. 1030 8.2. Registration of wss: scheme 1032 A |wss:| URL identifies a Web Socket server and resource name, and 1033 indicates that traffic over that connection is to be encrypted. 1035 URI scheme name. 1036 wss 1038 Status. 1039 Permanent. 1041 URI scheme syntax. 1042 In ABNF terms using the terminals from the IRI specifications: 1043 [RFC5238] [RFC3987] 1045 "ws" ":" ihier-part [ "?" iquery ] 1047 URI scheme semantics. 1048 The only operation for this scheme is to open a connection using 1049 the Web Socket protocol, encrypted using TLS. 1051 Encoding considerations. 1052 UTF-8 only. 1054 Applications/protocols that use this URI scheme name. 1055 Web Socket protocol over TLS. 1057 Interoperability considerations. 1058 None. 1060 Security considerations. 1061 See "Security considerations" section above. 1063 Contact. 1064 Ian Hickson 1066 Author/Change controller. 1067 Ian Hickson 1069 References. 1070 This document. 1072 8.3. Registration of ports 81 and 815 1074 See IANA ticket #257454 for port 81 and IANA ticket #257455 for port 1075 815. 1077 8.4. Registration of the "WebSocket" HTTP Upgrade keyword 1079 Name of token. 1080 WebSocket 1082 Author/Change controller. 1083 Ian Hickson 1085 Contact. 1086 Ian Hickson 1088 References. 1089 This document. 1091 9. Using the Web Socket protocol from other specifications 1093 The Web Socket protocol is intended to be used by another 1094 specification to provide a generic mechanism for dynamic author- 1095 defined content, e.g. in a specification defining a scripted API. 1097 Such a specification first needs to "establish a Web Socket 1098 connection", providing that algorithm with: 1100 o The destination, consisting of a /host/ and a /port/. 1102 o A /resource name/, which allows for multiple services to be 1103 identified at one host and port. 1105 o A /secure/ flag, which is true if the connection is to be 1106 encrypted, and false otherwise. 1108 o An ASCII serialization of an origin that is being made responsible 1109 for the connection. [ORIGIN] 1111 o Optionally a string identifying a protocol that is to be layered 1112 over the Web Socket connection. 1114 The /host/, /port/, /resource name/, and /secure/ flag are usually 1115 obtained from a URL using the steps to parse a Web Socket URL's 1116 components. These steps fail if the URL does not specify a Web 1117 Socket. 1119 If a connection can be established, then it is said that the "Web 1120 Socket connection is established". 1122 If at any time the connection is to be closed, then the specification 1123 needs to use the "close the Web Socket connection" algorithm. 1125 When the connection is closed, for any reason including failure to 1126 establish the connection in the first place, it is said that the "Web 1127 Socket connection is closed". 1129 While a connection is open, the specification will need to handle the 1130 cases when "a Web Socket message has been received" with text /data/. 1132 To send some text /data/ to an open connection, the specification 1133 needs to "send /data/ using the Web Socket". 1135 10. Normative References 1137 [HTML5] Hickson, I., "HTML5", August 2009. 1139 [ORIGIN] Barth, A., Jackson, C., and I. Hickson, "The HTTP Sec-From 1140 Header", July 2009. 1142 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 1143 Mechanism", RFC 2109, February 1997. 1145 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1146 Requirement Levels", BCP 14, RFC 2119, March 1997. 1148 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1149 RFC 2246, January 1999. 1151 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1152 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1153 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1155 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 1156 Mechanism", RFC 2965, October 2000. 1158 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1159 Identifiers (IRIs)", RFC 3987, January 2005. 1161 [RFC5238] Phelan, T., "Datagram Transport Layer Security (DTLS) over 1162 the Datagram Congestion Control Protocol (DCCP)", 1163 RFC 5238, May 2008. 1165 [WEBADDRESSES] 1166 Connolly, D. and C. Sperberg-McQueen, "Web addresses in 1167 HTML 5", May 2009. 1169 Author's Address 1171 Ian Hickson 1172 Google, Inc. 1174 Email: ian@hixie.ch 1175 URI: http://ln.hixie.ch/