idnits 2.17.1 draft-hixie-thewebsocketprotocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** 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 date (January 9, 2009) is 5585 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: 7 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 Expires: July 13, 2009 January 9, 2009 6 The Web Socket protocol 7 draft-hixie-thewebsocketprotocol-00 9 Status of this Memo 11 This Internet-Draft is submitted to IETF in full conformance with the 12 provisions of BCP 78 and BCP 79. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as Internet- 17 Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet-Drafts as reference 22 material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt. 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 This Internet-Draft will expire on July 13, 2009. 32 Copyright Notice 34 Copyright (c) 2009 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 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, and is therefore a 56 subset of, the HTML5 specification produced by the WHATWG. [HTML5] 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 2. Client-side requirements . . . . . . . . . . . . . . . . . . . 5 62 2.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 5 63 2.2. Data framing . . . . . . . . . . . . . . . . . . . . . . . 10 64 3. Server-side requirements . . . . . . . . . . . . . . . . . . . 13 65 3.1. Minimal handshake . . . . . . . . . . . . . . . . . . . . 13 66 3.2. Handshake details . . . . . . . . . . . . . . . . . . . . 13 67 3.3. Data framing . . . . . . . . . . . . . . . . . . . . . . . 14 68 4. Closing the connection . . . . . . . . . . . . . . . . . . . . 16 69 5. Security considerations . . . . . . . . . . . . . . . . . . . 17 70 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 73 1. Introduction 75 ** ISSUE ** ... 77 2. Client-side requirements 79 _This section only applies to user agents, not to servers._ 81 NOTE: This specification doesn't currently define a limit to the 82 number of simultaneous connections that a client can establish to a 83 server. 85 2.1. Handshake 87 When the user agent is to *establish a Web Socket connection* to a 88 host /host/, optionally on port /port/, from an origin /origin/, with 89 a flag /secure/, and with a particular /resource name/, it must run 90 the following steps: 92 1. If there is no explicit /port/, then: if /secure/ is false, let 93 /port/ be 81, otherwise let /port/ be 815. 95 2. If the user agent is configured to use a proxy to connect to 96 host /host/ and/or port /port/, then connect to that proxy and 97 ask it to open a TCP/IP connection to the host given by /host/ 98 and the port given by /port/. 100 EXAMPLE: For example, if the user agent uses an HTTP proxy 101 for all traffic, then if it was to try to connect to port 80 102 on server example.com, it might send the following lines to 103 the proxy server: 105 CONNECT example.com HTTP/1.1 107 If there was a password, the connection might look like: 109 CONNECT example.com HTTP/1.1 110 Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE= 112 Otherwise, if the user agent is not configured to use a proxy, 113 then open a TCP/IP connection to the host given by /host/ and 114 the port given by /port/. 116 3. If the connection could not be opened, then fail the Web Socket 117 connection and abort these steps. 119 4. If /secure/ is true, perform a TLS handshake over the 120 connection. If this fails (e.g. the server's certificate could 121 not be verified), then fail the Web Socket connection and abort 122 these steps. Otherwise, all further communication on this 123 channel must run through the encrypted tunnel. [RFC2246] 125 5. Send the following bytes to the remote side (the server): 127 47 45 54 20 129 Send the /resource name/ value, encoded as US-ASCII. 131 Send the following bytes: 133 20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61 134 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43 135 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61 136 64 65 0d 0a 138 NOTE: The string "GET ", the path, " HTTP/1.1", CRLF, the string 139 "Upgrade: WebSocket", CRLF, and the string "Connection: 140 Upgrade", CRLF. 142 6. Send the following bytes: 144 48 6f 73 74 3a 20 146 Send the /host/ value, encoded as US-ASCII and converted to 147 lowercase, if it represents a host name (and not an IP address). 149 Send the following bytes: 151 0d 0a 153 NOTE: The string "Host: ", the host, and CRLF. 155 7. Send the following bytes: 157 4f 72 69 67 69 6e 3a 20 159 Send the /origin/ value, encoded as US-ASCII and converted to 160 lowercase. 162 Send the following bytes: 164 0d 0a 166 NOTE: The string "Origin: ", the origin, and CRLF. 168 8. If the client has any authentication information or cookies that 169 would be relevant to a resource accessed over HTTP, if /secure/ 170 is false, or HTTPS, if it is true, on host /host/, port /port/, 171 with /resource name/ as the path (and possibly query 172 parameters), then HTTP headers that would be appropriate for 173 that information should be sent at this point. [RFC2616] 174 [RFC2109] [RFC2965] 176 Each header must be on a line of its own (each ending with a CR 177 LF sequence). For the purposes of this step, each header must 178 not be split into multiple lines (despite HTTP otherwise 179 allowing this with continuation lines). 181 EXAMPLE: For example, if the server had a username and 182 password that applied to |http://example.com/socket|, and the 183 Web Socket was being opened to |ws://example.com:80/socket|, 184 it could send them: 186 Authorization: Basic d2FsbGU6ZXZl 188 However, it would not send them if the Web Socket was being 189 opened to |ws://example.com/socket|, as that uses a different 190 port (81, not 80). 192 9. Send the following bytes: 194 0d 0a 196 NOTE: Just a CRLF (a blank line). 198 10. Read the first 85 bytes from the server. If the connection 199 closes before 85 bytes are received, or if the first 85 bytes 200 aren't exactly equal to the following bytes, then fail the Web 201 Socket connection and abort these steps. 203 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 204 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 205 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 206 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 207 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 208 61 64 65 0d 0a 210 NOTE: The string "HTTP/1.1 101 Web Socket Protocol Handshake", 211 CRLF, the string "Upgrade: WebSocket", CRLF, the string 212 "Connection: Upgrade", CRLF. 214 11. Let /headers/ be a list of name-value pairs, initially empty. 216 12. _Header_: Let /name/ and /value/ be empty byte arrays. 218 13. Read a byte from the server. 220 If the connection closes before this byte is received, then fail 221 the Web Socket connection and abort these steps. 223 Otherwise, handle the byte as described in the appropriate entry 224 below: 226 -> If the byte is 0x0d (ASCII CR) 227 If the /name/ byte array is empty, then jump to the headers 228 processing step. Otherwise, fail the Web Socket connection 229 and abort these steps. 231 -> If the byte is 0x0a (ASCII LF) 232 Fail the Web Socket connection and abort these steps. 234 -> If the byte is 0x3a (ASCII ":") 235 Move on to the next step. 237 -> If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z") 238 Append a byte whose value is the byte's value plus 0x20 to 239 the /name/ byte array and redo this step for the next byte. 241 -> Otherwise 242 Append the byte to the /name/ byte array and redo this step 243 for the next byte. 245 NOTE: This reads a header name, terminated by a colon, 246 converting upper-case ASCII letters to lowercase, and aborting 247 if a stray CR or LF is found. 249 14. Read a byte from the server. 251 If the connection closes before this byte is received, then fail 252 the Web Socket connection and abort these steps. 254 Otherwise, handle the byte as described in the appropriate entry 255 below: 257 -> If the byte is 0x20 (ASCII space) 258 Ignore the byte and move on to the next step. 260 -> Otherwise 261 Treat the byte as described by the list in the next step, 262 then move on to that next step for real. 264 NOTE: This skips past a space character after the colon, if 265 necessary. 267 15. Read a byte from the server. 269 If the connection closes before this byte is received, then fail 270 the Web Socket connection and abort these steps. 272 Otherwise, handle the byte as described in the appropriate entry 273 below: 275 -> If the byte is 0x0d (ASCII CR) 276 Move on to the next step. 278 -> If the byte is 0x0a (ASCII LF) 279 Fail the Web Socket connection and abort these steps. 281 -> Otherwise 282 Append the byte to the /name/ byte array and redo this step 283 for the next byte. 285 NOTE: This reads a header value, terminated by a CRLF. 287 16. Read a byte from the server. 289 If the connection closes before this byte is received, or if the 290 byte is not a 0x0a byte (ASCII LF), then fail the Web Socket 291 connection and abort these steps. 293 NOTE: This skips past the LF byte of the CRLF after the header. 295 17. Append an entry to the /headers/ list that has the name given by 296 the string obtained by interpreting the /name/ byte array as a 297 UTF-8 byte stream and the value given by the string obtained by 298 interpreting the /value/ byte array as a UTF-8 byte stream. 300 18. Return to the header step above. 302 19. _Headers processing_: If there is not exactly one entry in the 303 /headers/ list whose name is "websocket-origin", or if there is 304 not exactly one entry in the /headers/ list whose name is 305 "websocket-location", or if there are any entries in the 306 /headers/ list whose names are the empty string, then fail the 307 Web Socket connection and abort these steps. 309 20. Handle each entry in the /headers/ list as follows: 311 -> If the entry's name is "websocket-origin|" 312 If the value is not exactly equal to /origin/, converted to 313 lowercase, then fail the Web Socket connection and abort 314 these steps. 316 -> If the entry's name is "websocket-location|" 317 If the value is not exactly equal to a string consisting of 318 the following components in the same order, then fail the Web 319 Socket connection and abort these steps: 321 1. The string "http" if /secure/ is false and "https" if 322 /secure/ is true 324 2. The three characters "://". 326 3. The value of /host/. 328 4. If /secure/ is false and /port/ is not 81, or if /secure/ 329 is true and /port/ is not 815: a ":" character followed 330 by the value of /port/. 332 5. The value of /resource name/. 334 -> If the entry's name is "set-cookie|" or "set-cookie2|" or 335 another cookie-related header name 336 Handle the cookie as defined by the appropriate spec, with 337 the resource being the one with the host /host/, the port 338 /port/, the path (and possibly query parameters) /resource 339 name/, and the scheme |http| if /secure/ is false and |https| 340 if /secure/ is true. [RFC2109] [RFC2965] 342 -> Any other name 343 Ignore it. 345 21. The *Web Socket connection is established*. Now the user agent 346 must send and receive to and from the connection as described in 347 the next section. 349 To *fail the Web Socket connection*, the user agent must close the 350 Web Socket connection, and may report the problem to the user (which 351 would be especially useful for developers). However, user agents 352 must not convey the failure information to the script that attempted 353 the connection in a way distinguishable from the Web Socket being 354 closed normally. 356 2.2. Data framing 358 Once a Web Socket connection is established, the user agent must run 359 through the following state machine for the bytes sent by the server. 361 1. Try to read a byte from the server. Let /frame type/ be that 362 byte. 364 If no byte could be read because the Web Socket connection is 365 closed, then abort. 367 2. Handle the /frame type/ byte as follows: 369 If the high-order bit of the /frame type/ byte is set (i.e. if 370 /frame type/ _and_ed with 0x80 returns 0x80) 371 Run these steps. If at any point during these steps a read is 372 attempted but fails because the Web Socket connection is 373 closed, then abort. 375 1. Let /length/ be zero. 377 2. _Length_: Read a byte, let /b/ be that byte. 379 3. Let /b_v/ be integer corresponding to the low 7 bits of 380 /b/ (the value you would get by _and_ing /b/ with 0x7f). 382 4. Multiply /length/ by 128, add /b_v/ to that result, and 383 store the final result in /length/. 385 5. If the high-order bit of /b/ is set (i.e. if /b/ _and_ed 386 with 0x80 returns 0x80), then return to the step above 387 labeled _length_. 389 6. Read /length/ bytes. 391 7. Discard the read bytes. 393 If the high-order bit of the /frame type/ byte is _not_ set (i.e. 394 if /frame type/ _and_ed with 0x80 returns 0x00) 395 Run these steps. If at any point during these steps a read is 396 attempted but fails because the Web Socket connection is 397 closed, then abort. 399 1. Let /raw data/ be an empty byte array. 401 2. _Data_: Read a byte, let /b/ be that byte. 403 3. If /b/ is not 0xff, then append /b/ to /raw data/ and 404 return to the previous step (labeled _data_). 406 4. Interpret /raw data/ as a UTF-8 string, and store that 407 string in /data/. 409 5. If /frame type/ is 0x00, then *a message has been 410 received* with text /data/. Otherwise, discard the data. 412 3. Return to the first step to read the next byte. 414 If the user agent is faced with content that is too large to be 415 handled appropriately, then it must fail the Web Socket connection. 417 Once a Web Socket connection is established, the user agent must use 418 the following steps to *send /data/ using the Web Socket*: 420 1. Send a 0x00 byte to the server. 422 2. Encode /data/ using UTF-8 and send the resulting byte stream to 423 the server. 425 3. Send a 0xff byte to the server. 427 3. Server-side requirements 429 _This section only applies to servers._ 431 3.1. Minimal handshake 433 NOTE: This section describes the minimal requirements for a server- 434 side implementation of Web Sockets. 436 Listen on a port for TCP/IP. Upon receiving a connection request, 437 open a connection and send the following bytes back to the client: 439 48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62 440 20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c 441 20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72 442 61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 443 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 444 61 64 65 0d 0a 446 Send the string "WebSocket-Origin" followed by a U+003A COLON (":") 447 followed by the ASCII serialization of the origin from which the 448 server is willing to accept connections, followed by a CRLF pair 449 (0x0d 0x0a). 451 For instance: 453 WebSocket-Origin: http://example.com 455 Send the string "WebSocket-Location" followed by a U+003A COLON (":") 456 followed by the URL of the Web Socket script, followed by a CRLF pair 457 (0x0d 0x0a). 459 For instance: 461 WebSocket-Location: ws://example.com:80/demo 463 Send another CRLF pair (0x0d 0x0a). 465 Read (and discard) data from the client until four bytes 0x0d 0x0a 466 0x0d 0x0a are read. 468 If the connection isn't dropped at this point, go to the data framing 469 section. 471 3.2. Handshake details 473 The previous section ignores the data that is transmitted by the 474 client during the handshake. 476 The data sent by the client consists of a number of fields separated 477 by CR LF pairs (bytes 0x0d 0x0a). 479 The first field consists of three tokens separated by space 480 characters (byte 0x20). The middle token is the path being opened. 481 If the server supports multiple paths, then the server should echo 482 the value of this field in the initial handshake, as part of the URL 483 given on the |WebSocket-Location| line (after the appropriate scheme 484 and host). 486 The remaining fields consist of name-value pairs, with the name part 487 separated from the value part by a colon and a space (bytes 0x3a 488 0x20). Of these, several are interesting: 490 Host (bytes 48 6f 73 74) 491 The value gives the hostname that the client intended to use when 492 opening the Web Socket. It would be of interest in particular to 493 virtual hosting environments, where one server might serve 494 multiple hosts, and might therefore want to return different data. 496 The right host has to be output as part of the URL given on the 497 |WebSocket-Location| line of the handshake described above, to 498 verify that the server knows that it is really representing that 499 host. 501 Origin (bytes 4f 72 69 67 69 6e) 502 The value gives the scheme, hostname, and port (if it's not the 503 default port for the given scheme) of the page that asked the 504 client to open the Web Socket. It would be interesting if the 505 server's operator had deals with operators of other sites, since 506 the server could then decide how to respond (or indeed, _whether_ 507 to respond) based on which site was requesting a connection. 509 If the server supports connections from more than one origin, then 510 the server should echo the value of this field in the initial 511 handshake, on the |WebSocket-Origin| line. 513 Other fields 514 Other fields can be used, such as "Cookie" or "Authorization", for 515 authentication purposes. 517 3.3. Data framing 519 NOTE: This section only describes how to handle content that this 520 specification allows user agents to send (text). It doesn't handle 521 any arbitrary content in the same way that the requirements on user 522 agents defined earlier handle any content including possible future 523 extensions to the protocols. 525 The server should run through the following steps to process the 526 bytes sent by the client: 528 1. Read a byte from the client. Assuming everything is going 529 according to plan, it will be a 0x00 byte. Behaviour for the 530 server is undefined if the byte is not 0x00. 532 2. Let /raw data/ be an empty byte array. 534 3. _Data_: Read a byte, let /b/ be that byte. 536 4. If /b/ is not 0xff, then append /b/ to /raw data/ and return to 537 the previous step (labeled _data_). 539 5. Interpret /raw data/ as a UTF-8 string, and apply whatever 540 server-specific processing should occur for the resulting string. 542 6. Return to the first step to read the next byte. 544 The server should run through the following steps to send strings to 545 the client: 547 1. Send a 0x00 byte to the client to indicate the start of a string. 549 2. Encode /data/ using UTF-8 and send the resulting byte stream to 550 the client. 552 3. Send a 0xff byte to the client to indicate the end of the 553 message. 555 4. Closing the connection 557 To *close the Web Socket connection*, either the user agent or the 558 server closes the TCP/IP connection. There is no closing handshake. 559 Whether the user agent or the server closes the connection, it is 560 said that the *Web Socket connection is closed*. 562 Servers may close the Web Socket connection whenever desired. 564 User agents should not close the Web Socket connection arbitrarily. 566 5. Security considerations 568 ** ISSUE ** ... 570 6. References 572 [HTML5] Hickson, I., "HTML5", January 2009. 574 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 575 Mechanism", RFC 2109, February 1997. 577 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 578 RFC 2246, January 1999. 580 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 581 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 582 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 584 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 585 Mechanism", RFC 2965, October 2000. 587 Author's Address 589 Ian Hickson 590 Google, Inc. 592 Email: ian@hixie.ch 593 URI: http://ln.hixie.ch/