[html5] r5409 - [e] (0) Transferred the Web Sockets Protocol to Ian Fette.
whatwg at whatwg.org
whatwg at whatwg.org
Thu Sep 2 03:00:33 PDT 2010
Author: ianh
Date: 2010-09-02 03:00:31 -0700 (Thu, 02 Sep 2010)
New Revision: 5409
Modified:
complete.html
index
source
Log:
[e] (0) Transferred the Web Sockets Protocol to Ian Fette.
Modified: complete.html
===================================================================
--- complete.html 2010-09-01 21:49:50 UTC (rev 5408)
+++ complete.html 2010-09-02 10:00:31 UTC (rev 5409)
@@ -209,7 +209,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG src=/images/logo></a></p>
<hgroup><h1>Web Applications 1.0</h1>
- <h2 class="no-num no-toc">Draft Standard — 1 September 2010</h2>
+ <h2 class="no-num no-toc">Draft Standard — 2 September 2010</h2>
</hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
@@ -1032,65 +1032,10 @@
<li><a href=#feedback-from-the-protocol><span class=secno>10.3.3 </span>Feedback from the protocol</a>
<ol>
<li><a href=#event-definitions-1><span class=secno>10.3.3.1 </span>Event definitions</a></li>
- <li><a href=#garbage-collection-1><span class=secno>10.3.3.2 </span>Garbage collection</a></ol></li>
- <li><a href=#websocket-protocol title="The WebSocket protocol enables
- two-way communication between a user agent running untrusted code
- running in a controlled environment to a remote host that has
- opted-in to communications from that code. The security model used
- for this is the Origin-based security model commonly used by Web
- browsers. The protocol consists of an initial handshake followed by
- basic message framing, layered over TCP. The goal of this technology
- is to provide a mechanism for browser-based applications that need
- two-way communication with servers that does not rely on opening
- multiple HTTP connections (e.g. using XMLHttpRequest or
- <iframe>s and long polling)."><span class=secno>10.3.4 </span>The WebSocket protocol</a>
- <ol>
- <li><a href=#introduction-8><span class=secno>10.3.4.1 </span>Introduction</a>
- <ol>
- <li><a href=#background-0><span class=secno>10.3.4.1.1 </span>Background</a></li>
- <li><a href=#protocol-overview><span class=secno>10.3.4.1.2 </span>Protocol overview</a></li>
- <li><a href=#opening-handshake><span class=secno>10.3.4.1.3 </span>Opening handshake</a></li>
- <li><a href=#closing-handshake><span class=secno>10.3.4.1.4 </span>Closing handshake</a></li>
- <li><a href=#design-philosophy><span class=secno>10.3.4.1.5 </span>Design philosophy</a></li>
- <li><a href=#security-model><span class=secno>10.3.4.1.6 </span>Security model</a></li>
- <li><a href=#relationship-to-tcp-and-http><span class=secno>10.3.4.1.7 </span>Relationship to TCP and HTTP</a></li>
- <li><a href=#establishing-a-connection><span class=secno>10.3.4.1.8 </span>Establishing a connection</a></li>
- <li><a href=#subprotocols-using-the-websocket-protocol><span class=secno>10.3.4.1.9 </span>Subprotocols using the WebSocket protocol</a></ol></li>
- <li><a href=#terminology-1><span class=secno>10.3.4.2 </span>Terminology</a></li>
- <li><a href=#websocket-urls><span class=secno>10.3.4.3 </span>WebSocket URLs</a>
- <ol>
- <li><a href=#parsing-websocket-urls><span class=secno>10.3.4.3.1 </span>Parsing WebSocket URLs</a></li>
- <li><a href=#constructing-websocket-urls><span class=secno>10.3.4.3.2 </span>Constructing WebSocket URLs</a></ol></li>
- <li><a href=#client-side-requirements><span class=secno>10.3.4.4 </span>Client-side requirements</a>
- <ol>
- <li><a href=#opening-handshake-0><span class=secno>10.3.4.4.1 </span>Opening handshake</a></li>
- <li><a href=#data-framing><span class=secno>10.3.4.4.2 </span>Data framing</a></li>
- <li><a href=#handling-errors-in-utf-8-from-the-server><span class=secno>10.3.4.4.3 </span>Handling errors in UTF-8 from the server</a></ol></li>
- <li><a href=#server-side-requirements><span class=secno>10.3.4.5 </span>Server-side requirements</a>
- <ol>
- <li><a href="#reading-the-client's-opening-handshake"><span class=secno>10.3.4.5.1 </span>Reading the client's opening handshake</a></li>
- <li><a href="#sending-the-server's-opening-handshake"><span class=secno>10.3.4.5.2 </span>Sending the server's opening handshake</a></li>
- <li><a href=#ws-sd-framing><span class=secno>10.3.4.5.3 </span>Data framing</a></li>
- <li><a href=#handling-errors-in-utf-8-from-the-client><span class=secno>10.3.4.5.4 </span>Handling errors in UTF-8 from the client</a></ol></li>
- <li><a href=#closing-the-connection><span class=secno>10.3.4.6 </span>Closing the connection</a>
- <ol>
- <li><a href=#client-initiated-closure><span class=secno>10.3.4.6.1 </span>Client-initiated closure</a></li>
- <li><a href=#server-initiated-closure><span class=secno>10.3.4.6.2 </span>Server-initiated closure</a></li>
- <li><a href=#closure><span class=secno>10.3.4.6.3 </span>Closure</a></ol></li>
- <li><a href=#security-considerations><span class=secno>10.3.4.7 </span>Security considerations</a></li>
- <li><a href=#iana-considerations-0><span class=secno>10.3.4.8 </span>IANA considerations</a>
- <ol>
- <li><a href=#registration-of-ws:-scheme><span class=secno>10.3.4.8.1 </span>Registration of <code title="">ws:</code> scheme</a></li>
- <li><a href=#registration-of-wss:-scheme><span class=secno>10.3.4.8.2 </span>Registration of <code title="">wss:</code> scheme</a></li>
- <li><a href=#registration-of-the-websocket-http-upgrade-keyword><span class=secno>10.3.4.8.3 </span>Registration of the "<code title="">WebSocket</code>" HTTP Upgrade keyword</a></li>
- <li><a href=#sec-websocket-key1-and-sec-websocket-key2><span class=secno>10.3.4.8.4 </span><code>Sec-WebSocket-Key1</code> and <code>Sec-WebSocket-Key2</code></a></li>
- <li><a href=#sec-websocket-location><span class=secno>10.3.4.8.5 </span><code>Sec-WebSocket-Location</code></a></li>
- <li><a href=#sec-websocket-origin><span class=secno>10.3.4.8.6 </span><code>Sec-WebSocket-Origin</code></a></li>
- <li><a href=#sec-websocket-protocol><span class=secno>10.3.4.8.7 </span><code>Sec-WebSocket-Protocol</code></a></ol></li>
- <li><a href=#using-the-websocket-protocol-from-other-specifications><span class=secno>10.3.4.9 </span>Using the WebSocket protocol from other specifications</a></ol></ol></li>
+ <li><a href=#garbage-collection-1><span class=secno>10.3.3.2 </span>Garbage collection</a></ol></ol></li>
<li><a href=#web-messaging><span class=secno>10.4 </span>Cross-document messaging</a>
<ol>
- <li><a href=#introduction-9><span class=secno>10.4.1 </span>Introduction</a></li>
+ <li><a href=#introduction-8><span class=secno>10.4.1 </span>Introduction</a></li>
<li><a href=#security-postmsg><span class=secno>10.4.2 </span>Security</a>
<ol>
<li><a href=#authors><span class=secno>10.4.2.1 </span>Authors</a></li>
@@ -1098,14 +1043,14 @@
<li><a href=#posting-messages><span class=secno>10.4.3 </span>Posting messages</a></ol></li>
<li><a href=#channel-messaging><span class=secno>10.5 </span>Channel messaging</a>
<ol>
- <li><a href=#introduction-10><span class=secno>10.5.1 </span>Introduction</a></li>
+ <li><a href=#introduction-9><span class=secno>10.5.1 </span>Introduction</a></li>
<li><a href=#message-channels><span class=secno>10.5.2 </span>Message channels</a></li>
<li><a href=#message-ports><span class=secno>10.5.3 </span>Message ports</a>
<ol>
<li><a href=#ports-and-garbage-collection><span class=secno>10.5.3.1 </span>Ports and garbage collection</a></ol></ol></ol></li>
<li><a href=#webstorage><span class=secno>11 </span>Web storage</a>
<ol>
- <li><a href=#introduction-11><span class=secno>11.1 </span>Introduction</a></li>
+ <li><a href=#introduction-10><span class=secno>11.1 </span>Introduction</a></li>
<li><a href=#storage><span class=secno>11.2 </span>The API</a>
<ol>
<li><a href=#the-storage-interface><span class=secno>11.2.1 </span>The <code>Storage</code> interface</a></li>
@@ -1281,10 +1226,10 @@
<li><a href=#parsing-xhtml-fragments><span class=secno>13.4 </span>Parsing XHTML fragments</a></ol></li>
<li><a href=#rendering><span class=secno>14 </span>Rendering</a>
<ol>
- <li><a href=#introduction-12><span class=secno>14.1 </span>Introduction</a></li>
+ <li><a href=#introduction-11><span class=secno>14.1 </span>Introduction</a></li>
<li><a href=#the-css-user-agent-style-sheet-and-presentational-hints><span class=secno>14.2 </span>The CSS user agent style sheet and presentational hints</a>
<ol>
- <li><a href=#introduction-13><span class=secno>14.2.1 </span>Introduction</a></li>
+ <li><a href=#introduction-12><span class=secno>14.2.1 </span>Introduction</a></li>
<li><a href=#display-types><span class=secno>14.2.2 </span>Display types</a></li>
<li><a href=#margins-and-padding><span class=secno>14.2.3 </span>Margins and padding</a></li>
<li><a href=#alignment><span class=secno>14.2.4 </span>Alignment</a></li>
@@ -1310,7 +1255,7 @@
<li><a href=#toolbars-0><span class=secno>14.3.6 </span>Toolbars</a></ol></li>
<li><a href=#bindings><span class=secno>14.4 </span>Bindings</a>
<ol>
- <li><a href=#introduction-14><span class=secno>14.4.1 </span>Introduction</a></li>
+ <li><a href=#introduction-13><span class=secno>14.4.1 </span>Introduction</a></li>
<li><a href=#the-button-element-0><span class=secno>14.4.2 </span>The <code>button</code> element</a></li>
<li><a href=#the-details-element-0><span class=secno>14.4.3 </span>The <code>details</code> element</a></li>
<li><a href=#the-input-element-as-a-text-entry-widget><span class=secno>14.4.4 </span>The <code>input</code> element as a text entry widget</a></li>
@@ -61638,7 +61583,7 @@
<code><a href=#document>Document</a></code>'s <var title=concept-document-salvageable>salvageable</var> state to
false. <a href=#refsWEBSQL>[WEBSQL]</a></li>
- <li><p><a href=#close-the-websocket-connection>Close the WebSocket connection</a> of any
+ <li><p><span>Close the WebSocket connection</span> of any
<code><a href=#websocket>WebSocket</a></code> objects that were created by the <code title=dom-WebSocket><a href=#dom-websocket>WebSocket()</a></code> constructor visible on the
<code><a href=#document>Document</a></code>'s <code><a href=#window>Window</a></code> object. If this
affected any <code><a href=#websocket>WebSocket</a></code> objects, the set
@@ -73169,11 +73114,10 @@
<p>When the <code>WebSocket()</code> constructor is invoked, the UA
must run these steps:</p>
- <ol><!-- beware, this is very similar to the steps for what happens
- during a redirect, in the protocol section --><li><p><a href="#parse-a-websocket-url's-components">Parse a WebSocket URL's components</a> from the
+ <ol><li><p><span>Parse a WebSocket URL's components</span> from the
<var title="">url</var> argument, to obtain <var title="">host</var>, <var title="">port</var>, <var title="">resource name</var>, and <var title="">secure</var>. If
this fails, throw a <code><a href=#syntax_err>SYNTAX_ERR</a></code> exception and abort
- these steps.</li>
+ these steps. <a href=#refsWSP>[WSP]</a></li>
<li>
@@ -73217,17 +73161,17 @@
<li>
- <p><a href=#establish-a-websocket-connection>Establish a WebSocket connection</a> to a host <var title="">host</var>, on port <var title="">port</var> (if one was
+ <p><span>Establish a WebSocket connection</span> to a host <var title="">host</var>, on port <var title="">port</var> (if one was
specified), from <var title="">origin</var>, with the flag <var title="">secure</var>, with <var title="">resource name</var> as
the resource name, with <var title="">protocols</var> as the
- (possibly empty) list of protocols, and with the <var title="">defer cookies</var> flag set.</p>
+ (possibly empty) list of protocols, and with the <var title="">defer cookies</var> flag set. <a href=#refsWSP>[WSP]</a></p>
- <p class=note>If the "<a href=#establish-a-websocket-connection>establish a WebSocket
- connection</a>" algorithm fails, it triggers the "<a href=#fail-the-websocket-connection>fail
- the WebSocket connection</a>" algorithm, which then invokes
- the "<a href=#close-the-websocket-connection>close the WebSocket connection</a>" algorithm,
- which then establishes that the "<a href=#websocket-connection-is-closed>WebSocket connection is
- closed</a>", which fires the <code title=event-close>close</code> event <a href=#closeWebSocket>as described below</a>.</p>
+ <p class=note>If the "<span>establish a WebSocket
+ connection</span>" algorithm fails, it triggers the "<span>fail
+ the WebSocket connection</span>" algorithm, which then invokes
+ the "<span>close the WebSocket connection</span>" algorithm,
+ which then establishes that the "<span>WebSocket connection is
+ closed</span>", which fires the <code title=event-close>close</code> event <a href=#closeWebSocket>as described below</a>.</p>
</li>
@@ -73251,7 +73195,7 @@
<dt><dfn id=dom-websocket-open title=dom-WebSocket-OPEN><code>OPEN</code></dfn> (numeric value 1)</dt>
- <dd>The <a href=#websocket-connection-is-established>WebSocket connection is established</a> and communication is possible.</dd>
+ <dd>The <span>WebSocket connection is established</span> and communication is possible.</dd>
<dt><dfn id=dom-websocket-closing title=dom-WebSocket-CLOSING><code>CLOSING</code></dfn> (numeric value 2)</dt>
@@ -73265,8 +73209,8 @@
<code title=dom-WebSocket-CONNECTING><a href=#dom-websocket-connecting>CONNECTING</a></code> (0).</p>
<p>The <dfn id=dom-websocket-protocol title=dom-WebSocket-protocol><code>protocol</code></dfn> attribute
- must initially return the empty string. After the <a href=#websocket-connection-is-established>WebSocket
- connection is established</a>, its value might change, as defined
+ must initially return the empty string. After the <span>WebSocket
+ connection is established</span>, its value might change, as defined
below.</p>
<p class=note>The <code title=dom-WebSocket-protocol><a href=#dom-websocket-protocol>protocol</a></code> attribute returns the
@@ -73280,14 +73224,14 @@
raise an <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception. Otherwise, if the
<var title="">data</var> argument has any unpaired surrogates, then
it must raise <code><a href=#syntax_err>SYNTAX_ERR</a></code>. If the connection is
- established, and the string has no unpaired surrogates, and <a href=#the-websocket-closing-handshake-has-started title="the WebSocket closing handshake has started">the WebSocket
- closing handshake has not yet started</a>, then the user agent
- must <a href=#send-data-using-the-websocket>send <var title="">data</var> using the WebSocket</a>;
+ established, and the string has no unpaired surrogates, and <span title="the WebSocket closing handshake has started">the WebSocket
+ closing handshake has not yet started</span>, then the user agent
+ must <span>send <var title="">data</var> using the WebSocket</span>;
if the data cannot be sent, e.g. because it would need to be
- buffered but the buffer is full, the user agent must <a href=#close-the-websocket-connection>close the
- WebSocket connection</a>. Any invokation of this method that does
+ buffered but the buffer is full, the user agent must <span>close the
+ WebSocket connection</span>. Any invokation of this method that does
not raise an exception must increase the <code title=dom-WebSocket-bufferedAmount><a href=#dom-websocket-bufferedamount>bufferedAmount</a></code> attribute
- by the number of bytes needed to express the argument as UTF-8.</p>
+ by the number of bytes needed to express the argument as UTF-8. <a href=#refsWSP>[WSP]</a></p>
<p>The <dfn id=dom-websocket-close title=dom-WebSocket-close><code>close()</code></dfn>
method must run the first matching steps from the following list:</p>
@@ -73305,37 +73249,37 @@
</dd>
- <dt>If the WebSocket connection is not yet <a href=#websocket-connection-is-established title="WebSocket
- connection is established">established</a></dt>
+ <dt>If the WebSocket connection is not yet <span title="WebSocket
+ connection is established">established</span> <a href=#refsWSP>[WSP]</a></dt>
<dd>
- <p><a href=#fail-the-websocket-connection>Fail the WebSocket connection</a> and set the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's
- value to <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code>
- (2).</p>
+ <p><span>Fail the WebSocket connection</span> and set the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's
+ value to <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2).
+ <a href=#refsWSP>[WSP]</a></p>
- <p class=note>The "<a href=#fail-the-websocket-connection>fail the WebSocket connection</a>"
- algorithm invokes the "<a href=#close-the-websocket-connection>close the WebSocket
- connection</a>" algorithm, which then establishes that the
- "<a href=#websocket-connection-is-closed>WebSocket connection is closed</a>", which fires the
+ <p class=note>The "<span>fail the WebSocket connection</span>"
+ algorithm invokes the "<span>close the WebSocket
+ connection</span>" algorithm, which then establishes that the
+ "<span>WebSocket connection is closed</span>", which fires the
<code title=event-close>close</code> event <a href=#closeWebSocket>as described below</a>.</p>
</dd>
- <dt>If the WebSocket closing handshake has not yet been <a href=#the-websocket-closing-handshake-has-started title="the WebSocket closing handshake has
- started">started</a></dt>
+ <dt>If the WebSocket closing handshake has not yet been <span title="the WebSocket closing handshake has
+ started">started</span> <a href=#refsWSP>[WSP]</a></dt>
<dd>
- <p><a href=#start-the-websocket-closing-handshake>Start the WebSocket closing handshake</a> and set the
+ <p><span>Start the WebSocket closing handshake</span> and set the
<code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code>
- attribute's value to <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2).</p>
+ attribute's value to <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2). <a href=#refsWSP>[WSP]</a></p>
- <p class=note>The "<a href=#start-the-websocket-closing-handshake>start the WebSocket closing
- handshake</a>" algorithm eventually invokes the "<a href=#close-the-websocket-connection>close
- the WebSocket connection</a>" algorithm, which then establishes
- that the "<a href=#websocket-connection-is-closed>WebSocket connection is closed</a>", which
+ <p class=note>The "<span>start the WebSocket closing
+ handshake</span>" algorithm eventually invokes the "<span>close
+ the WebSocket connection</span>" algorithm, which then establishes
+ that the "<span>WebSocket connection is closed</span>", which
fires the <code title=event-close>close</code> event <a href=#closeWebSocket>as described below</a>.</p>
</dd>
@@ -73349,10 +73293,10 @@
value to <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code>
(2).</p>
- <p class=note><a href=#the-websocket-closing-handshake-has-started>The WebSocket closing handshake has
- started</a>, and will eventually invokethe "<a href=#close-the-websocket-connection>close the
- WebSocket connection</a>" algorithm, which will establish that
- the "<a href=#websocket-connection-is-closed>WebSocket connection is closed</a>", and thus the
+ <p class=note><span>The WebSocket closing handshake has
+ started</span>, and will eventually invokethe "<span>close the
+ WebSocket connection</span>" algorithm, which will establish that
+ the "<span>WebSocket connection is closed</span>", and thus the
<code title=event-close>close</code> event will fire, <a href=#closeWebSocket>as described below</a>.</p>
</dd>
@@ -73406,40 +73350,40 @@
<tr><td><dfn id=handler-websocket-onclose title=handler-WebSocket-onclose><code>onclose</code></dfn> <td> <code title=event-close>close</code>
</table><h4 id=feedback-from-the-protocol><span class=secno>10.3.3 </span>Feedback from the protocol</h4>
- <p>When the <i><a href=#websocket-connection-is-established>WebSocket connection is established</a></i>, the user
+ <p>When the <i>WebSocket connection is established</i>, the user
agent must <a href=#queue-a-task>queue a task</a> to first change the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's value
- to <code title=dom-WebSocket-OPEN><a href=#dom-websocket-open>OPEN</a></code> (1); <a href=#apply-the-cookies>apply the
- cookies</a> that were collected in the <var title="">list of
- cookies</var> when the <a href=#websocket-connection-is-established title="WebSocket connection is
- established">connection was established</a>; change the <code title=dom-WebSocket-protocol><a href=#dom-websocket-protocol>protocol</a></code> attribute's value to
- the <a href=#selected-websocket-subprotocol>selected WebSocket subprotocol</a>, if there is one;
- and then <a href=#fire-a-simple-event>fire a simple event</a> named <code title=event-open>open</code> at the <code><a href=#websocket>WebSocket</a></code>
- object.</p>
+ to <code title=dom-WebSocket-OPEN><a href=#dom-websocket-open>OPEN</a></code> (1); <span>apply the
+ cookies</span> that were collected in the <var title="">list of
+ cookies</var> when the <span title="WebSocket connection is
+ established">connection was established</span>; change the <code title=dom-WebSocket-protocol><a href=#dom-websocket-protocol>protocol</a></code> attribute's value to
+ the <span>selected WebSocket subprotocol</span>, if there is one;
+ and then <a href=#fire-a-simple-event>fire a simple event</a> named <code title=event-open>open</code> at the <code><a href=#websocket>WebSocket</a></code> object.
+ <a href=#refsWSP>[WSP]</a></p>
- <p>When <i><a href=#a-websocket-message-has-been-received>a WebSocket message has been received</a></i> with text <var title="">data</var>, the user agent must create an event that uses
+ <p>When <i>a WebSocket message has been received</i> with text <var title="">data</var>, the user agent must create an event that uses
the <code><a href=#messageevent>MessageEvent</a></code> interface, with the event name <code title=event-message><a href=#event-message>message</a></code>, which does not bubble, is not
cancelable, has no default action, and whose <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></code> attribute is set to <var title="">data</var>, and <a href=#queue-a-task>queue a task</a> to check to see
if the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code>
attribute's value is <code title=dom-WebSocket-OPEN><a href=#dom-websocket-open>OPEN</a></code>
(1) or <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2), and
- if so, dispatch the event at the <code><a href=#websocket>WebSocket</a></code> object.</p>
+ if so, dispatch the event at the <code><a href=#websocket>WebSocket</a></code> object. <a href=#refsWSP>[WSP]</a></p>
- <p>When <i><a href=#a-websocket-error-has-been-detected>a WebSocket error has been detected</a></i>, the user agent
+ <p>When <i>a WebSocket error has been detected</i>, the user agent
must <a href=#queue-a-task>queue a task</a> to check to see if the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's value
is <code title=dom-WebSocket-OPEN><a href=#dom-websocket-open>OPEN</a></code> (1) or <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2), and if so,
<a href=#fire-a-simple-event>fire a simple event</a> named <code title=event-error>error</code> at the <code><a href=#websocket>WebSocket</a></code>
- object.</p>
+ object. <a href=#refsWSP>[WSP]</a></p>
- <p>When <i><a href=#the-websocket-closing-handshake-has-started>the WebSocket closing handshake has started</a></i>, the user
+ <p>When <i>the WebSocket closing handshake has started</i>, the user
agent must <a href=#queue-a-task>queue a task</a> to change the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's value
to <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2). (If the
<code title=dom-WebSocket-close><a href=#dom-websocket-close>close()</a></code> method was called,
the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code>
attribute's value will already be set to <code title=dom-WebSocket-CLOSING><a href=#dom-websocket-closing>CLOSING</a></code> (2) when this task
- runs.)</p>
+ runs.) <a href=#refsWSP>[WSP]</a></p>
- <p id=closeWebSocket>When the <i><a href=#websocket-connection-is-closed>WebSocket connection is
- closed</a></i>, possibly <i title="">cleanly</i>, the user agent must
+ <p id=closeWebSocket>When the <i>WebSocket connection is
+ closed</i>, possibly <i title="">cleanly</i>, the user agent must
create an event that uses the <code><a href=#closeevent>CloseEvent</a></code> interface,
with the event name <code title=event-close>close</code>, which
does not bubble, is not cancelable, has no default action, and whose
@@ -73448,7 +73392,7 @@
false otherwise; and <a href=#queue-a-task>queue a task</a> to first change the
<code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's
value to <code title=dom-WebSocket-CLOSED><a href=#dom-websocket-closed>CLOSED</a></code> (3), and
- then dispatch the event at the <code><a href=#websocket>WebSocket</a></code> object.</p>
+ then dispatch the event at the <code><a href=#websocket>WebSocket</a></code> object. <a href=#refsWSP>[WSP]</a></p>
<p>The <a href=#task-source>task source</a> for all <a href=#concept-task title=concept-task>tasks</a> <a href=#queue-a-task title="queue a
task">queued</a> in this section is the <dfn id=websocket-task-source>WebSocket task
@@ -73486,2788 +73430,25 @@
the <a href=#event-loop>event loop</a> started executing a <a href=#concept-task title=concept-task>task</a> must not be garbage collected if
there are any event listeners registered for <code title=event-message><a href=#event-message>message</a></code> events, <code title=event-error>error</code> events, or <code title=event-close>close</code> events.</p>
- <p>A <code><a href=#websocket>WebSocket</a></code> object with <a href=#websocket-connection-is-established title="WebSocket
- connection is established">an established connection</a> that has
+ <p>A <code><a href=#websocket>WebSocket</a></code> object with <span title="WebSocket
+ connection is established">an established connection</span> that has
data queued to be transmitted to the network must not be garbage
- collected.</p>
+ collected. <a href=#refsWSP>[WSP]</a></p>
<p>If a <code><a href=#websocket>WebSocket</a></code> object is garbage collected while its
- connection is still open, the user agent must <a href=#close-the-websocket-connection>close the
- WebSocket connection</a>.</p>
+ connection is still open, the user agent must <span>close the
+ WebSocket connection</span>. <a href=#refsWSP>[WSP]</a></p>
-
+ </div><!--data-component-->
- <h4 id=websocket-protocol title="The WebSocket protocol enables
- two-way communication between a user agent running untrusted code
- running in a controlled environment to a remote host that has
- opted-in to communications from that code. The security model used
- for this is the Origin-based security model commonly used by Web
- browsers. The protocol consists of an initial handshake followed by
- basic message framing, layered over TCP. The goal of this technology
- is to provide a mechanism for browser-based applications that need
- two-way communication with servers that does not rely on opening
- multiple HTTP connections (e.g. using XMLHttpRequest or
- <iframe>s and long polling)."><span class=secno>10.3.4 </span>The WebSocket protocol</h4>
-
-
- <h5 id=introduction-8><span class=secno>10.3.4.1 </span>Introduction</h5>
-
- <h6 id=background-0><span class=secno>10.3.4.1.1 </span>Background</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>Historically, creating an instant messenger chat client as a Web
- application has required an abuse of HTTP to poll the server for
- updates while sending upstream notifications as distinct HTTP
- calls.</p>
-
- <p>This results in a variety of problems:</p>
-
- <ul><li>The server is forced to use a number of different underlying
- TCP connections for each client: one for sending information to the
- client, and a new one for each incoming message.</li>
-
- <li>The wire protocol has a high overhead, with each
- client-to-server message having an HTTP header.</li>
-
- <li>The client-side script is forced to maintain a mapping from the
- outgoing connections to the incoming connection to track
- replies.</li>
-
- </ul><p>A simpler solution would be to use a single TCP connection for
- traffic in both directions. This is what the WebSocket protocol
- provides. Combined with the WebSocket API, it provides an
- alternative to HTTP polling for two-way communication from a Web
- page to a remote server.
- </p>
-
- <p>The same technique can be used for a variety of Web applications,
- for instance games, stock tickers, multiuser applications with
- simultaneous editing, and user interfaces exposing server-side
- services in real time.</p>
-
-
-
- <h6 id=protocol-overview><span class=secno>10.3.4.1.2 </span>Protocol overview</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The protocol has two parts: a handshake, and then the data
- transfer.</p>
-
- <p>The handshake from the client looks as follows:</p>
-
- <pre>GET /demo HTTP/1.1
-Host: example.com
-Connection: Upgrade
-Sec-WebSocket-Key2: 12998 5 Y3 1 .P00
-Sec-WebSocket-Protocol: sample
-Upgrade: WebSocket
-Sec-WebSocket-Key1: 4 @1 46546xW%0l 1 5
-Origin: http://example.com
-
-^n:ds[4U</pre>
-
- <p>The handshake from the server looks as follows:</p>
-
- <pre>HTTP/1.1 101 WebSocket Protocol Handshake
-Upgrade: WebSocket
-Connection: Upgrade
-Sec-WebSocket-Origin: http://example.com
-Sec-WebSocket-Location: ws://example.com/demo
-Sec-WebSocket-Protocol: sample
-
-8jKS'y:G*Co,Wxa-</pre>
-
- <p>The leading line from the client follows the Request-Line
- format. The leading line from the server follows the Status-Line
- format. The Request-Line and Status-Line productions are defined in
- the HTTP specification.</p>
-
- <p>After the leading line in both cases come an unordered
- <a href=#ascii-case-insensitive>ASCII case-insensitive</a> set of fields, one per line,
- that each match the following non-normative ABNF:
- <a href=#refsABNF>[ABNF]</a>
-
- </p>
-
- <pre>field = 1*name-char colon [ space ] *any-char cr lf
-colon = %x003A ; U+003A COLON (:)
-space = %x0020 ; U+0020 SPACE
-cr = %x000D ; U+000D CARRIAGE RETURN (CR)
-lf = %x000A ; U+000A LINE FEED (LF)
-name-char = %x0000-0009 / %x000B-000C / %x000E-0039 / %x003B-10FFFF
- ; a Unicode character other than U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), or U+003A COLON (:)
-any-char = %x0000-0009 / %x000B-000C / %x000E-10FFFF
- ; a Unicode character other than U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)</pre>
-
- <p class=note>The character set for the above ABNF is Unicode. The
- fields themselves are encoded as UTF-8.</p>
-
- <p>Lines that don't match the above production cause the connection
- to be aborted.</p>
-
- <p>Finally, after the last field, the client sends 10 bytes
- starting with 0x0D 0x0A and followed by 8 random bytes, part of a
- challenge, and the server sends 18 bytes starting with 0x0D 0x0A and
- followed by 16 bytes consisting of a challenge response. The details
- of this challenge and other parts of the handshake are described in
- the next section.</p>
-
- <hr><p>Once the client and server have both sent their handshakes, and
- if the handshake was successful, then the data transfer part
- starts. This is a two-way communication channel where each side can,
- independently from the other, send data at will.</p>
-
- <p>Data is sent in the form of UTF-8 text. Each frame of data starts
- with a 0xFF byte identifying the frame type, followed by the number
- of bytes in the data expressed as a big-endian 64 bit unsigned
- integer, followed by the UTF-8 data.</p>
-
- <p class=note>The length is the number of UTF-8 <em>bytes</em>,
- and not the number of characters. For example, the string
- "H̶e̸͜҉ll̡o̵̶͘"
- has 13 Unicode code points, but is 21 bytes long.</p><!-- Zalgo -->
-
- <p>The WebSocket protocol uses this framing so that specifications
- that use the WebSocket protocol can expose such connections using
- an event-based mechanism instead of requiring users of those
- specifications to implement buffering and piecing together of
- messages manually.</p>
-
- <p>To close the connection cleanly, a frame consisting of just nine
- 0x00 bytes in a row is sent from one peer to ask that the other peer
- close the connection. That corresponds to a frame type of 0x00
- followed by a length of zero, indicating an empty frame.</p>
-
- <p>In addition to the 0x00 and 0xFF frame types, other types might
- in future be defined, to support binary data, fragmentation,
- compression, multiplexing, or other features.</p>
-
- <p>The wire format for the data transfer part is described by the
- <code title="">frames</code> production of the following
- non-normative ABNF.
- <a href=#refsABNF>[ABNF]</a>
-
- </p>
-
- <pre>frames = *frame
-frame = frame-type frame-length data
-frame-type = OCTET
-frame-length = 8OCTET
-data = *OCTET ; count must match the given length</pre>
-
- <p class=note>The above ABNF is intended for a binary octet
- environment.</p>
-
- <p class=warning>At this time, the WebSocket protocol cannot be
- used to send binary data. Using any of the frame types other than
- 0x00 and 0xFF is invalid. All other frame types are reserved for
- future use by future versions of this protocol.</p>
-
-
-
- <h6 id=opening-handshake><span class=secno>10.3.4.1.3 </span>Opening handshake</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The opening handshake is intended to be compatible with
- HTTP-based server-side software, so that a single port can be used
- by both HTTP clients talking to that server and WebSocket clients
- talking to that server. To this end, the WebSocket client's
- handshake appears to HTTP servers to be a regular GET request with
- an Upgrade offer:</p>
-
- <pre>GET / HTTP/1.1
-Upgrade: WebSocket
-Connection: Upgrade</pre>
-
- <p>Fields in the handshake are sent by the client in a random order;
- the order is not meaningful.</p>
-
- <p>Additional fields are used to select options in the WebSocket
- protocol. The only options available in this version are the
- subprotocol selector, <code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>Sec-WebSocket-Protocol</a></code>,
- and <code title=http-cookie>Cookie</code>, which can used for
- sending cookies to the server (e.g. as an authentication
- mechanism). The <code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>Sec-WebSocket-Protocol</a></code>
- field takes a space-separated list of strings:</p>
-
- <pre>Sec-WebSocket-Protocol: org.example.chat wsxmpp ACME.COM-IM-2</pre>
-
- <p>This field indicates the subprotocols (the application-level
- protocol layered over the WebSocket protocol) that the client can
- use. The server reports which subprotocol it is going to use in its
- handshake response.</p>
-
- <p>The other fields in the handshake are all security-related. The
- <code title=http-host>Host</code> field is used to protect against
- DNS rebinding attacks and to allow multiple domains to be served
- from one IP address.</p>
-
- <pre>Host: example.com</pre>
-
- <p>The server includes the hostname in the <code title=http-sec-websocket-location><a href=#sec-websocket-location>Sec-WebSocket-Location</a></code>
- field of its handshake, so that both the client and the server can
- verify that they agree on which host is in use.</p>
-
- <p>The <code title=http-origin>Origin</code> field is used to
- protect against unauthorized cross-origin use of a WebSocket server
- by scripts using the <code><a href=#websocket>WebSocket</a></code> API in a Web
- browser. The server specifies which origin it is willing to receive
- requests from by including a <code title=http-sec-websocket-origin><a href=#sec-websocket-origin>Sec-WebSocket-Origin</a></code> field
- with that origin. If multiple origins are authorized, the server
- echoes the value in the <code title=http-origin>Origin</code>
- field of the client's handshake.</p>
-
- <pre>Origin: http://example.com</pre>
-
- <p>Finally, the server has to prove to the client that it received
- the client's WebSocket handshake, so that the server doesn't accept
- connections that are not WebSocket connections. This prevents an
- attacker from tricking a WebSocket server by sending it
- carefully-crafted packets using <code>XMLHttpRequest</code> or a
- <code><a href=#the-form-element>form</a></code> submission.</p>
-
- <p>To prove that the handshake was received, the server has to take
- three pieces of information and combine them to form a response. The
- first two pieces of information come from the <code title=http-sec-websocket-key>Sec-WebSocket-Key1</code> and <code title=http-sec-websocket-key>Sec-WebSocket-Key2</code> fields in
- the client handshake:</p>
-
- <pre>Sec-WebSocket-Key1: 18x 6]8vM;54 *(5: { U1]8 z [ 8
-Sec-WebSocket-Key2: 1_ tx7X d < nw 334J702) 7]o}` 0</pre>
-
- <p>For each of these fields, the server has to take the digits from
- the value to obtain a number (in this case 1868545188 and 1733470270
- respectively), then divide that number by the number of spaces
- characters in the value (in this case 12 and 10) to obtain a 32-bit
- number (155712099 and 173347027). These two resulting numbers are
- then used in the server handshake, as described below.</p>
-
- <p>The counting of spaces is intended to make it impossible to
- smuggle this field into the resource name; making this even harder
- is the presence of <em>two</em> such fields, and the use of a
- newline as the only reliable indicator that the end of the key has
- been reached. The use of random characters interspersed with the
- spaces and the numbers ensures that the implementor actually looks
- for spaces and newlines, instead of being treating any character
- like a space, which would make it again easy to smuggle the fields
- into the path and trick the server. Finally, <em>dividing</em> by
- this number of spaces is intended to make sure that even the most
- naïve of implementations will check for spaces, since if ther
- server does not verify that there are some spaces, the server will
- try to divide by zero, which is usually fatal (a correct handshake
- will always have at least one space).
-
- <p>The third piece of information is given after the fields, in the
- last eight bytes of the handshake, expressed here as they would be
- seen if interpreted as UTF-8:</p>
-
- <pre>Tm[K T2u</pre>
-
- <p>The concatenation of the number obtained from processing the
- <code title=http-sec-websocket-key>Sec-WebSocket-Key1</code>
- field, expressed as a big-endian 32-bit number, the number
- obtained from processing the <code title=http-sec-websocket-key>Sec-WebSocket-Key2</code> field,
- again expressed as a big-endian 32-bit number, and finally the
- eight bytes at the end of the handshake, form a 128 bit string whose
- MD5 sum is then used by the server to prove that it read the
- handshake.</p>
-
- <hr><p>The handshake from the server is much simpler than the client
- handshake. The first line is an HTTP Status-Line, with the status
- code 101 (the HTTP version and reason phrase aren't important):</p>
-
- <pre>HTTP/1.1 101 WebSocket Protocol Handshake</pre>
-
- <p>The fields follow. Two of the fields are just for compatibility
- with HTTP:</p>
-
- <pre>Upgrade: WebSocket
-Connection: Upgrade</pre>
-
- <p>Two of the fields are part of the security model described
- above, echoing the origin and stating the exact host, port, resource
- name, and whether the connection is expected to be encrypted:</p>
-
- <pre>Sec-WebSocket-Origin: http://example.com
-Sec-WebSocket-Location: ws://example.com/</pre>
-
- <p>These fields are checked by the Web browser when it is acting as
- a <code><a href=#websocket>WebSocket</a></code> client for scripted pages. A server that
- only handles one origin and only serves one resource can therefore
- just return hard-coded values and does not need to parse the
- client's handshake to verify the correctness of the values.</p>
-
- <p>Option fields can also be included. In this version of the
- protocol, the main option field is <code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>Sec-WebSocket-Protocol</a></code>,
- which indicates the subprotocol that the server speaks. Web browsers
- verify that the server specified one of the values that was
- specified in the <code><a href=#websocket>WebSocket</a></code> constructor, so a server
- that speaks multiple subprotocols has to make sure it selects one
- based on the client's handshake and specifies the right one in its
- handshake.</p>
-
- <pre>Sec-WebSocket-Protocol: org.example.chat</pre>
-
- <p>The server can also set cookie-related option fields to
- <em>set</em> cookies, as in HTTP.</p>
-
- <p>After the fields, the server sends the aforementioned MD5 sum, a
- 16 byte (128 bit) value, shown here as if interpreted as UTF-8:</p>
-
- <pre>fQJ,fN/4F4!~K~MH</pre>
-
- <p>This value depends on what the client sends, as described
- above. If it doesn't match what the client is expecting, the client
- would disconnect.</p>
-
- <p>Having part of the handshake appear after the fields ensures
- that both the server and the client verify that the connection is
- not being interrupted by an HTTP intermediary such as a
- man-in-the-middle cache or proxy.</p>
-
-
- <h6 id=closing-handshake><span class=secno>10.3.4.1.4 </span>Closing handshake</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The closing handshake is far simpler than the opening handshake.</p>
-
- <p>Either peer can send a 0xFF frame with length 0x00 to begin the
- closing handshake. Upon receiving a 0xFF frame, the other peer
- sends an identical 0xFF frame in acknowledgement, if it hasn't
- already sent one. Upon receiving <em>that</em> 0xFF frame, the first
- peer then closes the connection, safe in the knowledge that no
- further data is forthcoming.</p>
-
- <p>After sending a 0xFF frame, a peer does not send any further
- data; after receiving a 0xFF frame, a peer discards any further
- data received.</p>
-
- <p>It is safe for both peers to initiate this handshake
- simultaneously.</p>
-
- <p>The closing handshake is intended to replace the TCP closing
- handshake (FIN/ACK), on the basis that the TCP closing handshake is
- not always reliable end-to-end, especially in the presence of
- man-in-the-middle proxies and other intermediaries.</p>
-
-
-
- <h6 id=design-philosophy><span class=secno>10.3.4.1.5 </span>Design philosophy</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The WebSocket protocol is designed on the principle that there
- should be minimal framing (the only framing that exists is to make
- the protocol frame-based instead of stream-based, and to support a
- distinction between Unicode text and binary frames). It is expected
- that metadata would be layered on top of WebSocket by the
- application layer, in the same way that metadata is layered on top
- of TCP by the application layer (HTTP).</p>
-
- <p>Conceptually, WebSocket is really just a layer on top of TCP
- that adds a Web "origin"-based security model for browsers; adds an
- addressing and subprotocol naming mechanism to support multiple
- services on one port and multiple host names on one IP address;
- layers a framing mechanism on top of TCP to get back to the IP
- packet mechanism that TCP is built on, but without length
- limits; and reimplements the closing handshake in-band.
-
- Other than that, it adds nothing. Basically it is intended
- to be as close to just exposing raw TCP to script as possible
- given the constraints of the Web. It's also designed in such a way
- that its servers can share a port with HTTP servers, by having its
- handshake be a valid HTTP Upgrade handshake also.</p>
-
- <p>The protocol is intended to be extensible; future versions will
- likely introduce a mechanism to compress data and might support
- sending binary data. To do this, future versions of this protocol
- are likely to introduce option fields that clients can send in its
- handshake to announce support for a feature (such as compression),
- to which the server can react by including a similar option field in
- <em>its</em> handshake.</p>
-
-
- <h6 id=security-model><span class=secno>10.3.4.1.6 </span>Security model</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The WebSocket protocol uses the origin model used by Web
- browsers to restrict which Web pages can contact a WebSocket server
- when the WebSocket protocol is used from a Web page. Naturally,
- when the WebSocket protocol is used by a dedicated client directly
- (i.e. not from a Web page through a Web browser), the origin model
- is not useful, as the client can provide any arbitrary origin
- string.</p>
-
- <p>This protocol is intended to fail to establish a connection with
- servers of pre-existing protocols like SMTP or HTTP, while allowing
- HTTP servers to opt-in to supporting this protocol if desired. This
- is achieved by having a strict and elaborate handshake, and by
- limiting the data that can be inserted into the connection before
- the handshake is finished (thus limiting how much the server can be
- influenced).</p>
-
- <p>It is similarly intended to fail to establish a connection when
- data from other protocols, especially HTTP, is sent to a WebSocket
- server, for example as might happen if an HTML <code><a href=#the-form-element>form</a></code>
- were submitted to a WebSocket server. This is primarily achieved by
- requiring that the server prove that it read the handshake, which it
- can only do if the handshake contains the appropriate parts which
- themselves can only be sent by a WebSocket handshake; in
- particular, fields starting with <code title="">Sec-</code> cannot
- be set by an attacker from a Web browser, even when using
- <code>XMLHttpRequest</code>.</p>
-
-
- <h6 id=relationship-to-tcp-and-http><span class=secno>10.3.4.1.7 </span>Relationship to TCP and HTTP</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The WebSocket protocol is an independent TCP-based protocol. Its
- only relationship to HTTP is that its handshake is interpreted by
- HTTP servers as an Upgrade request.</p>
-
- <p>Based on the expert recommendation of the IANA<!-- [IANA #257455]
- -->, the WebSocket protocol by default uses port 80 for regular
- WebSocket connections and port 443 for WebSocket connections
- tunneled over TLS.</p>
-
-
-
- <h6 id=establishing-a-connection><span class=secno>10.3.4.1.8 </span>Establishing a connection</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>There are several options for establishing a WebSocket connection.</p>
-
- <p>On the face of it, the simplest method would seem to be to use
- port 80 to get a direct connection to a WebSocket server. Port 80
- traffic, however, will often be intercepted by man-in-the-middle
- HTTP proxies, which can lead to the connection failing to be
- established.</p>
-
- <p>The most reliable method, therefore, is to use TLS encryption and
- port 443 to connect directly to a WebSocket server. This has the
- advantage of being more secure; however, TLS encryption can be
- computationally expensive.</p>
-
- <p>When a connection is to be made to a port that is shared by an
- HTTP server (a situation that is quite likely to occur with traffic
- to ports 80 and 443), the connection will appear to the HTTP server
- to be a regular GET request with an Upgrade offer. In relatively
- simple setups with just one IP address and a single server for all
- traffic to a single hostname, this might allow a practical way for
- systems based on the WebSocket protocol to be deployed. In more
- elaborate setups (e.g. with load balancers and multiple servers), a
- dedicated set of hosts for WebSocket connections separate from the
- HTTP servers is probably easier to manage.</p>
-
-
-
- <h6 id=subprotocols-using-the-websocket-protocol><span class=secno>10.3.4.1.9 </span>Subprotocols using the WebSocket protocol</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The client can request that the server use a specific subprotocol
- by including the <code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>Sec-Websocket-Protocol</a></code>
- field in its handshake. If it is specified, the server needs to
- include an equivalent field in its response for the connection to be
- established.</p>
-
- <p>These subprotocol names do not need to be registered, but if a
- subprotocol is intended to be implemented by multiple independent
- WebSocket servers, potential clashes with the names of subprotocols
- defined independently can be avoided by using names that contain the
- domain name of the subprotocol's originator. For example, if Example
- Corporation were to create a Chat subprotocol to be implemented by
- many servers around the Web, they could name it
- "chat.example.com". If the Example Organisation called their
- competing subprotocol "the-example.org-chat-protocol", then the two
- subprotocols could be implemented by servers simultaneously, with
- the server dynamically selecting which subprotocol to use based on
- the value sent by the client.</p>
-
- <p>Subprotocols can be versioned in backwards-incompatible ways by
- changing the subprotocol name, eg. going from "bookings.example.net"
- to "bookings.example.net2". These subprotocols would be considered
- completely separate by WebSocket clients. Backwards-compatible
- versioning can be implemented by reusing the same subprotocol string
- but carefully designing the actual subprotocol to support this kind
- of extensibility.</p>
-
- <p>Subprotocol names are sequences of one or more characters in the
- range U+0021 to U+007F.</p>
-
-
-
- <h5 id=terminology-1><span class=secno>10.3.4.2 </span>Terminology</h5>
-
-
- <p>When an implementation is required to <i>send</i> data as part of
- the WebSocket protocol, the implementation may delay the actual
- transmission arbitrarily, e.g. buffering data so as to send fewer IP
- packets.</p>
-
-
-
- <h5 id=websocket-urls><span class=secno>10.3.4.3 </span>WebSocket URLs</h5>
-
- <h6 id=parsing-websocket-urls><span class=secno>10.3.4.3.1 </span>Parsing WebSocket URLs</h6>
-
- <p>The steps to <dfn id="parse-a-websocket-url's-components">parse a WebSocket URL's components</dfn> from
- a string <var title="">url</var> are as follows. These steps return
- either a <var title="">host</var>, a <var title="">port</var>, a
- <var title="">resource name</var>, and a <var title="">secure</var>
- flag, or they fail.</p>
-
- <ol><li><p>If the <var title="">url</var> string is not an
- <a href=#absolute-url>absolute URL</a>, then fail this algorithm. <a href=#refsWEBADDRESSES>[WEBADDRESSES]</a></li>
-
- <li>
-
- <p><a href=#resolve-a-url title="resolve a url">Resolve</a> the <var title="">url</var> string using the <span>resolve a Web
- address</span> algorithm defined by the Web addresses
- specification, with the <span>URL character encoding</span> set to
- UTF-8. <a href=#refsWEBADDRESSES>[WEBADDRESSES]</a> <a href=#refsRFC3629>[RFC3629]</a></p> <!-- the URL character
- encoding is used to escape the query component -->
-
- <p class=note>It doesn't matter what it is resolved relative to,
- since we already know it is an <a href=#absolute-url>absolute URL</a> at this
- point.</p>
-
- </li>
-
- <li><p>If <var title="">url</var> does not have a <a href=#url-scheme title=url-scheme><scheme></a> component whose value,
- when <a href=#converted-to-ascii-lowercase>converted to ASCII lowercase</a>, is either "<code title="">ws</code>" or "<code title="">wss</code>", then fail this
- algorithm.</li>
-
- <li><p>If <var title="">url</var> has a <a href=#url-fragment title=url-fragment><fragment></a> component, then fail
- this algorithm.</li>
-
- <li><p>If the <a href=#url-scheme title=url-scheme><scheme></a>
- component of <var title="">url</var> is "<code title="">ws</code>",
- set <var title="">secure</var> to false; otherwise, the <a href=#url-scheme title=url-scheme><scheme></a> component is "<code title="">wss</code>", set <var title="">secure</var> to
- true.</li>
-
- <li><p>Let <var title="">host</var> be the value of the <a href=#url-host title=url-host><host></a> component of <var title="">url</var>, <a href=#converted-to-ascii-lowercase>converted to ASCII
- lowercase</a>.</li> <!-- at this point this is
- Punycode-encoded already -->
-
- <li><p>If <var title="">url</var> has a <a href=#url-port title=url-port><port></a> component, then let <var title="">port</var> be that component's value; otherwise, there is
- no explicit <var title="">port</var>.</li>
-
- <li><p>If there is no explicit <var title="">port</var>, then: if
- <var title="">secure</var> is false, let <var title="">port</var>
- be 80, otherwise let <var title="">port</var> be 443.</li>
-
- <li><p>Let <var title="">resource name</var> be the value of the
- <a href=#url-path title=url-path><path></a> component (which might
- be empty) of <var title="">url</var>.</li> <!-- at this point
- this is UTF-8 encoded and %-escaped -->
-
- <li><p>If <var title="">resource name</var> is the empty string,
- set it to a single character U+002F SOLIDUS (/).</li>
-
- <li><p>If <var title="">url</var> has a <a href=#url-query title=url-query><query></a> component, then append a
- single U+003F QUESTION MARK character (?) to <var title="">resource
- name</var>, followed by the value of the <a href=#url-query title=url-query><query></a> component.</li> <!-- at
- this point this is UTF-8 encoded and %-escaped -->
-
- <li><p>Return <var title="">host</var>, <var title="">port</var>,
- <var title="">resource name</var>, and <var title="">secure</var>.</li>
-
- </ol><h6 id=constructing-websocket-urls><span class=secno>10.3.4.3.2 </span>Constructing WebSocket URLs</h6>
-
- <p>The steps to <dfn id=construct-a-websocket-url>construct a WebSocket URL</dfn> from a <var title="">host</var>, a <var title="">port</var>, a <var title="">resource name</var>, and a <var title="">secure</var> flag,
- are as follows:</p>
-
- <ol><li>Let <var title="">url</var> be the empty string.</li>
-
- <li>If the <var title="">secure</var> flag is false, then append
- the string "<code title="">ws://</code>" to <var title="">url</var>. Otherwise, append the string "<code title="">wss://</code>" to <var title="">url</var>.</li>
-
- <li>Append <var title="">host</var> to <var title="">url</var>.</li>
-
- <li>If the <var title="">secure</var> flag is false and port is
- not 80, or if the <var title="">secure</var> flag is true and
- port is not 443, then append the string "<code title="">:</code>"
- followed by <var title="">port</var> to <var title="">url</var>.</li>
-
- <li>Append <var title="">resource name</var> to <var title="">url</var>.</li>
-
- <li>Return <var title="">url</var>.</li>
-
- </ol><h5 id=client-side-requirements><span class=secno>10.3.4.4 </span>Client-side requirements</h5>
-
- <p><i>This section only applies to user agents, not to
- servers.</i></p>
-
- <p>User agents running in controlled environments, e.g. browsers on
- mobile handsets tied to specific carriers, may offload the
- management of the connection to another agent on the network. In
- such a situation, the user agent for the purposes of conformance is
- considered to include both the handset software and any such
- agents.</p>
-
- <p class=note>This specification doesn't currently define a limit
- to the number of simultaneous connections that a client can
- establish to a server.</p>
-
-
- <h6 id=opening-handshake-0><span class=secno>10.3.4.4.1 </span>Opening handshake</h6>
-
- <p>When the user agent is to <dfn id=establish-a-websocket-connection>establish a WebSocket
- connection</dfn> to a host <var title="">host</var>, on a port <var title="">port</var>, from an origin whose <a href=#ascii-serialization-of-an-origin title="ASCII
- serialization of an origin">ASCII serialization</a> is <var title="">origin</var>, with a flag <var title="">secure</var>, with
- a string giving a <var title="">resource name</var>, with a
- (possibly empty) list of strings giving the <var title="">protocols</var>, and optionally with a <var title="">defer
- cookies</var> flag, it must run the following steps. The <var title="">host</var> must have been punycode-encoded already if
- necessary (i.e. it does not contain characters above U+007E). The
- <var title="">origin</var> must not contain characters in the range
- U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL
- LETTER Z). The <var title="">resource name</var> string must be a
- non-empty string of characters in the range U+0021 to U+007E that
- starts with a U+002F SOLIDUS character (/). The various strings in
- <var title="">protocols</var> must all be non-empty strings with
- characters in the range U+0021 to U+007E, and must all be unique. <a href=#refsORIGIN>[ORIGIN]</a></p>
-
- <ol><li>
-
- <p>If the user agent already has a WebSocket connection to the
- remote host (IP address) identified by <var title="">host</var>,
- even if known by another name, wait until that connection has been
- <a href=#websocket-connection-is-established title="WebSocket connection is
- established">established</a> or for that connection to have
- <a href=#fail-the-websocket-connection title="fail the WebSocket connection">failed</a>. If
- multiple connections to the same IP address are attempted
- simultaneously, the user agent must serialize them so that there
- is no more than one connection at a time running through the
- following steps.</p>
-
- <p>If the user agent cannot determine the IP address of the remote
- host (for example because all communication is being done through
- a proxy server that performs DNS queries itself), then the user
- agent must assume for the purposes of this step that each host
- name refers to a distinct remote host, but should instead limit
- the total number of simultaneous connections that are not <a href=#websocket-connection-is-established title="WebSocket connection is established">established</a> to
- a reasonably low number (e.g., in a Web browser, to the number of
- tabs the user has open).</p>
-
- <p class=note>This makes it harder for a script to perform a
- denial of service attack by just opening a large number of
- WebSocket connections to a remote host. A server can further
- reduce the load on itself when attacked by making use of this by
- pausing before closing the connection, as that will reduce the
- rate at which the client reconnects.</p>
-
- <p class=note>There is no limit to the number of <a href=#websocket-connection-is-established title="WebSocket connection is established">established</a>
- WebSocket connections a user agent can have with a single remote
- host. Servers can refuse to connect users with an excessive number
- of connections, or disconnect resource-hogging users when
- suffering high load.</p>
-
- </li>
-
- <li>
-
- <p><i>Connect</i>: If the user agent is configured to use a proxy
- when using the WebSocket protocol to connect to host <var title="">host</var> and/or port <var title="">port</var>, then
- connect to that proxy and ask it to open a TCP connection to
- the host given by <var title="">host</var> and the port given by
- <var title="">port</var>.</p>
-
- <div class=example>
-
- <p>For example, if the user agent uses an HTTP proxy for all
- traffic, then if it was to try to connect to port 80 on server
- example.com, it might send the following lines to the proxy
- server:</p>
-
- <pre>CONNECT example.com:80 HTTP/1.1
-Host: example.com</pre>
-
- <p>If there was a password, the connection might look like:</p>
-
- <pre>CONNECT example.com:80 HTTP/1.1
-Host: example.com
-Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE=</pre>
-
- </div>
-
- <p>Otherwise, if the user agent is not configured to use a proxy,
- then open a TCP connection to the host given by <var title="">host</var> and the port given by <var title="">port</var>.</p>
-
- <p class=note>Implementations that do not expose explicit UI for
- selecting a proxy for WebSocket connections separate from other
- proxies are encouraged to use a SOCKS proxy for WebSocket
- connections, if available, or failing that, to prefer the proxy
- configured for HTTPS connections over the proxy configured for
- HTTP connections.</p>
-
- <p>For the purpose of proxy autoconfiguration scripts, the
- <a href=#url>URL</a> to pass the function must be constructed from
- <var title="">host</var>, <var title="">port</var>, <var title="">resource name</var>, and the <var title="">secure</var>
- flag using the steps to <a href=#construct-a-websocket-url>construct a WebSocket
- URL</a>.</p>
-
- <p class=note>The WebSocket protocol can be identified in proxy
- autoconfiguration scripts from the scheme ("<code title="">ws:</code>" for unencrypted connections and "<code title="">wss:</code>" for encrypted connections).</p>
-
- </li>
-
- <li><p>If the connection could not be opened, then <a href=#fail-the-websocket-connection>fail the
- WebSocket connection</a> and abort these steps.</li>
-
- <li>
-
- <p>If <var title="">secure</var> is true, perform a TLS handshake
- over the connection. If this fails (e.g. the server's certificate
- could not be verified), then <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a> and abort these steps. Otherwise, all further
- communication on this channel must run through the encrypted
- tunnel. <a href=#refsRFC2246>[RFC2246]</a></p>
-
- <p>User agents must use the Server Name Indication extension in
- the TLS handshake. <a href=#refsRFC4366>[RFC4366]</a></p>
-
- <p>User agents must use the Next Protocol Negotiation extension in
- the TLS handshake, selecting the "776562736f636b6574" protocol
- ("websocket" in UTF-8). <a href=#refsNPN>[NPN]</a>
-
- </li>
-
- <li>
-
- <p>Send the UTF-8 string "GET" followed by a UTF-8-encoded U+0020
- SPACE character to the remote side (the server).</p>
-
- <p>Send the <var title="">resource name</var> value, encoded as
- UTF-8.</p>
-
- <p>Send another UTF-8-encoded U+0020 SPACE character, followed by
- the UTF-8 string "HTTP/1.1", followed by a UTF-8-encoded U+000D
- CARRIAGE RETURN U+000A LINE FEED character pair (CRLF).</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">fields</var> be an empty list of strings.</p>
-
- </li>
-
- <li>
-
- <p>Add the string "Upgrade: WebSocket" to <var title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>Add the string "Connection: Upgrade" to <var title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">hostport</var> be an empty string.</p>
-
- </li>
-
- <li>
-
- <p>Append the <var title="">host</var> value, <a href=#converted-to-ascii-lowercase>converted to
- ASCII lowercase</a>, to <var title="">hostport</var>.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">secure</var> is false, and <var title="">port</var> is not 80, or if <var title="">secure</var> is
- true, and <var title="">port</var> is not 443, then append a
- U+003A COLON character (:) followed by the value of <var title="">port</var>, expressed as a base-ten integer, to <var title="">hostport</var>.</p>
-
- </li>
-
- <li>
-
- <p>Add the string consisting of the concatenation of the string
- "Host:", a U+0020 SPACE character, and <var title="">hostport</var>, to <var title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>Add the string consisting of the concatenation of the string
- "Origin:", a U+0020 SPACE character, and the <var title="">origin</var> value, to <var title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>If the <var title="">protocols</var> list is empty, then skip
- this step.</p>
-
- <p>Otherwise, add the string consisting of the concatenation of
- the string "Sec-WebSocket-Protocol:", a U+0020 SPACE character,
- and the strings in <var title="">protocols</var>, maintaining
- their relative order and each separated from the next by a single
- U+0020 SPACE character, to <var title="">fields</var>.</p>
-
- </li>
-
-<!--UAS:
- <li>
-
- <p>Optionally, add the string consisting of the concatenation of
- the string "User-Agent:", a U+0020 SPACE character, and a
- user-agent defined string, to <var title="">fields</var>.</p>
-
- </li>
--->
-
- <li>
-
- <p>If the client has any <!--(v2-ws-auth) authentication
- information or--> cookies that would be relevant to a resource
- accessed over HTTP, if <var title="">secure</var> is false, or
- HTTPS, if it is true, on host <var title="">host</var>, port <var title="">port</var>, with <var title="">resource name</var> as the
- path (and possibly query parameters), then add to <var title="">fields</var> any HTTP headers that would be appropriate
- for that information.
- <a href=#refsHTTP>[HTTP]</a>
- <a href=#refsCOOKIES>[COOKIES]</a>
-
- </p>
-
- <p>This includes "<code>HttpOnly</code>" cookies (cookies with the
- http-only-flag set to true); the WebSocket protocol is not
- considered a non-HTTP API for the purpose of cookie
- processing.</p>
-
- <p>When one or more HTTP headers are to be added to <var title="">fields</var> for this step, each header must be added
- separately, and each header must be added as one entry consisting
- of the header's name in its canonical case, followed by a U+003A
- COLON character (:) and a U+0020 SPACE character, followed by the
- value with no use of continuation lines (i.e. containing no U+000A
- LINE FEED characters).</p>
-
- <!-- (Cookie headers only use one header for multiple cookies.) -->
-
-<!--(v2-ws-auth)
- <div class="example">
-
- <p>For example, if the server had a username and password that
- applied to <code title="">http://example.com/socket</code>, and
- the WebSocket was being opened to <code
- title="">ws://example.com/socket</code>, it could add them:</p>
-
- <pre>Authorization: Basic d2FsbGU6ZXZl</pre>
-
- </div>
--->
-
- </li>
-
- <li>
-
- <p>Let <var title="">spaces<sub>1</sub></var> be a random integer
- from 1 to 12 inclusive.</p>
-
- <p>Let <var title="">spaces<sub>2</sub></var> be a random integer
- from 1 to 12 inclusive.</p>
-
- <p class=example>For example, 5 and 9.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">max<sub>1</sub></var> be the largest integer
- not greater than 4,294,967,295 divided by <var title="">spaces<sub>1</sub></var>.</p>
-
- <p>Let <var title="">max<sub>2</sub></var> be the largest integer
- not greater than 4,294,967,295 divided by <var title="">spaces<sub>2</sub></var>.</p>
-
- <p class=example>Continuing the example, 858,993,459 and 477,218,588.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">number<sub>1</sub></var> be a random integer
- from 0 to <var title="">max<sub>1</sub></var> inclusive.</p>
-
- <p>Let <var title="">number<sub>2</sub></var> be a random integer
- from 0 to <var title="">max<sub>2</sub></var> inclusive.</p>
-
- <p class=example>For example, 777,007,543 and 114,997,259.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">product<sub>1</sub></var> be the result of
- multiplying <var title="">number<sub>1</sub></var> and <var title="">spaces<sub>1</sub></var> together.</p>
-
- <p>Let <var title="">product<sub>2</sub></var> be the result of
- multiplying <var title="">number<sub>2</sub></var> and <var title="">spaces<sub>2</sub></var> together.</p>
-
- <p class=example>Continuing the example, 3,885,037,715 and
- 1,034,975,331.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">key<sub>1</sub></var> be a string consisting
- of <var title="">product<sub>1</sub></var>, expressed in base ten
- using the numerals in the range U+0030 DIGIT ZERO (0) to U+0039
- DIGIT NINE (9).</p>
-
- <p>Let <var title="">key<sub>2</sub></var> be a string consisting
- of <var title="">product<sub>2</sub></var>, expressed in base ten
- using the numerals in the range U+0030 DIGIT ZERO (0) to U+0039
- DIGIT NINE (9).</p>
-
- <p class=example>Continuing the example, "3885037715" and
- "1034975331".</p>
-
- </li>
-
- <li>
-
- <p>Insert between one and twelve random characters from
- the ranges U+0021 to U+002F and U+003A to U+007E into <var title="">key<sub>1</sub></var> at random positions.</p>
-
- <p>Insert between one and twelve random characters from
- the ranges U+0021 to U+002F and U+003A to U+007E into <var title="">key<sub>2</sub></var> at random positions.</p>
-
- <p class=note>This corresponds to random printable ASCII
- characters other than the digits and the U+0020 SPACE
- character.</p>
-
- <p class=example>Continuing the example, this could lead to
- "P388O503D&ul7{K%gX(%715" and
- "1N?|kUT0or3o4I97N5-S3O31".</p>
-
- </li>
-
- <li>
-
- <p>Insert <var title="">spaces<sub>1</sub></var> U+0020 SPACE
- characters into <var title="">key<sub>1</sub></var> at random
- positions other than the start or end of the string.</p>
-
- <p>Insert <var title="">spaces<sub>2</sub></var> U+0020 SPACE
- characters into <var title="">key<sub>2</sub></var> at random
- positions other than the start or end of the string.</p>
-
- <p class=example>Continuing the example, this could lead to
- "P388 O503D&ul7 {K%gX( %7 15" and
- "1 N ?|k UT0or 3o 4 I97N 5-S3O 31".</p>
-
- </li>
-
- <li>
-
- <p>Add the string consisting of the concatenation of the string
- "Sec-WebSocket-Key1:", a U+0020 SPACE character, and the <var title="">key<sub>1</sub></var> value, to <var title="">fields</var>.</p>
-
- <p>Add the string consisting of the concatenation of the string
- "Sec-WebSocket-Key2:", a U+0020 SPACE character, and the <var title="">key<sub>2</sub></var> value, to <var title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>For each string in <var title="">fields</var>, in a random
- order: send the string, encoded as UTF-8, followed by a
- UTF-8-encoded U+000D CARRIAGE RETURN U+000A LINE FEED character
- pair (CRLF). It is important that the fields be output in a
- random order so that servers not depend on the particular order
- used by any particular client.</p>
-
- <p class=note>Only fields explicitly mentioned in the
- requirements of this specification are sent. For example, user
- agents do not send fields such as <code title=http-user-agent>User-Agent</code><!--UAS-->, <code title=http-accept-language>Accept-Language</code>, or <code title=http-content-type>Content-Type</code> in the WebSocket
- handshake.</p>
-
- </li>
-
- <li>
-
- <p>Send a UTF-8-encoded U+000D CARRIAGE RETURN U+000A LINE FEED
- character pair (CRLF).</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">key<sub>3</sub></var> be a string consisting
- of eight random bytes (or equivalently, a random 64 bit unsigned
- integer encoded in big-endian order).</p>
-
- <p class=example>For example, 0x47 0x30 0x22 0x2D 0x5A 0x3F 0x47
- 0x58.</p>
-
- </li>
-
- <li>
-
- <p>Send <var title="">key<sub>3</sub></var> to the server.</p>
-
- </li>
-
- <li>
-
- <p>Read bytes from the server until either the connection closes,
- or a 0x0A byte is read. Let <var title="">field</var> be these
- bytes, including the 0x0A byte.</p>
-
- <p>If <var title="">field</var> is not at least seven bytes long,
- or if the last two bytes aren't 0x0D and 0x0A respectively, or if
- <var title="">field</var> contains any 0x0D bytes other than the
- penultimate byte, or if <var title="">field</var> does not contain
- at least two 0x20 bytes, then <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a> and abort these steps.</p>
-
- <p>User agents may apply a timeout to this step, <a href=#fail-the-websocket-connection title="fail
- the WebSocket connection">failing the WebSocket
- connection</a> if the server does not send back data in a
- suitable time period.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">code</var> be the substring of <var title="">field</var> that starts from the byte after the first
- 0x20 byte, and ends with the byte before the second 0x20 byte.</p>
-
- </li>
-
-<!--(removed since the next step is even stricter)
- <li>
-
- <p>If <var title="">code</var> is not three bytes long, or if any
- of the bytes in <var title="">code</var> are not in the range 0x30
- to 0x39, then <span>fail the WebSocket connection</span> and abort
- these steps.</p>
-
- </li>
--->
-
- <li>
-
-<!--(v2-redirect or v2-ws-auth) - - then change the text below
- <p>If <var title="">code</var>, interpreted as UTF-8, is "101",
- then let <var title="">mode</var> be <i title="">normal</i>.</p>
--->
-<!--(v2-redirect)
- <p>If <var title="">code</var>, interpreted as UTF-8, is either
- "<code title="">301</code>", "<code title="">302</code>", "<code
- title="">303</code>", "<code title="">307</code>", then let <var
- title="">mode</var> be <i title="">redirect</i>.</p>
--->
-<!--(v2-ws-auth)
- <p>If <var title="">code</var>, interpreted as UTF-8, is "<code
- title="">401</code>", then let <var title="">mode</var> be <i
- title="">authenticate</i>.</p>
--->
-
- <p>If <var title="">code</var>, interpreted as UTF-8, is "101",
- then move to the next step.</p>
-
- <p>If <var title="">code</var>, interpreted as UTF-8, is "<code title="">407</code>", then either close the connection and jump
- back to step 2, providing appropriate authentication information,
- or <a href=#fail-the-websocket-connection>fail the WebSocket connection</a>. 407 is the code
- used by HTTP meaning "Proxy Authentication Required". User agents
- that support proxy authentication must interpret the response as
- defined by HTTP (e.g. to find and interpret the <code title=http-Proxy-Authenticate>Proxy-Authenticate</code>
- header).</p>
-
- <p>Otherwise, <a href=#fail-the-websocket-connection>fail the WebSocket connection</a> and abort
- these steps.</p>
-
- </li>
-
- <li><p>Let <var title="">fields</var> be a list of name-value
- pairs, initially empty.</li>
-
- <li id=ws-ua-field-loop><p><i title="">Field</i>: Let <var title="">name</var> and <var title="">value</var> be empty byte
- arrays.</li>
-
- <li>
-
- <p>Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, then
- <a href=#fail-the-websocket-connection>fail the WebSocket connection</a> and abort these
- steps.</p>
-
- <p>Otherwise, handle the byte as described in the appropriate
- entry below:</p>
-
- <dl class=switch><dt>If the byte is 0x0D (UTF-8 CR)</dt>
-
- <dd>If the <var title="">name</var> byte array is empty, then
- jump to the <a href=#ws-ua-fields-processing>fields
- processing</a> step. Otherwise, <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a> and abort these steps.</dd>
-
-
- <dt>If the byte is 0x0A (UTF-8 LF)</dt>
-
- <dd><a href=#fail-the-websocket-connection>Fail the WebSocket connection</a> and abort these
- steps.</dd>
-
-
- <dt>If the byte is 0x3A (UTF-8 :)</dt>
-
- <dd>Move on to the next step.</dd>
-
-
- <dt>If the byte is in the range 0x41 to 0x5A (UTF-8 A-Z)</dt>
-
- <dd>Append a byte whose value is the byte's value plus 0x20 to
- the <var title="">name</var> byte array and redo this step for
- the next byte.</dd>
-
-
- <dt>Otherwise</dt>
-
- <dd>Append the byte to the <var title="">name</var> byte
- array and redo this step for the next byte.</dd>
-
- </dl><p class=note>This reads a field name, terminated by a colon,
- converting upper-case letters in the range A-Z to lowercase, and
- aborting if a stray CR or LF is found.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">count</var> equal 0.</p>
-
- <p class=note>This is used in the next step to skip past a space
- character after the colon, if necessary.</p>
-
- </li>
-
- <li>
-
- <p>Read a byte from the server and increment <var title="">count</var> by 1.</p>
-
- <p>If the connection closes before this byte is received, then
- <a href=#fail-the-websocket-connection>fail the WebSocket connection</a> and abort these
- steps.</p>
-
- <p>Otherwise, handle the byte as described in the appropriate
- entry below:</p>
-
- <dl class=switch><dt>If the byte is 0x20 (UTF-8 space) and <var title="">count</var> equals 1</dt>
-
- <dd>Ignore the byte and redo this step for the next byte.</dd>
-
-
- <dt>If the byte is 0x0D (UTF-8 CR)</dt>
-
- <dd>Move on to the next step.</dd>
-
-
- <dt>If the byte is 0x0A (UTF-8 LF)</dt>
-
- <dd><a href=#fail-the-websocket-connection>Fail the WebSocket connection</a> and abort these
- steps.</dd>
-
-
- <dt>Otherwise</dt>
-
- <dd>Append the byte to the <var title="">value</var> byte array
- and redo this step for the next byte.</dd>
-
- </dl><p class=note>This reads a field value, terminated by a CRLF,
- skipping past a single space after the colon if there is one.</p>
-
- </li>
-
- <li>
-
- <p>Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, or if
- the byte is not a 0x0A byte (UTF-8 LF), then <a href=#fail-the-websocket-connection>fail the
- WebSocket connection</a> and abort these steps.</p>
-
- <p class=note>This skips past the LF byte of the CRLF after the
- field.</p>
-
- </li>
-
- <li>
-
- <p>Append an entry to the <var title="">fields</var> list that
- has the name given by the string obtained by interpreting the <var title="">name</var> byte array as a UTF-8 byte stream and the
- value given by the string obtained by interpreting the <var title="">value</var> byte array as a UTF-8 byte stream.</p>
-
- </li>
-
- <li>
-
- <p>Return to the "<a href=#ws-ua-field-loop>Field</a>" step
- above.</p>
-
- </li>
-
- <li id=ws-ua-fields-processing>
-
- <p><i>Fields processing</i>: Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, or if
- the byte is not a 0x0A byte (UTF-8 LF), then <a href=#fail-the-websocket-connection>fail the
- WebSocket connection</a> and abort these steps.</p>
-
- <p class=note>This skips past the LF byte of the CRLF after the
- blank line after the fields.</p>
-
- </li>
-
- <li><p>Let the <var title="">list of cookies</var> be empty.</li>
-
- <li>
-
- <p>
- <!--(v2-redirect or v2-ws-auth) If <var title="">mode</var> is <i title="">normal</i>, then: -->
-
- If there is not exactly one entry in the <var title="">fields</var> list whose name is "<code title=http-upgrade>upgrade</code>", or
-
- if there is not exactly one entry in the <var title="">fields</var> list whose name is "<code title=http-connection>connection</code>", or
-
- if there is not exactly one entry in the <var title="">fields</var> list whose name is "<code title=http-sec-websocket-origin><a href=#sec-websocket-origin>sec-websocket-origin</a></code>", or
-
- if there is not exactly one entry in the <var title="">fields</var> list whose name is "<code title=http-sec-websocket-location><a href=#sec-websocket-location>sec-websocket-location</a></code>", or
-
- if the <var title="">protocol</var> was specified but there is not exactly one entry in the <var title="">fields</var> list whose name is "<code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>sec-websocket-protocol</a></code>", or
-
- if there are any entries in the <var title="">fields</var> list
- whose names are the empty string, then <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a> and abort these steps. Otherwise, handle each
- entry in the <var title="">fields</var> list as follows:</p>
-
- <dl class=switch><dt>If the entry's name is "<code title=http-upgrade>upgrade</code>"</dt>
-
- <dd><p>If the value, <a href=#converted-to-ascii-lowercase>converted to ASCII lowercase</a>,
- is not exactly equal to the string "websocket", then <a href=#fail-the-websocket-connection>fail
- the WebSocket connection</a> and abort these steps.</dd>
-
-
- <dt>If the entry's name is "<code title=http-connection>connection</code>"</dt>
-
- <dd><p>If the value, <a href=#converted-to-ascii-lowercase>converted to ASCII lowercase</a>,
- is not exactly equal to the string "upgrade", then <a href=#fail-the-websocket-connection>fail the
- WebSocket connection</a> and abort these steps.</dd>
-
-
- <dt>If the entry's name is "<code title=http-sec-websocket-origin><a href=#sec-websocket-origin>sec-websocket-origin</a></code>"</dt>
-
- <dd><p>If the value is not exactly equal to <var title="">origin</var>, then <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a> and abort these steps. <a href=#refsORIGIN>[ORIGIN]</a></dd>
-
-
- <dt>If the entry's name is "<code title=http-sec-websocket-location><a href=#sec-websocket-location>sec-websocket-location</a></code>"</dt>
-
- <dd>
-
- <p>If the value is not exactly equal to a string obtained from
- the steps to <a href=#construct-a-websocket-url>construct a WebSocket URL</a> from <var title="">host</var>, <var title="">port</var>, <var title="">resource name</var>, and the <var title="">secure</var>
- flag, then <a href=#fail-the-websocket-connection>fail the WebSocket connection</a> and abort
- these steps.</p>
-
- </dd>
-
-
- <dt>If the entry's name is "<code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>sec-websocket-protocol</a></code>"</dt>
-
- <dd>
-
- <p>If the <var title="">protocols</var> list was not empty, and
- the value is not exactly equal to one of the strings in the <var title="">protocols</var> list, then <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a> and abort these steps.</p>
-
- <p>If the the value contains any characters outside the range
- U+0021 to U+007F, then <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a> and abort these steps.</p>
-
- <p>Otherwise, let the <dfn id=selected-websocket-subprotocol>selected WebSocket subprotocol</dfn>
- be the entry's value.</p>
-
- </dd>
-
-
- <dt>If the entry's name is "<code title=http-setcookie>set-cookie</code>" or "<code title=http-setcookie2>set-cookie2</code>" or another
- cookie-related field name</dt>
-
- <dd>
-
- <p>If the relevant specification is supported by the user agent,
- add the cookie, interpreted as defined by the appropriate
- specification, to the <var title="">list of cookies</var>, with
- the resource being the one with the host <var title="">host</var>, the port <var title="">port</var>, the path
- (and possibly query parameters) <var title="">resource
- name</var>, and the scheme <code title="">http</code> if <var title="">secure</var> is false and <code title="">https</code>
- if <var title="">secure</var> is true.
- <a href=#refsCOOKIES>[COOKIES]</a>
-
- </p>
-
- <p>If the relevant specification is not supported by the user
- agent, then the field must be ignored.</p>
-
- <p class=note>The cookies added to the <var title="">list of
- cookies</var> are discarded if the connection fails to be
- established. Only if and when the connection is established do
- the cookies actually get applied.</p>
-
- </dd>
-
-
- <!--UAS: 'Server' -->
-
-
- <dt>Any other name</dt>
-
- <dd>Ignore it.</dd>
-
- </dl><hr><!--(v2-redirect)
-redirect support
-we should probably reintroduce this at some point, with the
-multi-origin semantics described in [ORIGIN] applying. (http-origin)
-
- <p>If <var title="">mode</var> is <i title="">redirect</i>, then:
- If there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="">location</code>", then <span>fail the WebSocket
- connection</span> and abort these steps. Otherwise, handle each
- entry in the <var title="">fields</var> list as follows:</p>
-
- <dl class="switch">
-
- <dt>If the entry's name is "<code
- title="">location</code>"</dt>
-
- <dd>
-
- <ol>
-
- <li><p>Let <var title="">was secure</var> have the value of
- <var title="">secure</var>.</p></li>
-
- <li><p><span>Parse a WebSocket URL's components</span> from
- the <var title="">url</var> argument, to obtain new values for
- <var title="">host</var>, <var title="">port</var>, <var
- title="">resource name</var>, and <var
- title="">secure</var>. If this fails, <span>fail the WebSocket
- connection</span> and abort these steps.</p></li>
-
- <li><p>If <var title="">was secure</var> is true but <var
- title="">secure</var> is now false, <span>fail the WebSocket
- connection</span> and abort these steps.</p></li>
-
- <li><p>If <var title="">port</var> is a port to which the user
- agent is configured to block access, then <span>fail the
- WebSocket connection</span> and abort these steps. (User agents
- typically block access to well-known ports like SMTP.)</p></li>
-
- <li><p>Close the connection if the server has not already done
- so.</p></li>
-
- <li><p><span>Apply the cookies</span> in the <var title="">list
- of cookies</var>.</p></li>
-
- <li><p>Jump back to the first step of the overall algorithm
- (the very top of the handshake).</p></li>
-
- </ol>
-
- </dd>
-
-
- <dt>Any other name</dt>
-
- <dd>Ignore it.</dd>
-
- </dl>
---><!--(v2-ws-auth)
- <hr>
-
- <p>If <var title="">mode</var> is <i title="">authenticate</i>,
- then: If there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="">www-authenticate</code>", then <span>fail the WebSocket
- connection</span> and abort these steps. Otherwise, handle each
- entry in the <var title="">fields</var> list as follows:</p>
-
- <dl class="switch">
-
- <dt>If the entry's name is "<code
- title="">www-authenticate</code>"</dt>
-
- <dd>
-
- <p><span>Apply the cookies</span> in the <var title="">list of
- cookies</var>, then obtain credentials in a manner consistent
- with the requirements for handling the
- <code>WWW-Authenticate</code> header in HTTP, and then close
- the connection (if the server has not already done so) and jump
- back to the step labeled <i>connect</i>, including the relevant
- authentication headers in the new request.
- <a href="#refsHTTP">[HTTP]</a>
---><!--
- </p>
-
- </dd>
-
- <dt>Any other name</dt>
-
- <dd>Ignore it.</dd>
-
- </dl>
---></li>
-
- <li>
-
- <p>Let <var title="">challenge</var> be the concatenation of <var title="">number<sub>1</sub></var>, expressed as a big-endian
- unsigned 32-bit integer, <var title="">number<sub>2</sub></var>,
- expressed as a big-endian unsigned 32-bit integer, and the eight
- bytes of <var title="">key<sub>3</sub></var> in the order they
- were sent on the wire.</p>
-
- <!--
- perl -e 'foreach (@ARGV) { print pack 'N', $_ }' 777007543 114997259 | hexdump -C
- -->
-
- <p class=example>Using the examples given earlier, this leads to
- the 16 bytes 0x2E 0x50 0x31 0xB7 0x06 0xDA 0xB8 0x0B 0x47 0x30
- 0x22 0x2D 0x5A 0x3F 0x47 0x58.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">expected</var> be the MD5 fingerprint of <var title="">challenge</var> as a big-endian 128 bit string. <a href=#refsRFC1321>[RFC1321]</a></p>
-
- <!--
- perl -e "print pack 'c*', map { hex } @ARGV" 0x2E 0x50 0x31 0xB7 0x06 0xDA 0xB8 0x0B 0x47 0x30 0x22 0x2D 0x5A 0x3F 0x47 0x58 | md5sum -b
- -->
-
- <p class=example>Using the examples given earlier, this leads to
- the 16 bytes 0x30 0x73 0x74 0x33 0x52 0x6C 0x26 0x71 0x2D 0x32
- 0x5A 0x55 0x5E 0x77 0x65 0x75. In UTF-8, these bytes correspond to
- the string "0st3Rl&q-2ZU^weu".</p>
-
- </li>
-
- <li>
-
- <p>Read sixteen bytes from the server. Let <var title="">reply</var> be those bytes.</p>
-
- <p>If the connection closes before these bytes are received, then
- <a href=#fail-the-websocket-connection>fail the WebSocket connection</a> and abort these
- steps.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">reply</var> does not exactly equal <var title="">expected</var>, then <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a> and abort these steps.</p>
-
- </li>
-
- <li><p>If the <var title="">defer cookies</var> flag is not set,
- <a href=#apply-the-cookies>apply the cookies</a> in the <var title="">list of
- cookies</var>.</li>
-
- <li>
-
- <p>The <dfn id=websocket-connection-is-established>WebSocket connection is established</dfn>. Now the
- user agent must send and receive to and from the connection as
- described in the next section.</p>
-
- <p>If the <var title="">defer cookies</var> flag is set, store the
- <var title="">list of cookies</var> for use by the component that
- invoked this algorithm.</p>
-
- </li>
-
- </ol><p>Where the algorithm above requires that a user agent <a href=#fail-the-websocket-connection>fail
- the WebSocket connection</a>, the user agent may first read an
- arbitrary number of further bytes from the connection (and then
- discard them) before actually <a href=#fail-the-websocket-connection title="fail the WebSocket
- connection">failing the WebSocket connection</a>. Similarly, if a
- user agent can show that the bytes read from the connection so far
- are such that there is no subsequent sequence of bytes that the
- server can send that would not result in the user agent being
- required to <a href=#fail-the-websocket-connection>fail the WebSocket connection</a>, the user
- agent may immediately <a href=#fail-the-websocket-connection>fail the WebSocket connection</a>
- without waiting for those bytes.</p>
-
- <p class=note>The previous paragraph is intended to make it
- conforming for user agents to implement the algorithm in subtlely
- different ways that are equivalent in all ways except that they
- terminate the connection at earlier or later points. For example, it
- enables an implementation to buffer the entire handshake response
- before checking it, or to verify each field as it is received rather
- than collecting all the fields and then checking them as a
- block.</p>
-
- <p>When the user agent is to <dfn id=apply-the-cookies>apply the cookies</dfn> in a <var title="">list of cookies</var>, it must handle each cookie in the
- <var title="">list of cookies</var> as defined by the appropriate
- specification.
- <a href=#refsCOOKIES>[COOKIES]</a>
-
- </p>
-
-
- <h6 id=data-framing><span class=secno>10.3.4.4.2 </span>Data framing</h6>
-
- <p>Once a <a href=#websocket-connection-is-established>WebSocket connection is established</a>, the user
- agent must run through the following state machine for the bytes
- sent by the server. If at any point during these steps a read is
- attempted but fails because the <a href=#websocket-connection-is-closed>WebSocket connection is
- closed</a>, then abort.</p>
-
- <ol><li>
-
- <p>Try to read a byte from the server. Let <var title="">frame
- type</var> be that byte.</p>
-
- </li>
-
- <li>
-
- <p>Try to read eight more bytes from the server. Let <var title="">frame length</var> be the result of interpreting those
- eight bytes as a big-endian 64 bit unsigned integer.</p>
-
- </li>
-
- <li>
-
- <p>Try to read <var title="">frame length</var> bytes from the
- server. Let <var title="">raw data</var> be those bytes.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">error</var> be false.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">frame length</var> is greater than the length
- of data the user agent is able to deal with at this time, set <var title="">error</var> to true.</p>
-
- <p>User agents should ensure they are always able to deal with
- lengths up to at least 65536 bytes.</p>
-
- <p class=note>The minimum expected supported length will likely
- be increased in future revisions of this protocol.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">error</var> is still false, handle the <var title="">frame type</var> byte as follows:</p>
-
- <dl><dt>If the <var title="">frame type</var> byte is 0x00</dt>
-
- <dd>
-
- <p>If <var title="">frame length</var> is not zero, then set
- <var title="">error</var> to true. Otherwise, run these
- steps:</p>
-
- <ol><li>If <a href=#the-websocket-closing-handshake-has-started title="the WebSocket closing handshake has
- started">the WebSocket closing handshake has not yet
- started</a>, then <a href=#start-the-websocket-closing-handshake>start the WebSocket closing
- handshake</a>.</li>
-
- <li>Wait until either <a href=#the-websocket-closing-handshake-has-started>the WebSocket closing handshake
- has started</a> or the <a href=#websocket-connection-is-closed>WebSocket connection is
- closed</a>.</li>
-
- <li>If the <a href=#websocket-connection-is-closed title="WebSocket connection is
- closed">WebSocket connection is not already closed</a>,
- then <a href=#close-the-websocket-connection>close the WebSocket connection</a>: <dfn id=the-websocket-closing-handshake-has-finished>The
- WebSocket closing handshake has finished</dfn>. (If the
- connection closes before this happens, then the closing
- handshake doesn't finish.)</li>
-
- <li>Abort these steps. Any data on the connection after the
- 0x00 frame is discarded.</li>
-
- </ol></dd>
-
- <dt>If the <var title="">frame type</var> byte is 0xFF</dt>
-
- <dd>
-
- <p><dfn id=a-websocket-message-has-been-received>A WebSocket message has been received</dfn> with
- obtained by interpreting <var title="">raw data</var> as a UTF-8
- string.</p>
-
- </dd>
-
- <dt>Otherwise (the <var title="">frame type</var> byte is in the range 0x01 to 0xFE)</dt>
-
- <dd>
-
- <p>Set <var title="">error</var> to true.</p>
-
- </dd>
-
- </dl></li>
-
- <li>
-
- <p>If <var title="">error</var> is true, then <dfn id=a-websocket-error-has-been-detected>a WebSocket
- error has been detected</dfn>. Discard <var title="">raw
- data</var>.</p>
-
- </li>
-
- <li><p>Return to the first step to read the next byte.</li>
-
- </ol><p>If the user agent runs out of resources for buffering incoming
- data, or hits an artificial resource limit intended to avoid
- resource starvation, then it must <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a>.</p>
-
- <hr><p>Once a <a href=#websocket-connection-is-established>WebSocket connection is established</a>, but
- before <a href=#the-websocket-closing-handshake-has-started>the WebSocket closing handshake has started</a>, the
- user agent must use the following steps to <dfn id=send-data-using-the-websocket>send <var title="">data</var> using the WebSocket</dfn>:</p>
-
- <ol><li><p>Encode the text in <var title="">data</var> using UTF-8 to
- obtain the byte stream <var title="">bytes</var>.</li>
-
- <li><p>Send a 0xFF byte to the server.</li>
-
- <li><p>Send the number of bytes in <var title="">bytes</var>, as a
- 64 bit big-endian unsigned integer, to the server.</li>
-
- <li><p>Send <var title="">raw data</var> to the server.</li>
-
- </ol><p>Once <a href=#the-websocket-closing-handshake-has-started>the WebSocket closing handshake has started</a>,
- the user agent must not send any further data on the connection.</p>
-
- <hr><p>Once a <a href=#websocket-connection-is-established>WebSocket connection is established</a>, the user
- agent must use the following steps to <dfn id=start-the-websocket-closing-handshake>start the WebSocket
- closing handshake</dfn>. These steps must be run asynchronously
- relative to whatever algorithm invoked this one.</p>
-
- <ol><li><p>If <a href=#the-websocket-closing-handshake-has-started>the WebSocket closing handshake has started</a>,
- then abort these steps.</li>
-
- <li><p>Send nine 0x00 bytes to the server.</li>
-
- <li><p><dfn id=the-websocket-closing-handshake-has-started>The WebSocket closing handshake has started</dfn>.</li>
-
- <li><p>Wait a user-agent-determined length of time, or until the
- <a href=#websocket-connection-is-closed>WebSocket connection is closed</a>.</p>
-
- <li>If the <a href=#websocket-connection-is-closed title="WebSocket connection is closed">WebSocket
- connection is not already closed</a>, then <a href=#close-the-websocket-connection>close the
- WebSocket connection</a>. (If this happens, then the closing
- handshake doesn't finish.)</li>
-
- </ol><p class=note>If the user agent initiates it, the closing
- handshake <a href=#the-websocket-closing-handshake-has-finished title="the WebSocket closing handshake has
- finished">finishes</a> once the server returns the 0x00 frame, as
- described above.</p>
-
- <hr><p>If at any point there is a fatal problem with sending data to the
- server, the user agent must <a href=#fail-the-websocket-connection>fail the WebSocket
- connection</a>.</p>
-
-
- <h6 id=handling-errors-in-utf-8-from-the-server><span class=secno>10.3.4.4.3 </span>Handling errors in UTF-8 from the server</h6>
-
- <p>When a client is to interpret a byte stream as UTF-8 but finds
- that the byte stream is not in fact a valid UTF-8 stream, then any
- bytes or sequences of bytes that are not valid UTF-8 sequences must
- be interpreted as a U+FFFD REPLACEMENT CHARACTER.</p>
-
-
-
- <h5 id=server-side-requirements><span class=secno>10.3.4.5 </span>Server-side requirements</h5>
-
- <p><i>This section only applies to servers.</i></p>
-
- <p>Servers may offload the management of the connection to other
- agents on the network, for example load balancers and reverse
- proxies. In such a situation, the server for the purposes of
- conformance is considered to include all parts of the server-side
- infrastructure from the first device to terminate the TCP connection
- all the way to the server that processes requests and sends
- responses.</p>
-
- <div class=example>
-
- <p>For example, a data center might have a server that responds to
- Web Socket requests with an appropriate handshake, and then passes
- the connection to another server to actually process the data
- frames. For the purposes of this specification, the "server" is the
- combination of both computers.</p>
-
- </div>
-
-
- <h6 id="reading-the-client's-opening-handshake"><span class=secno>10.3.4.5.1 </span>Reading the client's opening handshake</h6>
-
- <p>When a client starts a WebSocket connection, it sends its part of
- the opening handshake. The server must parse at least part of this
- handshake in order to obtain the necessary information to generate
- the server part of the handshake.</p>
-
- <p>The client handshake consists of the following parts. If the
- server, while reading the handshake, finds that the client did not
- send a handshake that matches the description below, the server
- should <a href=#abort-the-websocket-connection>abort the WebSocket connection</a>.</p>
-
- <ol><li><p>The three-character UTF-8 string "GET".</li>
-
- <li><p>A UTF-8-encoded U+0020 SPACE character (0x20 byte).</li>
-
- <li><p>A string consisting of all the bytes up to the next
- UTF-8-encoded U+0020 SPACE character (0x20 byte). The result of
- decoding this string as a UTF-8 string is the name of the resource
- requested by the server. If the server only supports one resource,
- then this can safely be ignored; the client verifies that the right
- resource is supported based on the information included in the
- server's own handshake. The resource name will begin with U+002F
- SOLIDUS character (/) and will only include characters in the range
- U+0021 to U+007E.</li>
-
- <li><p>A string of bytes terminated by a UTF-8-encoded U+000D
- CARRIAGE RETURN U+000A LINE FEED character pair (CRLF). All the
- characters from the second 0x20 byte up to the first 0x0D 0x0A byte
- pair in the data from the client can be safely ignored. (It will
- probably be the string "HTTP/1.1".)</p>
-
- <li>
-
- <p>A series of fields.</p>
-
- <p>Each field is terminated by a UTF-8-encoded U+000D CARRIAGE
- RETURN U+000A LINE FEED character pair (CRLF). The end of the
- fields is denoted by the terminating CRLF pair being followed
- immediately by another CRLF pair.</p>
-
- <p class=note>In other words, the fields start with the first
- 0x0D 0x0A byte pair, end with the first 0x0D 0x0A 0x0D 0x0A byte
- sequence, and are separate from each other by 0x0D 0x0A byte
- pairs.</p>
-
- <p>The fields are encoded as UTF-8.</p>
-
- <p>Each field consists of a name, consisting of one or more
- characters in the ranges U+0021 to U+0039 and U+003B to U+007E,
- followed by a U+003A COLON character (:) and a U+0020 SPACE
- character, followed by zero or more characters forming the
- value.</p>
-
- <p>The expected field names, the meaning of their corresponding
- values, and the processing servers are required to apply to those
- fields, are described below, after the description of the client
- handshake.</p>
-
- </li>
-
- <li>
-
- <p>After the first 0x0D 0x0A 0x0D 0x0A byte sequence, indicating
- the end of the fields, the client sends eight random bytes. These
- are used in constructing the server handshake.</p>
-
- </li>
-
- </ol><p>The expected field names, and the meaning of their corresponding
- values, are as follows. Field names must be compared in an
- <a href=#ascii-case-insensitive>ASCII case-insensitive</a> manner.</p>
-
- <dl><dt><code title=http-upgrade>Upgrade</code></dt>
-
- <dd>
-
- <p>Invariant part of the handshake. Will always have a value that
- is an <a href=#ascii-case-insensitive>ASCII case-insensitive</a> match for the string
- "WebSocket".</p>
-
- <p>Can be safely ignored, though the server should <a href=#abort-the-websocket-connection>abort the WebSocket
- connection</a> if this field is absent or has a different
- value, to avoid vulnerability to cross-protocol attacks.</p>
-
- </dd>
-
- <dt><code title=http-connection>Connection</code></dt>
-
- <dd>
-
- <p>Invariant part of the handshake. Will always have a value that
- is an <a href=#ascii-case-insensitive>ASCII case-insensitive</a> match for the string
- "Upgrade".</p>
-
- <p>Can be safely ignored, though the server should <a href=#abort-the-websocket-connection>abort the WebSocket
- connection</a> if this field is absent or has a different
- value, to avoid vulnerability to cross-protocol attacks.</p>
-
- </dd>
-
- <dt><code title=http-host>Host</code></dt>
-
- <dd>
-
- <p>The value gives the hostname that the client intended to use
- when opening the WebSocket. It would be of interest in particular
- to virtual hosting environments, where one server might serve
- multiple hosts, and might therefore want to return different
- data.</p>
-
- <p>Can be safely ignored, though the server should <a href=#abort-the-websocket-connection>abort the WebSocket
- connection</a> if this field is absent or has a value that
- does not match the server's host name, to avoid vulnerability to
- cross-protocol attacks and DNS rebinding attacks.</p>
-
- </dd>
-
- <dt><code title=http-origin>Origin</code></dt>
-
- <dd>
-
- <p>The value gives the scheme, hostname, and port (if it's not the
- default port for the given scheme) of the page that asked the
- client to open the WebSocket. It would be interesting if the
- server's operator had deals with operators of other sites, since
- the server could then decide how to respond (or indeed,
- <em>whether</em> to respond) based on which site was requesting a
- connection. <a href=#refsORIGIN>[ORIGIN]</a></p>
-
- <p>Can be safely ignored, though the server should <a href=#abort-the-websocket-connection>abort the WebSocket
- connection</a> if this field is absent or has a value that
- does not match one of the origins the server is expecting to
- communicate with, to avoid vulnerability to cross-protocol attacks
- and cross-site scripting attacks.</p>
-
- </dd>
-
- <dt><code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>Sec-WebSocket-Protocol</a></code></dt>
-
- <dd>
-
- <p>The value gives the names of subprotocols that the client is
- willing to use, as a space-separated list in the order that the
- client prefers the protocols. It would be interesting if the
- server supports multiple protocols or protocol versions.</p>
-
- <p>Can be safely ignored, though the server may <a href=#abort-the-websocket-connection>abort the
- WebSocket connection</a> if the field is absent but the
- conventions for communicating with the server are such that the
- field is expected; and the server should <a href=#abort-the-websocket-connection>abort the WebSocket
- connection</a> if the field does not contain a value that does
- matches one of the subprotocols that the server supports, to avoid
- integrity errors once the connection is established.</p>
-
- </dd>
-
- <dt><code title=http-sec-websocket-key1><a href=#sec-websocket-key1-and-sec-websocket-key2>Sec-WebSocket-Key1</a></code></dt>
- <dt><code title=http-sec-websocket-key2><a href=#sec-websocket-key1-and-sec-websocket-key2>Sec-WebSocket-Key2</a></code></dt>
-
- <dd>
-
- <p>The values provide the information required for computing the
- server's handshake, as described in the next section.</p>
-
- </dd>
-
- <!--UAS: 'User-Agent' -->
-
- <dt>Other fields</dt>
-
- <dd>
-
- <p>Other fields can be used, such as "<code title="">Cookie</code>"<!--(v2-ws-auth) or
- "<code>Authorization</code>"-->, for authentication
- purposes. Their semantics are equivalent to the semantics of the
- HTTP headers with the same names.</p>
-
- </dd>
-
- </dl><p>Unrecognized fields can be safely ignored, and are probably
- either the result of intermediaries injecting fields unrelated to
- the operation of the WebSocket protocol, or clients that support
- future versions of the protocol offering options that the server
- doesn't support.</p>
-
-
- <h6 id="sending-the-server's-opening-handshake"><span class=secno>10.3.4.5.2 </span>Sending the server's opening handshake</h6>
-
- <p>When a client establishes a WebSocket connection to a server, the
- server must run the following steps.</p>
-
- <ol><li>
-
- <p>If the server supports encryption, perform a TLS handshake over
- the connection. If this fails (e.g. the client indicated a host
- name in the extended client hello "server_name" extension that the
- server does not host), then close the connection; otherwise, all
- further communication for the connection (including the server
- handshake) must run through the encrypted tunnel. <a href=#refsRFC2246>[RFC2246]</a></p>
-
- <p>Servers must support the Next Protocol Negotiation extension in
- the TLS handshake, advertising support for the
- "776562736f636b6574" protocol ("websocket" in UTF-8). <a href=#refsNPN>[NPN]</a>
-
- </li>
-
- <li>
-
- <p>Establish the following information:</p>
-
- <dl><dt><var title="">host</var></dt>
-
- <dd>The host name or IP address of the WebSocket server, as it is
- to be addressed by clients. The host name must be
- punycode-encoded if necessary. If the server can respond to
- requests to multiple hosts (e.g. in a virtual hosting
- environment), then the value should be derived from the client's
- handshake, specifically from the "<code title=http-host>Host</code>" field. The <var title="">host</var> value must be lowercase (not containing
- characters in the range U+0041 LATIN CAPITAL LETTER A to U+005A
- LATIN CAPITAL LETTER Z).</dd>
-
- <dt><var title="">port</var></dt>
-
- <dd>The port number on which the server expected and/or received
- the connection.</dd>
-
- <dt><var title="">resource name</var></dt>
-
- <dd>An identifier for the service provided by the server. If the
- server provides multiple services, then the value should be
- derived from the resource name given in the client's
- handshake.</dd>
-
- <dt><var title="">secure flag</var></dt>
-
- <dd>True if the connection is encrypted or if the server expected
- it to be encrypted; false otherwise.</dd>
-
- <dt><var title="">origin</var></dt>
-
- <dd>The <a href=#ascii-serialization-of-an-origin title="ASCII serialization of an origin">ASCII
- serialization</a> of the origin that the server is willing to
- communicate with, <a href=#converted-to-ascii-lowercase>converted to ASCII lowercase</a>. If
- the server can respond to requests from multiple origins (or
- indeed, all origins), then the value should be derived from the
- client's handshake, specifically from the "<code title=http-origin>Origin</code>" field. <a href=#refsORIGIN>[ORIGIN]</a></dd>
-
- <dt><var title="">subprotocol</var></dt>
-
- <dd>Either null, or a string representing the subprotocol the
- server is ready to use. If the server supports multiple
- subprotocols, then the value should be derived from the client's
- handshake, specifically from the "<code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>Sec-WebSocket-Protocol</a></code>"
- field. The absence of such a field is equivalent to the null
- value. The empty string is not the same as the null value for
- these purposes.</dd>
-
- <dt><var title="">key<sub title="">1</sub></var></dt>
-
- <dd>The value of the "<code title=http-sec-websocket-key1><a href=#sec-websocket-key1-and-sec-websocket-key2>Sec-WebSocket-Key1</a></code>"
- field in the client's handshake.</dd>
-
- <dt><var title="">key<sub title="">2</sub></var></dt>
-
- <dd>The value of the "<code title=http-sec-websocket-key2><a href=#sec-websocket-key1-and-sec-websocket-key2>Sec-WebSocket-Key2</a></code>"
- field in the client's handshake.</dd>
-
- <dt><var title="">key<sub title="">3</sub></var></dt>
-
- <dd>The eight random bytes sent after the first 0x0D 0x0A 0x0D
- 0x0A sequence in the client's handshake.</dd>
-
- </dl></li>
-
- <li>
-
- <p>Let <var title="">location</var> be the string that results
- from <a href=#construct-a-websocket-url title="construct a WebSocket URL">constructing a
- WebSocket URL</a> from <var title="">host</var>, <var title="">port</var>, <var title="">resource name</var>, and <var title="">secure flag</var>.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">key-number<sub title="">1</sub></var> be the digits (characters
- in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9)) in
- <var title="">key<sub title="">1</sub></var>, interpreted as a base ten integer,
- ignoring all other characters in <var title="">key<sub title="">1</sub></var>.</p>
-
- <p>Let <var title="">key-number<sub title="">2</sub></var> be the digits (characters
- in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9)) in
- <var title="">key<sub title="">2</sub></var>, interpreted as a base ten integer,
- ignoring all other characters in <var title="">key<sub title="">2</sub></var>.</p>
-
- <p>If either <var title="">key-number<sub title="">1</sub></var>
- or <var title="">key-number<sub title="">2</sub></var> is greater
- than 4,294,967,295, then <a href=#abort-the-websocket-connection>abort the WebSocket
- connection</a>. This is a symptom of an attack.</p>
-
- <p class=note>If the client is a conforming client, then both
- <var title="">key-number<sub title="">1</sub></var> and <var title="">key-number<sub title="">2</sub></var> will fit in
- unsigned 32-bit integers.</p>
-
- <div class=example>
-
- <p>For example, assume that the client handshake was:</p>
-
- <pre>GET / HTTP/1.1
-Connection: Upgrade
-Host: example.com
-Upgrade: WebSocket
-Sec-WebSocket-Key1: 3e6b263 4 17 80
-Origin: http://example.com
-Sec-WebSocket-Key2: 17 9 G`ZD9 2 2b 7X 3 /r90
-
-WjN}|M(6</pre>
-
- <p>The <var title="">key-number<sub title="">1</sub></var> would be the number
- 3,626,341,780, and the <var title="">key-number<sub title="">2</sub></var> would be
- the number 1,799,227,390.</p>
-
- <p>In this example, incidentally, <var title="">key<sub title="">3</sub></var> is
- "WjN}|M(6", or 0x57 0x6A 0x4E 0x7D 0x7C 0x4D 0x28 0x36.</p>
-
- </div>
-
- </li>
-
- <li>
-
- <p>Let <var title="">spaces<sub title="">1</sub></var> be the number of U+0020 SPACE
- characters in <var title="">key<sub title="">1</sub></var>.</p>
-
- <p>Let <var title="">spaces<sub title="">2</sub></var> be the number of U+0020 SPACE
- characters in <var title="">key<sub title="">2</sub></var>.</p>
-
- <p>If either <var title="">spaces<sub title="">1</sub></var> or
- <var title="">spaces<sub title="">2</sub></var> is zero, then
- <a href=#abort-the-websocket-connection>abort the WebSocket connection</a>. This is a symptom of
- a cross-protocol attack.</p>
-
- <p class=note>If the client is a conforming client, then both
- <var title="">spaces<sub title="">1</sub></var> and <var title="">spaces<sub title="">2</sub></var> will easily fit in
- unsigned 32-bit integers (indeed, they won't be greater than
- 12).</p>
-
- <p class=example>In the example above, <var title="">spaces<sub title="">1</sub></var> would be 4 and <var title="">spaces<sub title="">2</sub></var>
- would be 10.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">key-number<sub title="">1</sub></var> is not an integral multiple
- of <var title="">spaces<sub title="">1</sub></var>, then <a href=#abort-the-websocket-connection>abort the WebSocket
- connection</a>.</p>
-
- <p>If <var title="">key-number<sub title="">2</sub></var> is not an integral multiple
- of <var title="">spaces<sub title="">2</sub></var>, then <a href=#abort-the-websocket-connection>abort the WebSocket
- connection</a>.</p>
-
- <p class=note>This can only happen if the client is not a
- conforming WebSocket client.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">part<sub title="">1</sub></var> be <var title="">key-number<sub title="">1</sub></var> divided by <var title="">spaces<sub title="">1</sub></var>.</p>
-
- <p>Let <var title="">part<sub title="">2</sub></var> be <var title="">key-number<sub title="">2</sub></var> divided by <var title="">spaces<sub title="">2</sub></var>.</p>
-
- <p class=example>In the example above, <var title="">part<sub title="">1</sub></var>
- would be 906,585,445 and <var title="">part<sub title="">2</sub></var> would be
- 179,922,739.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">challenge</var> be the concatenation of <var title="">part<sub title="">1</sub></var>, expressed as a
- big-endian unsigned 32-bit integer, <var title="">part<sub title="">2</sub></var>, expressed as a big-endian unsigned 32-bit
- integer, and the eight bytes of <var title="">key<sub title="">3</sub></var> in the order they were sent on the
- wire.</p>
-
- <!--
- perl -e 'foreach (@ARGV) { print pack 'N', $_ }' 906585445 179922739 | hexdump -C
- -->
-
- <p class=example>In the example above, this would be the 16
- bytes 0x36 0x09 0x65 0x65 0x0A 0xB9 0x67 0x33 0x57 0x6A 0x4E 0x7D
- 0x7C 0x4D 0x28 0x36.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">response</var> be the MD5 fingerprint of <var title="">challenge</var> as a big-endian 128 bit string. <a href=#refsRFC1321>[RFC1321]</a></p>
-
- <!--
- perl -e "print pack 'c*', map { hex } @ARGV" 0x36 0x09 0x65 0x65 0x0A 0xB9 0x67 0x33 0x57 0x6A 0x4E 0x7D 0x7C 0x4D 0x28 0x36 | md5sum -b
- -->
-
- <p class=example>In the example above, this would be the 16
- bytes 0x6E 0x60 0x39 0x65 0x42 0x6B 0x39 0x7A 0x24 0x52 0x38 0x70
- 0x4F 0x74 0x56 0x62, or "n`9eBk9z$R8pOtVb" in UTF-8.
-
- </li>
-
- <li>
-
- <p>Send the following line, terminated by the two characters
- U+000D CARRIAGE RETURN and U+000A LINE FEED (CRLF) and encoded as
- UTF-8, to the client:</p>
-
- <pre>HTTP/1.1 101 WebSocket Protocol Handshake</pre>
-
- <p>This line may be sent differently if necessary, but must match
- the Status-Line production defined in the HTTP specification, with
- the Status-Code having the value 101.</p>
-
- </li>
-
- <li>
-
- <p>Send the following fields to the client. Each field must be
- sent as a line consisting of the field name, which must be an
- <a href=#ascii-case-insensitive>ASCII case-insensitive</a> match for the field name in
- the list below, followed by a U+003A COLON character (:) and a
- U+0020 SPACE character, followed by the field value as specified
- in the list below, followed by the two characters U+000D CARRIAGE
- RETURN and U+000A LINE FEED (CRLF). The lines must be encoded as
- UTF-8. The lines may be sent in any order.</p>
-
- <dl><dt><code title=http-upgrade>Upgrade</code></dt>
-
- <dd><p>The value must be the string "WebSocket".</dd>
-
- <dt><code title=http-connection>Connection</code></dt>
-
- <dd><p>The value must be the string "Upgrade".</dd>
-
- <dt><code title=http-sec-websocket-location><a href=#sec-websocket-location>Sec-WebSocket-Location</a></code></dt>
-
- <dd><p>The value must be <var title="">location</var></dd>
-
- <dt><code title=http-sec-websocket-origin><a href=#sec-websocket-origin>Sec-WebSocket-Origin</a></code></dt>
-
- <dd><p>The value must be <var title="">origin</var></dd>
-
- <dt><code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>Sec-WebSocket-Protocol</a></code></dt>
-
- <dd>
-
- <p>This field must be included if <var title="">subprotocol</var> is not null, and must not be included
- if <var title="">subprotocol</var> is null.</p>
-
- <p>If included, the value must be <var title="">subprotocol</var></p>
-
- </dd>
-
- </dl><p>Optionally, include "<code title=http-setcookie>Set-Cookie</code>", "<code title=http-setcookie2>Set-Cookie2</code>", or other
- cookie-related fields, with values equal to the values that would
- be used for the identically named HTTP headers.
- <a href=#refsCOOKIES>[COOKIES]</a>
-
- </p>
-
- <!--UAS: optionally, include 'Server:' field -->
-
- </li>
-
- <li>
-
- <p>Send two bytes 0x0D 0x0A (UTF-8 CRLF).</p>
-
- </li>
-
- <li>
-
- <p>Send <var title="">response</var>.</p>
-
- </li>
-
- </ol><p>This completes the server's handshake. If the server finishes
- these steps without <a href=#abort-the-websocket-connection title="abort the WebSocket
- connection">aborting the WebSocket connection</a>, and if the
- client does not then <a href=#fail-the-websocket-connection>fail the WebSocket connection</a>,
- then the connection is established and the server may begin and
- receiving sending data, as described in the next section.</p>
-
-
-
- <h6 id=ws-sd-framing><span class=secno>10.3.4.5.3 </span>Data framing</h6>
-
- <p>The server must run through the following steps to process the
- bytes sent by the client. If at any point during these steps a read
- is attempted but fails because the <a href=#websocket-connection-is-closed>WebSocket connection is
- closed</a>, then abort.</p>
-
- <ol><li>
-
- <p>Try to read a byte from the client. Let <var title="">frame
- type</var> be that byte.</p>
-
- </li>
-
- <li>
-
- <p>Try to read eight more bytes from the client. Let <var title="">frame length</var> be the result of interpreting those
- eight bytes as a big-endian 64 bit unsigned integer.</p>
-
- </li>
-
- <li>
-
- <p>Try to read <var title="">frame length</var> bytes from the
- client. Let <var title="">raw data</var> be those bytes.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">frame length</var> is greater than the length
- of data the server is able to deal with at this time, the server
- may abort these steps and either immediately disconnect from the
- client or set the <var title="">client terminated</var>
- flag. Alternatively, the server may just discard this frame and
- jump back to the first step.</p>
-
- </li>
-
- <li>
-
- <p>Handle the <var title="">frame type</var> byte as follows:</p>
-
- <dl><dt>If the <var title="">frame type</var> byte is 0x00 and the <var title="">frame length</var> is 0</dt>
-
- <dd>
-
- <p>Set the <var title="">client terminated</var> flag and abort
- these steps. All further data sent by the client should be
- discarded.</p>
-
- </dd>
-
- <dt>If the <var title="">frame type</var> byte is 0xFF</dt>
-
- <dd>
-
- <p>Interpret <var title="">raw data</var> as a UTF-8 string, and
- apply whatever server-specific processing is to occur for the
- resulting string (the message from the client).</p>
-
- </dd>
-
- <dt>Otherwise</dt>
-
- <dd>
-
- <p>The server may abort these steps and either immediately
- disconnect from the client or set the <var title="">client
- terminated</var> flag.</p>
-
- </dd>
-
- </dl></li>
-
- <li><p>Return to the first step to read the next byte.</li>
-
- </ol><hr><p>The server must run through the following steps to send strings
- to the client:</p>
-
- <ol><li><p>Encode the text using UTF-8 to obtain the byte stream <var title="">raw data</var>.</li>
-
- <li><p>Send a 0xFF byte to the client.</li>
-
- <li><p>Send the number of bytes in <var title="">raw data</var>, as
- a 64 bit big-endian unsigned integer, to the client.</li>
-
- <li><p>Send <var title="">raw data</var> to the client.</li>
-
- </ol><hr><p>At any time, the server may decide to terminate the WebSocket
- connection by running through the following steps. These steps
- should be run when the <var title="">client terminated</var> flag is
- set, if they aren't already running.</p>
-
- <ol><li><p>Send nine 0x00 bytes to the client to indicate the start of
- the closing handshake.</li>
-
- <li><p>Wait until the <var title="">client terminated</var> flag
- has been set, or until a server-defined timeout expires.</li>
-
- <li><p><a href=#close-the-websocket-connection>Close the WebSocket connection</a>.</li>
-
- </ol><p>Once these steps have started, the server must not send any
- further data to the client. The nine 0x00 bytes indicate the end of
- the server's data, and further bytes will be discarded by the
- client.</p>
-
-
- <h6 id=handling-errors-in-utf-8-from-the-client><span class=secno>10.3.4.5.4 </span>Handling errors in UTF-8 from the client</h6>
-
- <p>When a server is to interpret a byte stream as UTF-8 but finds
- that the byte stream is not in fact a valid UTF-8 stream, behavior
- is undefined. A server could close the connection, convert invalid
- byte sequences to U+FFFD REPLACEMENT CHARACTERs, store the data
- verbatim, or perform application-specific processing. Subprotocols
- layered on the WebSocket protocol might define specific behavior
- for servers.</p>
-
-
-
- <h5 id=closing-the-connection><span class=secno>10.3.4.6 </span>Closing the connection</h5>
-
- <h6 id=client-initiated-closure><span class=secno>10.3.4.6.1 </span>Client-initiated closure</h6>
-
- <p>Certain algorithms require the user agent to <dfn id=fail-the-websocket-connection>fail the
- WebSocket connection</dfn>. To do so, the user agent must
- <a href=#close-the-websocket-connection>close the WebSocket connection</a>, and may report the
- problem to the user (which would be especially useful for
- developers).</p>
-
- <p>Except as indicated above or as specified by the application
- layer (e.g. a script using the WebSocket API), user agents should
- not close the connection.</p>
-
- <p>User agents must not convey any failure information to scripts in
- a way that would allow a script to distinguish the following
- situations:</p>
-
- <ul><li>A server whose host name could not be resolved.</li>
-
- <li>A server to which packets could not successfully be
- routed.</li>
-
- <li>A server that refused the connection on the specified
- port.</li>
-
- <li>A server that did not complete the opening handshake
- (e.g. because it was not a WebSocket server).</li>
-
- <li>A WebSocket server that sent a correct opening handshake, but
- that specified options that caused the client to drop the
- connection (e.g. the server specified an origin that differed from
- the script's).</li>
-
- <li>A WebSocket server that abruptly closed the connection after
- successfully completing the opening handshake.</li>
-
- </ul><h6 id=server-initiated-closure><span class=secno>10.3.4.6.2 </span>Server-initiated closure</h6>
-
- <p>Certain algorithms require or recommend that the server
- <dfn id=abort-the-websocket-connection>abort the WebSocket connection</dfn> during the opening
- handshake. To do so, the server must simply <a href=#close-the-websocket-connection>close the
- WebSocket connection</a>.</p>
-
-
- <h6 id=closure><span class=secno>10.3.4.6.3 </span>Closure</h6>
-
- <p>To <dfn id=close-the-websocket-connection>close the WebSocket connection</dfn>, the user agent or
- server must close the TCP connection, using whatever mechanism
- possible (e.g. either the TCP RST or FIN mechanisms). When a user
- agent notices that the server has closed its connection, it must
- immediately close its side of the connection also. Whether the user
- agent or the server closes the connection first, it is said that the
- <dfn id=websocket-connection-is-closed>WebSocket connection is closed</dfn>. If the connection was
- closed after the client <a href=#the-websocket-closing-handshake-has-finished title="the WebSocket closing handshake
- has finished">finished the WebSocket closing handshake</a>, then
- the WebSocket connection is said to have been closed <i title="">cleanly</i>.</p>
-
- <p>Servers may <a href=#close-the-websocket-connection>close the WebSocket connection</a> whenever
- desired. User agents should not <a href=#close-the-websocket-connection>close the WebSocket
- connection</a> arbitrarily.</p>
-
-
- <h5 id=security-considerations><span class=secno>10.3.4.7 </span>Security considerations</h5>
-
- <p>While this protocol is intended to be used by scripts in Web
- pages, it can also be used directly by hosts. Such hosts are acting
- on their own behalf, and can therefore send fake "Origin" fields,
- misleading the server. Servers should therefore be careful about
- assuming that they are talking directly to scripts from known
- origins, and must consider that they might be accessed in unexpected
- ways. In particular, a server should not trust that any input is
- valid.</p>
-
- <p class=example>For example, if the server uses input as part of
- SQL queries, all input text should be escaped before being passed to
- the SQL server, lest the server be susceptible to SQL injection.</p>
-
- <hr><p>Servers that are not intended to process input from any Web page
- but only for certain sites should verify the "Origin" field is an
- origin they expect, and should only respond with the corresponding
- "Sec-WebSocket-Origin" if it is an accepted origin. Servers that
- only accept input from one origin can just send back that value in
- the "Sec-WebSocket-Origin" field, without bothering to check the
- client's value.</p>
-
- <hr><p>If at any time a server is faced with data that it does not
- understand, or that violates some criteria by which the server
- determines safety of input, or when the server sees a handshake that
- does not correspond to the values the server is expecting
- (e.g. incorrect path or origin), the server should just
- disconnect. It is always safe to disconnect.</p>
-
- <hr><p>The biggest security risk when sending text data using this
- protocol is sending data using the wrong encoding. If an attacker
- can trick the server into sending data encoded as ISO-8859-1
- verbatim (for instance), rather than encoded as UTF-8, then the
- attacker could inject arbitrary frames into the data stream.</p>
-
-
- <h5 id=iana-considerations-0><span class=secno>10.3.4.8 </span>IANA considerations</h5>
-
- <h6 id=registration-of-ws:-scheme><span class=secno>10.3.4.8.1 </span>Registration of <code title="">ws:</code> scheme</h6>
-
- <p>A <code title="">ws:</code> URL identifies a WebSocket server
- and resource name.</p>
-
- <dl><dt>URI scheme name.</dt>
- <dd>ws</dd>
-
- <dt>Status.</dt>
- <dd>Permanent.</dd>
-
- <dt>URI scheme syntax.</dt>
- <dd>
- <p>In ABNF terms using the terminals from the URI specifications:
- <a href=#refsABNF>[ABNF]</a>
-
- <a href=#refsRFC3986>[RFC3986]</a>
- </p>
- <pre>"ws" ":" hier-part [ "?" query ]</pre>
- <p>The path and query components form the resource name sent to
- the server to identify the kind of service desired. Other
- components have the meanings described in RFC3986.</p>
- </dd>
-
- <dt>URI scheme semantics.</dt>
- <dd>The only operation for this scheme is to open a connection
- using the WebSocket protocol.</dd>
-
- <dt>Encoding considerations.</dt>
- <dd>
-
- <p>Characters in the host component that are excluded by the
- syntax defined above must be converted from Unicode to ASCII by
- applying the IDNA ToASCII algorithm to the Unicode host name, with
- both the AllowUnassigned and UseSTD3ASCIIRules flags set, and
- using the result of this algorithm as the host in the URI. <a href=#refsRFC3490>[RFC3490]</a></p>
-
- <p>Characters in other components that are excluded by the syntax
- defined above must be converted from Unicode to ASCII by first
- encoding the characters as UTF-8 and then replacing the
- corresponding bytes using their percent-encoded form as defined in
- the URI and IRI specification. <a href=#refsRFC3986>[RFC3986]</a> <a href=#refsRFC3987>[RFC3987]</a></p>
-
- </dd>
-
- <dt>Applications/protocols that use this URI scheme name.</dt>
- <dd>WebSocket protocol.</dd>
-
- <dt>Interoperability considerations.</dt>
- <dd>None.</dd>
-
- <dt>Security considerations.</dt>
- <dd>See "Security considerations" section above.</dd>
-
- <dt>Contact.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>Author/Change controller.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>References.</dt>
- <dd>This document.</dd>
-
- </dl><h6 id=registration-of-wss:-scheme><span class=secno>10.3.4.8.2 </span>Registration of <code title="">wss:</code> scheme</h6>
-
- <p>A <code title="">wss:</code> URL identifies a WebSocket server
- and resource name, and indicates that traffic over that connection
- is to be encrypted.</p>
-
- <dl><dt>URI scheme name.</dt>
- <dd>wss</dd>
-
- <dt>Status.</dt>
- <dd>Permanent.</dd>
-
- <dt>URI scheme syntax.</dt>
- <dd>
- <p>In ABNF terms using the terminals from the URI specifications:
- <a href=#refsABNF>[ABNF]</a>
-
- <a href=#refsRFC3986>[RFC3986]</a></p>
- <pre>"wss" ":" hier-part [ "?" query ]</pre>
- <p>The path and query components form the resource name sent to
- the server to identify the kind of service desired. Other
- components have the meanings described in RFC3986.</p>
- </dd>
-
- <dt>URI scheme semantics.</dt>
- <dd>The only operation for this scheme is to open a connection
- using the WebSocket protocol, encrypted using TLS.</dd>
-
- <dt>Encoding considerations.</dt>
- <dd>
-
- <p>Characters in the host component that are excluded by the
- syntax defined above must be converted from Unicode to ASCII by
- applying the IDNA ToASCII algorithm to the Unicode host name, with
- both the AllowUnassigned and UseSTD3ASCIIRules flags set, and
- using the result of this algorithm as the host in the URI. <a href=#refsRFC3490>[RFC3490]</a></p>
-
- <p>Characters in other components that are excluded by the syntax
- defined above must be converted from Unicode to ASCII by first
- encoding the characters as UTF-8 and then replacing the
- corresponding bytes using their percent-encoded form as defined in
- the URI and IRI specification. <a href=#refsRFC3986>[RFC3986]</a> <a href=#refsRFC3987>[RFC3987]</a></p>
-
- </dd>
-
- <dt>Applications/protocols that use this URI scheme name.</dt>
- <dd>WebSocket protocol over TLS.</dd>
-
- <dt>Interoperability considerations.</dt>
- <dd>None.</dd>
-
- <dt>Security considerations.</dt>
- <dd>See "Security considerations" section above.</dd>
-
- <dt>Contact.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>Author/Change controller.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>References.</dt>
- <dd>This document.</dd>
-
- </dl><h6 id=registration-of-the-websocket-http-upgrade-keyword><span class=secno>10.3.4.8.3 </span>Registration of the "<code title="">WebSocket</code>" HTTP Upgrade keyword</h6>
-
- <dl><dt>Name of token.</dt>
- <dd>WebSocket</dd>
-
- <dt>Author/Change controller.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>Contact.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>References.</dt>
- <dd>This document.</dd>
-
- </dl><h6 id=sec-websocket-key1-and-sec-websocket-key2><span class=secno>10.3.4.8.4 </span><dfn title=http-sec-websocket-key1><code>Sec-WebSocket-Key1</code></dfn> and <dfn title=http-sec-websocket-key2><code>Sec-WebSocket-Key2</code></dfn></h6>
-
- <p>This section describes two header fields for registration in the
- Permanent Message Header Field Registry. <a href=#refsRFC3864>[RFC3864]</a></p>
-
- <dl><dt>Header field name</dt>
- <dd>Sec-WebSocket-Key1</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl><dl><dt>Header field name</dt>
- <dd>Sec-WebSocket-Key2</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl><p>The <code title=http-sec-websocket-key1><a href=#sec-websocket-key1-and-sec-websocket-key2>Sec-WebSocket-Key1</a></code> and <code title=http-sec-websocket-key2><a href=#sec-websocket-key1-and-sec-websocket-key2>Sec-WebSocket-Key2</a></code> headers
- are used in the WebSocket handshake. They are sent from the client
- to the server to provide part of the information used by the server
- to prove that it received a valid WebSocket handshake. This helps
- ensure that the server does not accept connections from
- non-Web-Socket clients (e.g. HTTP clients) that are being abused to
- send data to unsuspecting WebSocket servers.</p>
-
-
- <h6 id=sec-websocket-location><span class=secno>10.3.4.8.5 </span><dfn title=http-sec-websocket-location><code>Sec-WebSocket-Location</code></dfn></h6>
-
- <p>This section describes a header field for registration in the
- Permanent Message Header Field Registry. <a href=#refsRFC3864>[RFC3864]</a></p>
-
- <dl><dt>Header field name</dt>
- <dd>Sec-WebSocket-Location</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl><p>The <code title=http-sec-websocket-location><a href=#sec-websocket-location>Sec-WebSocket-Location</a></code>
- header is used in the WebSocket handshake. It is sent from the
- server to the client to confirm the <a href=#url>URL</a> of the
- connection. This enables the client to verify that the connection
- was established to the right server, port, and path, instead of
- relying on the server to verify that the requested host, port, and
- path are correct.</p>
-
-
- <h6 id=sec-websocket-origin><span class=secno>10.3.4.8.6 </span><dfn title=http-sec-websocket-origin><code>Sec-WebSocket-Origin</code></dfn></h6>
-
- <p>This section describes a header field for registration in the
- Permanent Message Header Field Registry. <a href=#refsRFC3864>[RFC3864]</a></p>
-
- <dl><dt>Header field name</dt>
- <dd>Sec-WebSocket-Origin</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl><p>The <code title=http-sec-websocket-origin><a href=#sec-websocket-origin>Sec-WebSocket-Origin</a></code> header
- is used in the WebSocket handshake. It is sent from the server to
- the client to confirm the <a href=#origin>origin</a> of the script that
- opened the connection. This enables user agents to verify that the
- server is willing to serve the script that opened the
- connection.</p>
-
-
- <h6 id=sec-websocket-protocol><span class=secno>10.3.4.8.7 </span><dfn title=http-sec-websocket-protocol><code>Sec-WebSocket-Protocol</code></dfn></h6>
-
- <p>This section describes a header field for registration in the
- Permanent Message Header Field Registry. <a href=#refsRFC3864>[RFC3864]</a></p>
-
- <dl><dt>Header field name</dt>
- <dd>Sec-WebSocket-Protocol</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl><p>The <code title=http-sec-websocket-protocol><a href=#sec-websocket-protocol>Sec-WebSocket-Protocol</a></code>
- header is used in the WebSocket handshake. It is sent from the
- client to the server and back from the server to the client to
- confirm the subprotocol of the connection. This enables scripts to
- both select a subprotocol and be sure that the server agreed to
- serve that subprotocol.</p>
-
-
-
-
- <h5 id=using-the-websocket-protocol-from-other-specifications><span class=secno>10.3.4.9 </span>Using the WebSocket protocol from other specifications</h5>
-
- <p>The WebSocket protocol is intended to be used by another
- specification to provide a generic mechanism for dynamic
- author-defined content, e.g. in a specification defining a scripted
- API.</p>
-
- <p>Such a specification first needs to "<a href=#establish-a-websocket-connection>establish a WebSocket
- connection</a>", providing that algorithm with:</p>
-
- <ul><li>The destination, consisting of a <var title="">host</var> and a
- <var title="">port</var>.</li>
-
- <li>A <var title="">resource name</var>, which allows for multiple
- services to be identified at one host and port.</li>
-
- <li>A <var title="">secure</var> flag, which is true if the
- connection is to be encrypted, and false otherwise.</li>
-
- <li>An <a href=#ascii-serialization-of-an-origin>ASCII serialization of an origin</a> that is being
- made responsible for the connection. <a href=#refsORIGIN>[ORIGIN]</a></li>
-
- <li>Optionally a string identifying a <span>protocol</span> that is
- to be layered over the WebSocket connection.</li>
-
- </ul><p>The <var title="">host</var>, <var title="">port</var>, <var title="">resource name</var>, and <var title="">secure</var> flag
- are usually obtained from a <a href=#url>URL</a> using the steps to
- <a href="#parse-a-websocket-url's-components">parse a WebSocket URL's components</a>. These steps fail
- if the URL does not specify a WebSocket.</p>
-
- <p>If a connection can be established, then it is said that the
- "<a href=#websocket-connection-is-established>WebSocket connection is established</a>".</p>
-
- <p>If at any time the connection is to be closed, then the
- specification needs to use the "<a href=#close-the-websocket-connection>close the WebSocket
- connection</a>" algorithm.</p>
-
- <p>When the connection is closed, for any reason including failure
- to establish the connection in the first place, it is said that the
- "<a href=#websocket-connection-is-closed>WebSocket connection is closed</a>".</p>
-
- <p>While a connection is open, the specification will need to handle
- the cases when "<a href=#a-websocket-message-has-been-received>a WebSocket message has been received</a>"
- with text <var title="">data</var>.</p>
-
- <p>To send some text <var title="">data</var> to an open connection,
- the specification needs to "<a href=#send-data-using-the-websocket>send <var title="">data</var>
- using the WebSocket</a>".</p>
-
-
- </div><!--data-component-->
-
<div data-component="Web Messaging (editor: Ian Hickson)">
@@ -76293,7 +73474,7 @@
</div>
- <h4 id=introduction-9><span class=secno>10.4.1 </span>Introduction</h4>
+ <h4 id=introduction-8><span class=secno>10.4.1 </span>Introduction</h4>
<p><i>This section is non-normative.</i></p>
@@ -76518,7 +73699,7 @@
<h3 id=channel-messaging><span class=secno>10.5 </span><dfn>Channel messaging</dfn></h3>
- <h4 id=introduction-10><span class=secno>10.5.1 </span>Introduction</h4>
+ <h4 id=introduction-9><span class=secno>10.5.1 </span>Introduction</h4>
<p><i>This section is non-normative.</i></p>
@@ -76968,7 +74149,7 @@
- <h3 id=introduction-11><span class=secno>11.1 </span>Introduction</h3>
+ <h3 id=introduction-10><span class=secno>11.1 </span>Introduction</h3>
<p><i>This section is non-normative.</i></p>
@@ -86829,7 +84010,7 @@
lead to this experience.</i></p>
- <h3 id=introduction-12><span class=secno>14.1 </span>Introduction</h3>
+ <h3 id=introduction-11><span class=secno>14.1 </span>Introduction</h3>
<p>In general, user agents are expected to support CSS, and many of
the suggestions in this section are expressed in CSS terms. User
@@ -86867,7 +84048,7 @@
<h3 id=the-css-user-agent-style-sheet-and-presentational-hints><span class=secno>14.2 </span>The CSS user agent style sheet and presentational hints</h3>
- <h4 id=introduction-13><span class=secno>14.2.1 </span>Introduction</h4>
+ <h4 id=introduction-12><span class=secno>14.2.1 </span>Introduction</h4>
<p>The CSS rules given in these subsections are, except where
otherwise specified, expected to be used as part of the user-agent
@@ -88998,7 +86179,7 @@
<h3 id=bindings><span class=secno>14.4 </span>Bindings</h3>
- <h4 id=introduction-14><span class=secno>14.4.1 </span>Introduction</h4>
+ <h4 id=introduction-13><span class=secno>14.4.1 </span>Introduction</h4>
<p>A number of elements have their rendering defined in terms of the
'binding' property. <a href=#refsBECSS>[BECSS]</a></p>
@@ -95291,11 +92472,6 @@
<dd>(Non-normative) <cite><a href=https://developer.mozilla.org/en/Gecko_Plugin_API_Reference>Gecko
Plugin API Reference</a></cite>. Mozilla.</dd>
- <dt id=refsNPN>[NPN]</dt>
- <dd><cite><a href=http://tools.ietf.org/html/draft-agl-tls-nextprotoneg>Transport
- Layer Security (TLS) Next Protocol Negotiation
- Extension</a></cite>, A. Langley. IETF.</dd>
-
<dt id=refsOPENSEARCH>[OPENSEARCH]</dt>
<dd><cite><a href=http://www.opensearch.org/Specifications/OpenSearch/1.1#Autodiscovery_in_HTML.2FXHTML>Autodiscovery
in HTML/XHTML</a></cite>. In <cite>OpenSearch 1.1 Draft 4</cite>,
@@ -95342,10 +92518,6 @@
Names - Concepts and Facilities</a></cite>, P. Mockapetris. IETF,
November 1987.</dd>
- <dt id=refsRFC1321>[RFC1321]</dt>
- <dd><cite><a href=http://www.ietf.org/rfc/rfc1321.txt>The MD5
- Message-Digest Algorithm</a></cite>, R. Rivest. IETF.</dd>
-
<dt id=refsRFC1345>[RFC1345]</dt>
<dd><cite><a href=http://www.ietf.org/rfc/rfc1345.txt>Character Mnemonics
and Character Sets</a></cite>, K. Simonsen. IETF.</dd>
@@ -95394,10 +92566,6 @@
<dd><cite><a href=http://www.ietf.org/rfc/rfc2237.txt>Japanese Character
Encoding for Internet Messages</a></cite>, K. Tamaru. IETF.</dd>
- <dt id=refsRFC2246>[RFC2246]</dt>
- <dd><cite><a href=http://www.ietf.org/rfc/rfc2246.txt>The TLS Protocol
- Version 1.0</a></cite>, T. Dierks, C. Allen. IETF.</dd>
-
<dt id=refsRFC2313>[RFC2313]</dt>
<dd><cite><a href=http://www.ietf.org/rfc/rfc2313.txt>PKCS #1:
RSA Encryption</a></cite>, B. Kaliski. IETF.</dd>
@@ -95482,11 +92650,6 @@
<dd>(Non-normative) <cite><a href=http://www.ietf.org/rfc/rfc4329.txt>Scripting Media
Types</a></cite>, B. Höhrmann. IETF.</dd>
- <dt id=refsRFC4366>[RFC4366]</dt>
- <dd><cite><a href=http://www.ietf.org/rfc/rfc4366.txt>Transport
- Layer Security (TLS) Extensions</a></cite>, S. Blake-Wilson,
- M. Nystrom, D. Hopwood, J. Mikkelsen, T. Wright. IETF.</dd>
-
<dt id=refsRFC4770>[RFC4770]</dt>
<dd><cite><a href=http://www.ietf.org/rfc/rfc4770.txt>vCard Extensions for
Instant Messaging (IM)</a></cite>, C. Jennings, J. Reschke. IETF.</dd>
@@ -95574,11 +92737,6 @@
Guidelines (WCAG) 2.0</a></cite>, B. Caldwell, M. Cooper, L. Reid,
G. Vanderheiden. W3C.</dd>
- <dt id=refsWEBADDRESSES>[WEBADDRESSES]</dt>
- <dd><cite><a href=http://www.w3.org/html/wg/href/draft>Web
- addresses in HTML5</a></cite>, D. Connolly,
- C. Sperberg-McQueen.</dd>
-
<dt id=refsWEBGL>[WEBGL]</dt>
<dd><cite><a href=https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/WebGL-spec.html>WebGL
Specification</a></cite>, C. Marrin. Khronos Group.</dd>
@@ -95617,6 +92775,10 @@
<dt id=refsWIN949>[WIN949]</dt>
<dd><cite><a href=http://www.microsoft.com/globaldev/reference/dbcs/949.mspx>Windows Codepage 949</a></cite>. Microsoft.</dd>
+ <dt id=refsWSP>[WSP]</dt>
+ <dd><cite><a href=http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol>The
+ WebSocket protocol</a></cite>, I. Fette. IETF.</dd>
+
<dt id=refsX121>[X121]</dt>
<dd><cite>Recommendation X.121 — International Numbering Plan for
Public Data Networks</cite>, CCITT Blue Book, Fascicle VIII.3,
Modified: index
===================================================================
--- index 2010-09-01 21:49:50 UTC (rev 5408)
+++ index 2010-09-02 10:00:31 UTC (rev 5409)
@@ -213,7 +213,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG src=/images/logo></a></p>
<hgroup><h1>HTML5 (including next generation additions still in development)</h1>
- <h2 class="no-num no-toc">Draft Standard — 1 September 2010</h2>
+ <h2 class="no-num no-toc">Draft Standard — 2 September 2010</h2>
</hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
@@ -70096,11 +70096,9 @@
</div>
- </div><!--data-component-->
-
<div data-component="Web Messaging (editor: Ian Hickson)">
@@ -89638,4 +89636,4 @@
hand corner." src="sample-datetime-ui-3"></li>
-->
-
+ </div>
Modified: source
===================================================================
--- source 2010-09-01 21:49:50 UTC (rev 5408)
+++ source 2010-09-02 10:00:31 UTC (rev 5409)
@@ -82243,7 +82243,7 @@
<div data-component="WebSocket API (editor: Ian Hickson)">
-<!--START websocket--><!--START websocket-api-->
+<!--START websocket-api-->
<h4 id="network-intro">Introduction</h4>
@@ -82307,15 +82307,12 @@
<ol>
- <!-- beware, this is very similar to the steps for what happens
- during a redirect, in the protocol section -->
-
<li><p><span>Parse a WebSocket URL's components</span> from the
<var title="">url</var> argument, to obtain <var
title="">host</var>, <var title="">port</var>, <var
title="">resource name</var>, and <var title="">secure</var>. If
this fails, throw a <code>SYNTAX_ERR</code> exception and abort
- these steps.</p></li>
+ these steps. <a href="#refsWSP">[WSP]</a></p></li>
<li>
@@ -82368,7 +82365,8 @@
title="">secure</var>, with <var title="">resource name</var> as
the resource name, with <var title="">protocols</var> as the
(possibly empty) list of protocols, and with the <var
- title="">defer cookies</var> flag set.</p>
+ title="">defer cookies</var> flag set. <a
+ href="#refsWSP">[WSP]</a></p>
<p class="note">If the "<span>establish a WebSocket
connection</span>" algorithm fails, it triggers the "<span>fail
@@ -82453,7 +82451,8 @@
WebSocket connection</span>. Any invokation of this method that does
not raise an exception must increase the <code
title="dom-WebSocket-bufferedAmount">bufferedAmount</code> attribute
- by the number of bytes needed to express the argument as UTF-8.</p>
+ by the number of bytes needed to express the argument as UTF-8. <a
+ href="#refsWSP">[WSP]</a></p>
<p>The <dfn title="dom-WebSocket-close"><code>close()</code></dfn>
method must run the first matching steps from the following list:</p>
@@ -82478,14 +82477,15 @@
<dt>If the WebSocket connection is not yet <span title="WebSocket
- connection is established">established</span></dt>
+ connection is established">established</span> <a
+ href="#refsWSP">[WSP]</a></dt>
<dd>
<p><span>Fail the WebSocket connection</span> and set the <code
title="dom-WebSocket-readyState">readyState</code> attribute's
- value to <code title="dom-WebSocket-CLOSING">CLOSING</code>
- (2).</p>
+ value to <code title="dom-WebSocket-CLOSING">CLOSING</code> (2).
+ <a href="#refsWSP">[WSP]</a></p>
<p class="note">The "<span>fail the WebSocket connection</span>"
algorithm invokes the "<span>close the WebSocket
@@ -82499,14 +82499,15 @@
<dt>If the WebSocket closing handshake has not yet been <span
title="the WebSocket closing handshake has
- started">started</span></dt>
+ started">started</span> <a href="#refsWSP">[WSP]</a></dt>
<dd>
<p><span>Start the WebSocket closing handshake</span> and set the
<code title="dom-WebSocket-readyState">readyState</code>
attribute's value to <code
- title="dom-WebSocket-CLOSING">CLOSING</code> (2).</p>
+ title="dom-WebSocket-CLOSING">CLOSING</code> (2). <a
+ href="#refsWSP">[WSP]</a></p>
<p class="note">The "<span>start the WebSocket closing
handshake</span>" algorithm eventually invokes the "<span>close
@@ -82612,8 +82613,8 @@
title="dom-WebSocket-protocol">protocol</code> attribute's value to
the <span>selected WebSocket subprotocol</span>, if there is one;
and then <span>fire a simple event</span> named <code
- title="event-open">open</code> at the <code>WebSocket</code>
- object.</p>
+ title="event-open">open</code> at the <code>WebSocket</code> object.
+ <a href="#refsWSP">[WSP]</a></p>
<p>When <i>a WebSocket message has been received</i> with text <var
title="">data</var>, the user agent must create an event that uses
@@ -82625,7 +82626,8 @@
if the <code title="dom-WebSocket-readyState">readyState</code>
attribute's value is <code title="dom-WebSocket-OPEN">OPEN</code>
(1) or <code title="dom-WebSocket-CLOSING">CLOSING</code> (2), and
- if so, dispatch the event at the <code>WebSocket</code> object.</p>
+ if so, dispatch the event at the <code>WebSocket</code> object. <a
+ href="#refsWSP">[WSP]</a></p>
<p>When <i>a WebSocket error has been detected</i>, the user agent
must <span>queue a task</span> to check to see if the <code
@@ -82634,7 +82636,7 @@
title="dom-WebSocket-CLOSING">CLOSING</code> (2), and if so,
<span>fire a simple event</span> named <code
title="event-error">error</code> at the <code>WebSocket</code>
- object.</p>
+ object. <a href="#refsWSP">[WSP]</a></p>
<p>When <i>the WebSocket closing handshake has started</i>, the user
agent must <span>queue a task</span> to change the <code
@@ -82644,7 +82646,7 @@
the <code title="dom-WebSocket-readyState">readyState</code>
attribute's value will already be set to <code
title="dom-WebSocket-CLOSING">CLOSING</code> (2) when this task
- runs.)</p>
+ runs.) <a href="#refsWSP">[WSP]</a></p>
<p id="closeWebSocket">When the <i>WebSocket connection is
closed</i>, possibly <i title="">cleanly</i>, the user agent must
@@ -82656,7 +82658,8 @@
false otherwise; and <span>queue a task</span> to first change the
<code title="dom-WebSocket-readyState">readyState</code> attribute's
value to <code title="dom-WebSocket-CLOSED">CLOSED</code> (3), and
- then dispatch the event at the <code>WebSocket</code> object.</p>
+ then dispatch the event at the <code>WebSocket</code> object. <a
+ href="#refsWSP">[WSP]</a></p>
<p>The <span>task source</span> for all <span
title="concept-task">tasks</span> <span title="queue a
@@ -82711,3169 +82714,22 @@
<p>A <code>WebSocket</code> object with <span title="WebSocket
connection is established">an established connection</span> that has
data queued to be transmitted to the network must not be garbage
- collected.</p>
+ collected. <a href="#refsWSP">[WSP]</a></p>
<p>If a <code>WebSocket</code> object is garbage collected while its
connection is still open, the user agent must <span>close the
- WebSocket connection</span>.</p>
+ WebSocket connection</span>. <a href="#refsWSP">[WSP]</a></p>
<!--END websocket-api-->
- <!--START websocket-protocol-->
+ </div><!--data-component-->
- <h4 id="websocket-protocol" title="The WebSocket protocol enables
- two-way communication between a user agent running untrusted code
- running in a controlled environment to a remote host that has
- opted-in to communications from that code. The security model used
- for this is the Origin-based security model commonly used by Web
- browsers. The protocol consists of an initial handshake followed by
- basic message framing, layered over TCP. The goal of this technology
- is to provide a mechanism for browser-based applications that need
- two-way communication with servers that does not rely on opening
- multiple HTTP connections (e.g. using XMLHttpRequest or
- <iframe>s and long polling).">The WebSocket protocol</h4>
-
-
- <h5>Introduction</h5>
-
- <h6>Background</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>Historically, creating an instant messenger chat client as a Web
- application has required an abuse of HTTP to poll the server for
- updates while sending upstream notifications as distinct HTTP
- calls.</p>
-
- <p>This results in a variety of problems:</p>
-
- <ul>
-
- <li>The server is forced to use a number of different underlying
- TCP connections for each client: one for sending information to the
- client, and a new one for each incoming message.</li>
-
- <li>The wire protocol has a high overhead, with each
- client-to-server message having an HTTP header.</li>
-
- <li>The client-side script is forced to maintain a mapping from the
- outgoing connections to the incoming connection to track
- replies.</li>
-
- </ul>
-
- <p>A simpler solution would be to use a single TCP connection for
- traffic in both directions. This is what the WebSocket protocol
- provides. Combined with the WebSocket API, it provides an
- alternative to HTTP polling for two-way communication from a Web
- page to a remote server.
- <!--END complete--><!--END epub-->
- <a href="#refsWSAPI">[WSAPI]</a>
- <!--START complete--><!--START epub-->
- </p>
-
- <p>The same technique can be used for a variety of Web applications,
- for instance games, stock tickers, multiuser applications with
- simultaneous editing, and user interfaces exposing server-side
- services in real time.</p>
-
-
-
- <h6>Protocol overview</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The protocol has two parts: a handshake, and then the data
- transfer.</p>
-
- <p>The handshake from the client looks as follows:</p>
-
- <pre>GET /demo HTTP/1.1
-Host: example.com
-Connection: Upgrade
-Sec-WebSocket-Key2: 12998 5 Y3 1 .P00
-Sec-WebSocket-Protocol: sample
-Upgrade: WebSocket
-Sec-WebSocket-Key1: 4 @1 46546xW%0l 1 5
-Origin: http://example.com
-
-^n:ds[4U</pre>
-
- <p>The handshake from the server looks as follows:</p>
-
- <pre>HTTP/1.1 101 WebSocket Protocol Handshake
-Upgrade: WebSocket
-Connection: Upgrade
-Sec-WebSocket-Origin: http://example.com
-Sec-WebSocket-Location: ws://example.com/demo
-Sec-WebSocket-Protocol: sample
-
-8jKS'y:G*Co,Wxa-</pre>
-
- <p>The leading line from the client follows the Request-Line
- format. The leading line from the server follows the Status-Line
- format. The Request-Line and Status-Line productions are defined in
- the HTTP specification.</p>
-
- <p>After the leading line in both cases come an unordered
- <span>ASCII case-insensitive</span> set of fields, one per line,
- that each match the following non-normative ABNF:
-<!--END complete--><!--END epub-->
- <a href="#refsRFC5234">[RFC5234]</a>
-<!--START complete--><!--START epub--><!--END websocket-protocol-->
- <a href="#refsABNF">[ABNF]</a>
-<!--START websocket-protocol-->
- </p>
-
- <pre>field = 1*name-char colon [ space ] *any-char cr lf
-colon = %x003A ; U+003A COLON (:)
-space = %x0020 ; U+0020 SPACE
-cr = %x000D ; U+000D CARRIAGE RETURN (CR)
-lf = %x000A ; U+000A LINE FEED (LF)
-name-char = %x0000-0009 / %x000B-000C / %x000E-0039 / %x003B-10FFFF
- ; a Unicode character other than U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), or U+003A COLON (:)
-any-char = %x0000-0009 / %x000B-000C / %x000E-10FFFF
- ; a Unicode character other than U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)</pre>
-
- <p class="note">The character set for the above ABNF is Unicode. The
- fields themselves are encoded as UTF-8.</p>
-
- <p>Lines that don't match the above production cause the connection
- to be aborted.</p>
-
- <p>Finally, after the last field, the client sends 10 bytes
- starting with 0x0D 0x0A and followed by 8 random bytes, part of a
- challenge, and the server sends 18 bytes starting with 0x0D 0x0A and
- followed by 16 bytes consisting of a challenge response. The details
- of this challenge and other parts of the handshake are described in
- the next section.</p>
-
- <hr>
-
- <p>Once the client and server have both sent their handshakes, and
- if the handshake was successful, then the data transfer part
- starts. This is a two-way communication channel where each side can,
- independently from the other, send data at will.</p>
-
- <p>Data is sent in the form of UTF-8 text. Each frame of data starts
- with a 0xFF byte identifying the frame type, followed by the number
- of bytes in the data expressed as a big-endian 64 bit unsigned
- integer, followed by the UTF-8 data.</p>
-
- <p class="note">The length is the number of UTF-8 <em>bytes</em>,
- and not the number of characters. For example, the string
- "H̶e̸͜҉ll̡o̵̶͘"
- has 13 Unicode code points, but is 21 bytes long.</p><!-- Zalgo -->
-
- <p>The WebSocket protocol uses this framing so that specifications
- that use the WebSocket protocol can expose such connections using
- an event-based mechanism instead of requiring users of those
- specifications to implement buffering and piecing together of
- messages manually.</p>
-
- <p>To close the connection cleanly, a frame consisting of just nine
- 0x00 bytes in a row is sent from one peer to ask that the other peer
- close the connection. That corresponds to a frame type of 0x00
- followed by a length of zero, indicating an empty frame.</p>
-
- <p>In addition to the 0x00 and 0xFF frame types, other types might
- in future be defined, to support binary data, fragmentation,
- compression, multiplexing, or other features.</p>
-
- <p>The wire format for the data transfer part is described by the
- <code title="">frames</code> production of the following
- non-normative ABNF.
-<!--END complete--><!--END epub-->
- <a href="#refsRFC5234">[RFC5234]</a>
-<!--START complete--><!--START epub--><!--END websocket-protocol-->
- <a href="#refsABNF">[ABNF]</a>
-<!--START websocket-protocol-->
- </p>
-
- <pre>frames = *frame
-frame = frame-type frame-length data
-frame-type = OCTET
-frame-length = 8OCTET
-data = *OCTET ; count must match the given length</pre>
-
- <p class="note">The above ABNF is intended for a binary octet
- environment.</p>
-
- <p class="warning">At this time, the WebSocket protocol cannot be
- used to send binary data. Using any of the frame types other than
- 0x00 and 0xFF is invalid. All other frame types are reserved for
- future use by future versions of this protocol.</p>
-
-
-
- <h6>Opening handshake</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The opening handshake is intended to be compatible with
- HTTP-based server-side software, so that a single port can be used
- by both HTTP clients talking to that server and WebSocket clients
- talking to that server. To this end, the WebSocket client's
- handshake appears to HTTP servers to be a regular GET request with
- an Upgrade offer:</p>
-
- <pre>GET / HTTP/1.1
-Upgrade: WebSocket
-Connection: Upgrade</pre>
-
- <p>Fields in the handshake are sent by the client in a random order;
- the order is not meaningful.</p>
-
- <p>Additional fields are used to select options in the WebSocket
- protocol. The only options available in this version are the
- subprotocol selector, <code
- title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>,
- and <code title="http-cookie">Cookie</code>, which can used for
- sending cookies to the server (e.g. as an authentication
- mechanism). The <code
- title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>
- field takes a space-separated list of strings:</p>
-
- <pre>Sec-WebSocket-Protocol: org.example.chat wsxmpp ACME.COM-IM-2</pre>
-
- <p>This field indicates the subprotocols (the application-level
- protocol layered over the WebSocket protocol) that the client can
- use. The server reports which subprotocol it is going to use in its
- handshake response.</p>
-
- <p>The other fields in the handshake are all security-related. The
- <code title="http-host">Host</code> field is used to protect against
- DNS rebinding attacks and to allow multiple domains to be served
- from one IP address.</p>
-
- <pre>Host: example.com</pre>
-
- <p>The server includes the hostname in the <code
- title="http-sec-websocket-location">Sec-WebSocket-Location</code>
- field of its handshake, so that both the client and the server can
- verify that they agree on which host is in use.</p>
-
- <p>The <code title="http-origin">Origin</code> field is used to
- protect against unauthorized cross-origin use of a WebSocket server
- by scripts using the <code>WebSocket</code> API in a Web
- browser. The server specifies which origin it is willing to receive
- requests from by including a <code
- title="http-sec-websocket-origin">Sec-WebSocket-Origin</code> field
- with that origin. If multiple origins are authorized, the server
- echoes the value in the <code title="http-origin">Origin</code>
- field of the client's handshake.</p>
-
- <pre>Origin: http://example.com</pre>
-
- <p>Finally, the server has to prove to the client that it received
- the client's WebSocket handshake, so that the server doesn't accept
- connections that are not WebSocket connections. This prevents an
- attacker from tricking a WebSocket server by sending it
- carefully-crafted packets using <code>XMLHttpRequest</code> or a
- <code>form</code> submission.</p>
-
- <p>To prove that the handshake was received, the server has to take
- three pieces of information and combine them to form a response. The
- first two pieces of information come from the <code
- title="http-sec-websocket-key">Sec-WebSocket-Key1</code> and <code
- title="http-sec-websocket-key">Sec-WebSocket-Key2</code> fields in
- the client handshake:</p>
-
- <pre>Sec-WebSocket-Key1: 18x 6]8vM;54 *(5: { U1]8 z [ 8
-Sec-WebSocket-Key2: 1_ tx7X d < nw 334J702) 7]o}` 0</pre>
-
- <p>For each of these fields, the server has to take the digits from
- the value to obtain a number (in this case 1868545188 and 1733470270
- respectively), then divide that number by the number of spaces
- characters in the value (in this case 12 and 10) to obtain a 32-bit
- number (155712099 and 173347027). These two resulting numbers are
- then used in the server handshake, as described below.</p>
-
- <p>The counting of spaces is intended to make it impossible to
- smuggle this field into the resource name; making this even harder
- is the presence of <em>two</em> such fields, and the use of a
- newline as the only reliable indicator that the end of the key has
- been reached. The use of random characters interspersed with the
- spaces and the numbers ensures that the implementor actually looks
- for spaces and newlines, instead of being treating any character
- like a space, which would make it again easy to smuggle the fields
- into the path and trick the server. Finally, <em>dividing</em> by
- this number of spaces is intended to make sure that even the most
- naïve of implementations will check for spaces, since if ther
- server does not verify that there are some spaces, the server will
- try to divide by zero, which is usually fatal (a correct handshake
- will always have at least one space).
-
- <p>The third piece of information is given after the fields, in the
- last eight bytes of the handshake, expressed here as they would be
- seen if interpreted as UTF-8:</p>
-
- <pre>Tm[K T2u</pre>
-
- <p>The concatenation of the number obtained from processing the
- <code title="http-sec-websocket-key">Sec-WebSocket-Key1</code>
- field, expressed as a big-endian 32-bit number, the number
- obtained from processing the <code
- title="http-sec-websocket-key">Sec-WebSocket-Key2</code> field,
- again expressed as a big-endian 32-bit number, and finally the
- eight bytes at the end of the handshake, form a 128 bit string whose
- MD5 sum is then used by the server to prove that it read the
- handshake.</p>
-
- <hr>
-
- <p>The handshake from the server is much simpler than the client
- handshake. The first line is an HTTP Status-Line, with the status
- code 101 (the HTTP version and reason phrase aren't important):</p>
-
- <pre>HTTP/1.1 101 WebSocket Protocol Handshake</pre>
-
- <p>The fields follow. Two of the fields are just for compatibility
- with HTTP:</p>
-
- <pre>Upgrade: WebSocket
-Connection: Upgrade</pre>
-
- <p>Two of the fields are part of the security model described
- above, echoing the origin and stating the exact host, port, resource
- name, and whether the connection is expected to be encrypted:</p>
-
- <pre>Sec-WebSocket-Origin: http://example.com
-Sec-WebSocket-Location: ws://example.com/</pre>
-
- <p>These fields are checked by the Web browser when it is acting as
- a <code>WebSocket</code> client for scripted pages. A server that
- only handles one origin and only serves one resource can therefore
- just return hard-coded values and does not need to parse the
- client's handshake to verify the correctness of the values.</p>
-
- <p>Option fields can also be included. In this version of the
- protocol, the main option field is <code
- title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>,
- which indicates the subprotocol that the server speaks. Web browsers
- verify that the server specified one of the values that was
- specified in the <code>WebSocket</code> constructor, so a server
- that speaks multiple subprotocols has to make sure it selects one
- based on the client's handshake and specifies the right one in its
- handshake.</p>
-
- <pre>Sec-WebSocket-Protocol: org.example.chat</pre>
-
- <p>The server can also set cookie-related option fields to
- <em>set</em> cookies, as in HTTP.</p>
-
- <p>After the fields, the server sends the aforementioned MD5 sum, a
- 16 byte (128 bit) value, shown here as if interpreted as UTF-8:</p>
-
- <pre>fQJ,fN/4F4!~K~MH</pre>
-
- <p>This value depends on what the client sends, as described
- above. If it doesn't match what the client is expecting, the client
- would disconnect.</p>
-
- <p>Having part of the handshake appear after the fields ensures
- that both the server and the client verify that the connection is
- not being interrupted by an HTTP intermediary such as a
- man-in-the-middle cache or proxy.</p>
-
-
- <h6>Closing handshake</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The closing handshake is far simpler than the opening handshake.</p>
-
- <p>Either peer can send a 0xFF frame with length 0x00 to begin the
- closing handshake. Upon receiving a 0xFF frame, the other peer
- sends an identical 0xFF frame in acknowledgement, if it hasn't
- already sent one. Upon receiving <em>that</em> 0xFF frame, the first
- peer then closes the connection, safe in the knowledge that no
- further data is forthcoming.</p>
-
- <p>After sending a 0xFF frame, a peer does not send any further
- data; after receiving a 0xFF frame, a peer discards any further
- data received.</p>
-
- <p>It is safe for both peers to initiate this handshake
- simultaneously.</p>
-
- <p>The closing handshake is intended to replace the TCP closing
- handshake (FIN/ACK), on the basis that the TCP closing handshake is
- not always reliable end-to-end, especially in the presence of
- man-in-the-middle proxies and other intermediaries.</p>
-
-
-
- <h6>Design philosophy</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The WebSocket protocol is designed on the principle that there
- should be minimal framing (the only framing that exists is to make
- the protocol frame-based instead of stream-based, and to support a
- distinction between Unicode text and binary frames). It is expected
- that metadata would be layered on top of WebSocket by the
- application layer, in the same way that metadata is layered on top
- of TCP by the application layer (HTTP).</p>
-
- <p>Conceptually, WebSocket is really just a layer on top of TCP
- that adds a Web "origin"-based security model for browsers; adds an
- addressing and subprotocol naming mechanism to support multiple
- services on one port and multiple host names on one IP address;
- layers a framing mechanism on top of TCP to get back to the IP
- packet mechanism that TCP is built on, but without length
- limits; and reimplements the closing handshake in-band.
-
- Other than that, it adds nothing. Basically it is intended
- to be as close to just exposing raw TCP to script as possible
- given the constraints of the Web. It's also designed in such a way
- that its servers can share a port with HTTP servers, by having its
- handshake be a valid HTTP Upgrade handshake also.</p>
-
- <p>The protocol is intended to be extensible; future versions will
- likely introduce a mechanism to compress data and might support
- sending binary data. To do this, future versions of this protocol
- are likely to introduce option fields that clients can send in its
- handshake to announce support for a feature (such as compression),
- to which the server can react by including a similar option field in
- <em>its</em> handshake.</p>
-
-
- <h6>Security model</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The WebSocket protocol uses the origin model used by Web
- browsers to restrict which Web pages can contact a WebSocket server
- when the WebSocket protocol is used from a Web page. Naturally,
- when the WebSocket protocol is used by a dedicated client directly
- (i.e. not from a Web page through a Web browser), the origin model
- is not useful, as the client can provide any arbitrary origin
- string.</p>
-
- <p>This protocol is intended to fail to establish a connection with
- servers of pre-existing protocols like SMTP or HTTP, while allowing
- HTTP servers to opt-in to supporting this protocol if desired. This
- is achieved by having a strict and elaborate handshake, and by
- limiting the data that can be inserted into the connection before
- the handshake is finished (thus limiting how much the server can be
- influenced).</p>
-
- <p>It is similarly intended to fail to establish a connection when
- data from other protocols, especially HTTP, is sent to a WebSocket
- server, for example as might happen if an HTML <code>form</code>
- were submitted to a WebSocket server. This is primarily achieved by
- requiring that the server prove that it read the handshake, which it
- can only do if the handshake contains the appropriate parts which
- themselves can only be sent by a WebSocket handshake; in
- particular, fields starting with <code title="">Sec-</code> cannot
- be set by an attacker from a Web browser, even when using
- <code>XMLHttpRequest</code>.</p>
-
-
- <h6>Relationship to TCP and HTTP</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The WebSocket protocol is an independent TCP-based protocol. Its
- only relationship to HTTP is that its handshake is interpreted by
- HTTP servers as an Upgrade request.</p>
-
- <p>Based on the expert recommendation of the IANA<!-- [IANA #257455]
- -->, the WebSocket protocol by default uses port 80 for regular
- WebSocket connections and port 443 for WebSocket connections
- tunneled over TLS.</p>
-
-
-
- <h6>Establishing a connection</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>There are several options for establishing a WebSocket connection.</p>
-
- <p>On the face of it, the simplest method would seem to be to use
- port 80 to get a direct connection to a WebSocket server. Port 80
- traffic, however, will often be intercepted by man-in-the-middle
- HTTP proxies, which can lead to the connection failing to be
- established.</p>
-
- <p>The most reliable method, therefore, is to use TLS encryption and
- port 443 to connect directly to a WebSocket server. This has the
- advantage of being more secure; however, TLS encryption can be
- computationally expensive.</p>
-
- <p>When a connection is to be made to a port that is shared by an
- HTTP server (a situation that is quite likely to occur with traffic
- to ports 80 and 443), the connection will appear to the HTTP server
- to be a regular GET request with an Upgrade offer. In relatively
- simple setups with just one IP address and a single server for all
- traffic to a single hostname, this might allow a practical way for
- systems based on the WebSocket protocol to be deployed. In more
- elaborate setups (e.g. with load balancers and multiple servers), a
- dedicated set of hosts for WebSocket connections separate from the
- HTTP servers is probably easier to manage.</p>
-
-
-
- <h6>Subprotocols using the WebSocket protocol</h6>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>The client can request that the server use a specific subprotocol
- by including the <code
- title="http-sec-websocket-protocol">Sec-Websocket-Protocol</code>
- field in its handshake. If it is specified, the server needs to
- include an equivalent field in its response for the connection to be
- established.</p>
-
- <p>These subprotocol names do not need to be registered, but if a
- subprotocol is intended to be implemented by multiple independent
- WebSocket servers, potential clashes with the names of subprotocols
- defined independently can be avoided by using names that contain the
- domain name of the subprotocol's originator. For example, if Example
- Corporation were to create a Chat subprotocol to be implemented by
- many servers around the Web, they could name it
- "chat.example.com". If the Example Organisation called their
- competing subprotocol "the-example.org-chat-protocol", then the two
- subprotocols could be implemented by servers simultaneously, with
- the server dynamically selecting which subprotocol to use based on
- the value sent by the client.</p>
-
- <p>Subprotocols can be versioned in backwards-incompatible ways by
- changing the subprotocol name, eg. going from "bookings.example.net"
- to "bookings.example.net2". These subprotocols would be considered
- completely separate by WebSocket clients. Backwards-compatible
- versioning can be implemented by reusing the same subprotocol string
- but carefully designing the actual subprotocol to support this kind
- of extensibility.</p>
-
- <p>Subprotocol names are sequences of one or more characters in the
- range U+0021 to U+007F.</p>
-
-
-<!--END complete--><!--END epub-->
- <!--BOILERPLATE middle-ietf-conformance-->
-<!--START complete--><!--START epub-->
-
- <h5>Terminology</h5>
-
-<!--END complete--><!--END epub-->
- <p><dfn title="converted to ASCII lowercase">Converting a string to
- ASCII lowercase</dfn> means replacing all characters in the range
- U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL
- LETTER Z) with the corresponding characters in the range U+0061
- to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z).</p>
-
- <p>Comparing two strings in an <dfn>ASCII case-insensitive</dfn>
- manner means comparing them exactly, code point for code point, except
- that the characters in the range U+0041 to U+005A (i.e. LATIN
- CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding
- characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A
- to LATIN SMALL LETTER Z) are considered to also match.</p>
-
- <p>The term "URL" is used in this section in a manner consistent
- with the terminology used in HTML, namely, to denote a string that
- might or might not be a valid URI or IRI and to which certain error
- handling behaviors will be applied when the string is parsed. <a
- href="#refsHTML">[HTML]</a></p>
-<!--START complete--><!--START epub-->
-
- <p>When an implementation is required to <i>send</i> data as part of
- the WebSocket protocol, the implementation may delay the actual
- transmission arbitrarily, e.g. buffering data so as to send fewer IP
- packets.</p>
-
-
-
- <h5>WebSocket URLs</h5>
-
- <h6>Parsing WebSocket URLs</h6>
-
- <p>The steps to <dfn>parse a WebSocket URL's components</dfn> from
- a string <var title="">url</var> are as follows. These steps return
- either a <var title="">host</var>, a <var title="">port</var>, a
- <var title="">resource name</var>, and a <var title="">secure</var>
- flag, or they fail.</p>
-
- <ol>
-
- <li><p>If the <var title="">url</var> string is not an
- <span>absolute URL</span>, then fail this algorithm. <a
- href="#refsWEBADDRESSES">[WEBADDRESSES]</a></p></li>
-
- <li>
-
- <p><span title="resolve a url">Resolve</span> the <var
- title="">url</var> string using the <span>resolve a Web
- address</span> algorithm defined by the Web addresses
- specification, with the <span>URL character encoding</span> set to
- UTF-8. <a href="#refsWEBADDRESSES">[WEBADDRESSES]</a> <a
- href="#refsRFC3629">[RFC3629]</a></p> <!-- the URL character
- encoding is used to escape the query component -->
-
- <p class="note">It doesn't matter what it is resolved relative to,
- since we already know it is an <span>absolute URL</span> at this
- point.</p>
-
- </li>
-
- <li><p>If <var title="">url</var> does not have a <span
- title="url-scheme"><scheme></span> component whose value,
- when <span>converted to ASCII lowercase</span>, is either "<code
- title="">ws</code>" or "<code title="">wss</code>", then fail this
- algorithm.</p></li>
-
- <li><p>If <var title="">url</var> has a <span
- title="url-fragment"><fragment></span> component, then fail
- this algorithm.</p></li>
-
- <li><p>If the <span title="url-scheme"><scheme></span>
- component of <var title="">url</var> is "<code title="">ws</code>",
- set <var title="">secure</var> to false; otherwise, the <span
- title="url-scheme"><scheme></span> component is "<code
- title="">wss</code>", set <var title="">secure</var> to
- true.</p></li>
-
- <li><p>Let <var title="">host</var> be the value of the <span
- title="url-host"><host></span> component of <var
- title="">url</var>, <span>converted to ASCII
- lowercase</span>.</p></li> <!-- at this point this is
- Punycode-encoded already -->
-
- <li><p>If <var title="">url</var> has a <span
- title="url-port"><port></span> component, then let <var
- title="">port</var> be that component's value; otherwise, there is
- no explicit <var title="">port</var>.</p></li>
-
- <li><p>If there is no explicit <var title="">port</var>, then: if
- <var title="">secure</var> is false, let <var title="">port</var>
- be 80, otherwise let <var title="">port</var> be 443.</p></li>
-
- <li><p>Let <var title="">resource name</var> be the value of the
- <span title="url-path"><path></span> component (which might
- be empty) of <var title="">url</var>.</p></li> <!-- at this point
- this is UTF-8 encoded and %-escaped -->
-
- <li><p>If <var title="">resource name</var> is the empty string,
- set it to a single character U+002F SOLIDUS (/).</p></li>
-
- <li><p>If <var title="">url</var> has a <span
- title="url-query"><query></span> component, then append a
- single U+003F QUESTION MARK character (?) to <var title="">resource
- name</var>, followed by the value of the <span
- title="url-query"><query></span> component.</p></li> <!-- at
- this point this is UTF-8 encoded and %-escaped -->
-
- <li><p>Return <var title="">host</var>, <var title="">port</var>,
- <var title="">resource name</var>, and <var
- title="">secure</var>.</p></li>
-
- </ol>
-
-
- <h6>Constructing WebSocket URLs</h6>
-
- <p>The steps to <dfn>construct a WebSocket URL</dfn> from a <var
- title="">host</var>, a <var title="">port</var>, a <var
- title="">resource name</var>, and a <var title="">secure</var> flag,
- are as follows:</p>
-
- <ol>
-
- <li>Let <var title="">url</var> be the empty string.</li>
-
- <li>If the <var title="">secure</var> flag is false, then append
- the string "<code title="">ws://</code>" to <var
- title="">url</var>. Otherwise, append the string "<code
- title="">wss://</code>" to <var title="">url</var>.</li>
-
- <li>Append <var title="">host</var> to <var
- title="">url</var>.</li>
-
- <li>If the <var title="">secure</var> flag is false and port is
- not 80, or if the <var title="">secure</var> flag is true and
- port is not 443, then append the string "<code title="">:</code>"
- followed by <var title="">port</var> to <var
- title="">url</var>.</li>
-
- <li>Append <var title="">resource name</var> to <var
- title="">url</var>.</li>
-
- <li>Return <var title="">url</var>.</li>
-
- </ol>
-
-
- <h5>Client-side requirements</h5>
-
- <p><i>This section only applies to user agents, not to
- servers.</i></p>
-
- <p>User agents running in controlled environments, e.g. browsers on
- mobile handsets tied to specific carriers, may offload the
- management of the connection to another agent on the network. In
- such a situation, the user agent for the purposes of conformance is
- considered to include both the handset software and any such
- agents.</p>
-
- <p class="note">This specification doesn't currently define a limit
- to the number of simultaneous connections that a client can
- establish to a server.</p>
-
-
- <h6>Opening handshake</h6>
-
- <p>When the user agent is to <dfn>establish a WebSocket
- connection</dfn> to a host <var title="">host</var>, on a port <var
- title="">port</var>, from an origin whose <span title="ASCII
- serialization of an origin">ASCII serialization</span> is <var
- title="">origin</var>, with a flag <var title="">secure</var>, with
- a string giving a <var title="">resource name</var>, with a
- (possibly empty) list of strings giving the <var
- title="">protocols</var>, and optionally with a <var title="">defer
- cookies</var> flag, it must run the following steps. The <var
- title="">host</var> must have been punycode-encoded already if
- necessary (i.e. it does not contain characters above U+007E). The
- <var title="">origin</var> must not contain characters in the range
- U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL
- LETTER Z). The <var title="">resource name</var> string must be a
- non-empty string of characters in the range U+0021 to U+007E that
- starts with a U+002F SOLIDUS character (/). The various strings in
- <var title="">protocols</var> must all be non-empty strings with
- characters in the range U+0021 to U+007E, and must all be unique. <a
- href="#refsORIGIN">[ORIGIN]</a></p>
-
- <ol>
-
- <li>
-
- <p>If the user agent already has a WebSocket connection to the
- remote host (IP address) identified by <var title="">host</var>,
- even if known by another name, wait until that connection has been
- <span title="WebSocket connection is
- established">established</span> or for that connection to have
- <span title="fail the WebSocket connection">failed</span>. If
- multiple connections to the same IP address are attempted
- simultaneously, the user agent must serialize them so that there
- is no more than one connection at a time running through the
- following steps.</p>
-
- <p>If the user agent cannot determine the IP address of the remote
- host (for example because all communication is being done through
- a proxy server that performs DNS queries itself), then the user
- agent must assume for the purposes of this step that each host
- name refers to a distinct remote host, but should instead limit
- the total number of simultaneous connections that are not <span
- title="WebSocket connection is established">established</span> to
- a reasonably low number (e.g., in a Web browser, to the number of
- tabs the user has open).</p>
-
- <p class="note">This makes it harder for a script to perform a
- denial of service attack by just opening a large number of
- WebSocket connections to a remote host. A server can further
- reduce the load on itself when attacked by making use of this by
- pausing before closing the connection, as that will reduce the
- rate at which the client reconnects.</p>
-
- <p class="note">There is no limit to the number of <span
- title="WebSocket connection is established">established</span>
- WebSocket connections a user agent can have with a single remote
- host. Servers can refuse to connect users with an excessive number
- of connections, or disconnect resource-hogging users when
- suffering high load.</p>
-
- </li>
-
- <li>
-
- <p><i>Connect</i>: If the user agent is configured to use a proxy
- when using the WebSocket protocol to connect to host <var
- title="">host</var> and/or port <var title="">port</var>, then
- connect to that proxy and ask it to open a TCP connection to
- the host given by <var title="">host</var> and the port given by
- <var title="">port</var>.</p>
-
- <div class="example">
-
- <p>For example, if the user agent uses an HTTP proxy for all
- traffic, then if it was to try to connect to port 80 on server
- example.com, it might send the following lines to the proxy
- server:</p>
-
- <pre>CONNECT example.com:80 HTTP/1.1
-Host: example.com</pre>
-
- <p>If there was a password, the connection might look like:</p>
-
- <pre>CONNECT example.com:80 HTTP/1.1
-Host: example.com
-Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE=</pre>
-
- </div>
-
- <p>Otherwise, if the user agent is not configured to use a proxy,
- then open a TCP connection to the host given by <var
- title="">host</var> and the port given by <var
- title="">port</var>.</p>
-
- <p class="note">Implementations that do not expose explicit UI for
- selecting a proxy for WebSocket connections separate from other
- proxies are encouraged to use a SOCKS proxy for WebSocket
- connections, if available, or failing that, to prefer the proxy
- configured for HTTPS connections over the proxy configured for
- HTTP connections.</p>
-
- <p>For the purpose of proxy autoconfiguration scripts, the
- <span>URL</span> to pass the function must be constructed from
- <var title="">host</var>, <var title="">port</var>, <var
- title="">resource name</var>, and the <var title="">secure</var>
- flag using the steps to <span>construct a WebSocket
- URL</span>.</p>
-
- <p class="note">The WebSocket protocol can be identified in proxy
- autoconfiguration scripts from the scheme ("<code
- title="">ws:</code>" for unencrypted connections and "<code
- title="">wss:</code>" for encrypted connections).</p>
-
- </li>
-
- <li><p>If the connection could not be opened, then <span>fail the
- WebSocket connection</span> and abort these steps.</p></li>
-
- <li>
-
- <p>If <var title="">secure</var> is true, perform a TLS handshake
- over the connection. If this fails (e.g. the server's certificate
- could not be verified), then <span>fail the WebSocket
- connection</span> and abort these steps. Otherwise, all further
- communication on this channel must run through the encrypted
- tunnel. <a href="#refsRFC2246">[RFC2246]</a></p>
-
- <p>User agents must use the Server Name Indication extension in
- the TLS handshake. <a href="#refsRFC4366">[RFC4366]</a></p>
-
- <p>User agents must use the Next Protocol Negotiation extension in
- the TLS handshake, selecting the "776562736f636b6574" protocol
- ("websocket" in UTF-8). <a href="#refsNPN">[NPN]</a>
-
- </li>
-
- <li>
-
- <p>Send the UTF-8 string "GET" followed by a UTF-8-encoded U+0020
- SPACE character to the remote side (the server).</p>
-
- <p>Send the <var title="">resource name</var> value, encoded as
- UTF-8.</p>
-
- <p>Send another UTF-8-encoded U+0020 SPACE character, followed by
- the UTF-8 string "HTTP/1.1", followed by a UTF-8-encoded U+000D
- CARRIAGE RETURN U+000A LINE FEED character pair (CRLF).</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">fields</var> be an empty list of strings.</p>
-
- </li>
-
- <li>
-
- <p>Add the string "Upgrade: WebSocket" to <var
- title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>Add the string "Connection: Upgrade" to <var
- title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">hostport</var> be an empty string.</p>
-
- </li>
-
- <li>
-
- <p>Append the <var title="">host</var> value, <span>converted to
- ASCII lowercase</span>, to <var title="">hostport</var>.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">secure</var> is false, and <var
- title="">port</var> is not 80, or if <var title="">secure</var> is
- true, and <var title="">port</var> is not 443, then append a
- U+003A COLON character (:) followed by the value of <var
- title="">port</var>, expressed as a base-ten integer, to <var
- title="">hostport</var>.</p>
-
- </li>
-
- <li>
-
- <p>Add the string consisting of the concatenation of the string
- "Host:", a U+0020 SPACE character, and <var
- title="">hostport</var>, to <var title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>Add the string consisting of the concatenation of the string
- "Origin:", a U+0020 SPACE character, and the <var
- title="">origin</var> value, to <var title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>If the <var title="">protocols</var> list is empty, then skip
- this step.</p>
-
- <p>Otherwise, add the string consisting of the concatenation of
- the string "Sec-WebSocket-Protocol:", a U+0020 SPACE character,
- and the strings in <var title="">protocols</var>, maintaining
- their relative order and each separated from the next by a single
- U+0020 SPACE character, to <var title="">fields</var>.</p>
-
- </li>
-
-<!--UAS:
- <li>
-
- <p>Optionally, add the string consisting of the concatenation of
- the string "User-Agent:", a U+0020 SPACE character, and a
- user-agent defined string, to <var title="">fields</var>.</p>
-
- </li>
--->
-
- <li>
-
- <p>If the client has any <!--(v2-ws-auth) authentication
- information or--> cookies that would be relevant to a resource
- accessed over HTTP, if <var title="">secure</var> is false, or
- HTTPS, if it is true, on host <var title="">host</var>, port <var
- title="">port</var>, with <var title="">resource name</var> as the
- path (and possibly query parameters), then add to <var
- title="">fields</var> any HTTP headers that would be appropriate
- for that information.
-<!--END complete--><!--END epub-->
- <a href="#refsRFC2616">[RFC2616]</a>
- <a href="#refsRFC2109">[RFC2109]</a>
- <a href="#refsRFC2965">[RFC2965]</a>
-<!--START complete--><!--START epub--><!--END websocket-protocol-->
- <a href="#refsHTTP">[HTTP]</a>
- <a href="#refsCOOKIES">[COOKIES]</a>
-<!--START websocket-protocol-->
- </p>
-
- <p>This includes "<code>HttpOnly</code>" cookies (cookies with the
- http-only-flag set to true); the WebSocket protocol is not
- considered a non-HTTP API for the purpose of cookie
- processing.</p>
-
- <p>When one or more HTTP headers are to be added to <var
- title="">fields</var> for this step, each header must be added
- separately, and each header must be added as one entry consisting
- of the header's name in its canonical case, followed by a U+003A
- COLON character (:) and a U+0020 SPACE character, followed by the
- value with no use of continuation lines (i.e. containing no U+000A
- LINE FEED characters).</p>
-
- <!-- (Cookie headers only use one header for multiple cookies.) -->
-
-<!--(v2-ws-auth)
- <div class="example">
-
- <p>For example, if the server had a username and password that
- applied to <code title="">http://example.com/socket</code>, and
- the WebSocket was being opened to <code
- title="">ws://example.com/socket</code>, it could add them:</p>
-
- <pre>Authorization: Basic d2FsbGU6ZXZl</pre>
-
- </div>
--->
-
- </li>
-
- <li>
-
- <p>Let <var title="">spaces<sub>1</sub></var> be a random integer
- from 1 to 12 inclusive.</p>
-
- <p>Let <var title="">spaces<sub>2</sub></var> be a random integer
- from 1 to 12 inclusive.</p>
-
- <p class="example">For example, 5 and 9.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">max<sub>1</sub></var> be the largest integer
- not greater than 4,294,967,295 divided by <var
- title="">spaces<sub>1</sub></var>.</p>
-
- <p>Let <var title="">max<sub>2</sub></var> be the largest integer
- not greater than 4,294,967,295 divided by <var
- title="">spaces<sub>2</sub></var>.</p>
-
- <p class="example">Continuing the example, 858,993,459 and 477,218,588.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">number<sub>1</sub></var> be a random integer
- from 0 to <var title="">max<sub>1</sub></var> inclusive.</p>
-
- <p>Let <var title="">number<sub>2</sub></var> be a random integer
- from 0 to <var title="">max<sub>2</sub></var> inclusive.</p>
-
- <p class="example">For example, 777,007,543 and 114,997,259.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">product<sub>1</sub></var> be the result of
- multiplying <var title="">number<sub>1</sub></var> and <var
- title="">spaces<sub>1</sub></var> together.</p>
-
- <p>Let <var title="">product<sub>2</sub></var> be the result of
- multiplying <var title="">number<sub>2</sub></var> and <var
- title="">spaces<sub>2</sub></var> together.</p>
-
- <p class="example">Continuing the example, 3,885,037,715 and
- 1,034,975,331.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">key<sub>1</sub></var> be a string consisting
- of <var title="">product<sub>1</sub></var>, expressed in base ten
- using the numerals in the range U+0030 DIGIT ZERO (0) to U+0039
- DIGIT NINE (9).</p>
-
- <p>Let <var title="">key<sub>2</sub></var> be a string consisting
- of <var title="">product<sub>2</sub></var>, expressed in base ten
- using the numerals in the range U+0030 DIGIT ZERO (0) to U+0039
- DIGIT NINE (9).</p>
-
- <p class="example">Continuing the example, "3885037715" and
- "1034975331".</p>
-
- </li>
-
- <li>
-
- <p>Insert between one and twelve random characters from
- the ranges U+0021 to U+002F and U+003A to U+007E into <var
- title="">key<sub>1</sub></var> at random positions.</p>
-
- <p>Insert between one and twelve random characters from
- the ranges U+0021 to U+002F and U+003A to U+007E into <var
- title="">key<sub>2</sub></var> at random positions.</p>
-
- <p class="note">This corresponds to random printable ASCII
- characters other than the digits and the U+0020 SPACE
- character.</p>
-
- <p class="example">Continuing the example, this could lead to
- "P388O503D&ul7{K%gX(%715" and
- "1N?|kUT0or3o4I97N5-S3O31".</p>
-
- </li>
-
- <li>
-
- <p>Insert <var title="">spaces<sub>1</sub></var> U+0020 SPACE
- characters into <var title="">key<sub>1</sub></var> at random
- positions other than the start or end of the string.</p>
-
- <p>Insert <var title="">spaces<sub>2</sub></var> U+0020 SPACE
- characters into <var title="">key<sub>2</sub></var> at random
- positions other than the start or end of the string.</p>
-
- <p class="example">Continuing the example, this could lead to
- "P388 O503D&ul7 {K%gX( %7 15" and
- "1 N ?|k UT0or 3o 4 I97N 5-S3O 31".</p>
-
- </li>
-
- <li>
-
- <p>Add the string consisting of the concatenation of the string
- "Sec-WebSocket-Key1:", a U+0020 SPACE character, and the <var
- title="">key<sub>1</sub></var> value, to <var
- title="">fields</var>.</p>
-
- <p>Add the string consisting of the concatenation of the string
- "Sec-WebSocket-Key2:", a U+0020 SPACE character, and the <var
- title="">key<sub>2</sub></var> value, to <var
- title="">fields</var>.</p>
-
- </li>
-
- <li>
-
- <p>For each string in <var title="">fields</var>, in a random
- order: send the string, encoded as UTF-8, followed by a
- UTF-8-encoded U+000D CARRIAGE RETURN U+000A LINE FEED character
- pair (CRLF). It is important that the fields be output in a
- random order so that servers not depend on the particular order
- used by any particular client.</p>
-
- <p class="note">Only fields explicitly mentioned in the
- requirements of this specification are sent. For example, user
- agents do not send fields such as <code
- title="http-user-agent">User-Agent</code><!--UAS-->, <code
- title="http-accept-language">Accept-Language</code>, or <code
- title="http-content-type">Content-Type</code> in the WebSocket
- handshake.</p>
-
- </li>
-
- <li>
-
- <p>Send a UTF-8-encoded U+000D CARRIAGE RETURN U+000A LINE FEED
- character pair (CRLF).</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">key<sub>3</sub></var> be a string consisting
- of eight random bytes (or equivalently, a random 64 bit unsigned
- integer encoded in big-endian order).</p>
-
- <p class="example">For example, 0x47 0x30 0x22 0x2D 0x5A 0x3F 0x47
- 0x58.</p>
-
- </li>
-
- <li>
-
- <p>Send <var title="">key<sub>3</sub></var> to the server.</p>
-
- </li>
-
- <li>
-
- <p>Read bytes from the server until either the connection closes,
- or a 0x0A byte is read. Let <var title="">field</var> be these
- bytes, including the 0x0A byte.</p>
-
- <p>If <var title="">field</var> is not at least seven bytes long,
- or if the last two bytes aren't 0x0D and 0x0A respectively, or if
- <var title="">field</var> contains any 0x0D bytes other than the
- penultimate byte, or if <var title="">field</var> does not contain
- at least two 0x20 bytes, then <span>fail the WebSocket
- connection</span> and abort these steps.</p>
-
- <p>User agents may apply a timeout to this step, <span title="fail
- the WebSocket connection">failing the WebSocket
- connection</span> if the server does not send back data in a
- suitable time period.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">code</var> be the substring of <var
- title="">field</var> that starts from the byte after the first
- 0x20 byte, and ends with the byte before the second 0x20 byte.</p>
-
- </li>
-
-<!--(removed since the next step is even stricter)
- <li>
-
- <p>If <var title="">code</var> is not three bytes long, or if any
- of the bytes in <var title="">code</var> are not in the range 0x30
- to 0x39, then <span>fail the WebSocket connection</span> and abort
- these steps.</p>
-
- </li>
--->
-
- <li>
-
-<!--(v2-redirect or v2-ws-auth) - - then change the text below
- <p>If <var title="">code</var>, interpreted as UTF-8, is "101",
- then let <var title="">mode</var> be <i title="">normal</i>.</p>
--->
-<!--(v2-redirect)
- <p>If <var title="">code</var>, interpreted as UTF-8, is either
- "<code title="">301</code>", "<code title="">302</code>", "<code
- title="">303</code>", "<code title="">307</code>", then let <var
- title="">mode</var> be <i title="">redirect</i>.</p>
--->
-<!--(v2-ws-auth)
- <p>If <var title="">code</var>, interpreted as UTF-8, is "<code
- title="">401</code>", then let <var title="">mode</var> be <i
- title="">authenticate</i>.</p>
--->
-
- <p>If <var title="">code</var>, interpreted as UTF-8, is "101",
- then move to the next step.</p>
-
- <p>If <var title="">code</var>, interpreted as UTF-8, is "<code
- title="">407</code>", then either close the connection and jump
- back to step 2, providing appropriate authentication information,
- or <span>fail the WebSocket connection</span>. 407 is the code
- used by HTTP meaning "Proxy Authentication Required". User agents
- that support proxy authentication must interpret the response as
- defined by HTTP (e.g. to find and interpret the <code
- title="http-Proxy-Authenticate">Proxy-Authenticate</code>
- header).</p>
-
- <p>Otherwise, <span>fail the WebSocket connection</span> and abort
- these steps.</p>
-
- </li>
-
- <li><p>Let <var title="">fields</var> be a list of name-value
- pairs, initially empty.</p></li>
-
- <li id="ws-ua-field-loop"><p><i title="">Field</i>: Let <var
- title="">name</var> and <var title="">value</var> be empty byte
- arrays.</p></li>
-
- <li>
-
- <p>Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, then
- <span>fail the WebSocket connection</span> and abort these
- steps.</p>
-
- <p>Otherwise, handle the byte as described in the appropriate
- entry below:</p>
-
- <dl class="switch">
-
- <dt>If the byte is 0x0D (UTF-8 CR)</dt>
-
- <dd>If the <var title="">name</var> byte array is empty, then
- jump to the <a href="#ws-ua-fields-processing">fields
- processing</a> step. Otherwise, <span>fail the WebSocket
- connection</span> and abort these steps.</dd>
-
-
- <dt>If the byte is 0x0A (UTF-8 LF)</dt>
-
- <dd><span>Fail the WebSocket connection</span> and abort these
- steps.</dd>
-
-
- <dt>If the byte is 0x3A (UTF-8 :)</dt>
-
- <dd>Move on to the next step.</dd>
-
-
- <dt>If the byte is in the range 0x41 to 0x5A (UTF-8 A-Z)</dt>
-
- <dd>Append a byte whose value is the byte's value plus 0x20 to
- the <var title="">name</var> byte array and redo this step for
- the next byte.</dd>
-
-
- <dt>Otherwise</dt>
-
- <dd>Append the byte to the <var title="">name</var> byte
- array and redo this step for the next byte.</dd>
-
- </dl>
-
- <p class="note">This reads a field name, terminated by a colon,
- converting upper-case letters in the range A-Z to lowercase, and
- aborting if a stray CR or LF is found.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">count</var> equal 0.</p>
-
- <p class="note">This is used in the next step to skip past a space
- character after the colon, if necessary.</p>
-
- </li>
-
- <li>
-
- <p>Read a byte from the server and increment <var
- title="">count</var> by 1.</p>
-
- <p>If the connection closes before this byte is received, then
- <span>fail the WebSocket connection</span> and abort these
- steps.</p>
-
- <p>Otherwise, handle the byte as described in the appropriate
- entry below:</p>
-
- <dl class="switch">
-
- <dt>If the byte is 0x20 (UTF-8 space) and <var title="">count</var> equals 1</dt>
-
- <dd>Ignore the byte and redo this step for the next byte.</dd>
-
-
- <dt>If the byte is 0x0D (UTF-8 CR)</dt>
-
- <dd>Move on to the next step.</dd>
-
-
- <dt>If the byte is 0x0A (UTF-8 LF)</dt>
-
- <dd><span>Fail the WebSocket connection</span> and abort these
- steps.</dd>
-
-
- <dt>Otherwise</dt>
-
- <dd>Append the byte to the <var title="">value</var> byte array
- and redo this step for the next byte.</dd>
-
- </dl>
-
- <p class="note">This reads a field value, terminated by a CRLF,
- skipping past a single space after the colon if there is one.</p>
-
- </li>
-
- <li>
-
- <p>Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, or if
- the byte is not a 0x0A byte (UTF-8 LF), then <span>fail the
- WebSocket connection</span> and abort these steps.</p>
-
- <p class="note">This skips past the LF byte of the CRLF after the
- field.</p>
-
- </li>
-
- <li>
-
- <p>Append an entry to the <var title="">fields</var> list that
- has the name given by the string obtained by interpreting the <var
- title="">name</var> byte array as a UTF-8 byte stream and the
- value given by the string obtained by interpreting the <var
- title="">value</var> byte array as a UTF-8 byte stream.</p>
-
- </li>
-
- <li>
-
- <p>Return to the "<a href="#ws-ua-field-loop">Field</a>" step
- above.</p>
-
- </li>
-
- <li id="ws-ua-fields-processing">
-
- <p><i>Fields processing</i>: Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, or if
- the byte is not a 0x0A byte (UTF-8 LF), then <span>fail the
- WebSocket connection</span> and abort these steps.</p>
-
- <p class="note">This skips past the LF byte of the CRLF after the
- blank line after the fields.</p>
-
- </li>
-
- <li><p>Let the <var title="">list of cookies</var> be empty.</p></li>
-
- <li>
-
- <p>
- <!--(v2-redirect or v2-ws-auth) If <var title="">mode</var> is <i title="">normal</i>, then: -->
-
- If there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="http-upgrade">upgrade</code>", or
-
- if there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="http-connection">connection</code>", or
-
- if there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="http-sec-websocket-origin">sec-websocket-origin</code>", or
-
- if there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="http-sec-websocket-location">sec-websocket-location</code>", or
-
- if the <var title="">protocol</var> was specified but there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="http-sec-websocket-protocol">sec-websocket-protocol</code>", or
-
- if there are any entries in the <var title="">fields</var> list
- whose names are the empty string, then <span>fail the WebSocket
- connection</span> and abort these steps. Otherwise, handle each
- entry in the <var title="">fields</var> list as follows:</p>
-
- <dl class="switch">
-
- <dt>If the entry's name is "<code
- title="http-upgrade">upgrade</code>"</dt>
-
- <dd><p>If the value, <span>converted to ASCII lowercase</span>,
- is not exactly equal to the string "websocket", then <span>fail
- the WebSocket connection</span> and abort these steps.</p></dd>
-
-
- <dt>If the entry's name is "<code
- title="http-connection">connection</code>"</dt>
-
- <dd><p>If the value, <span>converted to ASCII lowercase</span>,
- is not exactly equal to the string "upgrade", then <span>fail the
- WebSocket connection</span> and abort these steps.</p></dd>
-
-
- <dt>If the entry's name is "<code
- title="http-sec-websocket-origin">sec-websocket-origin</code>"</dt>
-
- <dd><p>If the value is not exactly equal to <var
- title="">origin</var>, then <span>fail the WebSocket
- connection</span> and abort these steps. <a
- href="#refsORIGIN">[ORIGIN]</a></p></dd>
-
-
- <dt>If the entry's name is "<code
- title="http-sec-websocket-location">sec-websocket-location</code>"</dt>
-
- <dd>
-
- <p>If the value is not exactly equal to a string obtained from
- the steps to <span>construct a WebSocket URL</span> from <var
- title="">host</var>, <var title="">port</var>, <var
- title="">resource name</var>, and the <var title="">secure</var>
- flag, then <span>fail the WebSocket connection</span> and abort
- these steps.</p>
-
- </dd>
-
-
- <dt>If the entry's name is "<code
- title="http-sec-websocket-protocol">sec-websocket-protocol</code>"</dt>
-
- <dd>
-
- <p>If the <var title="">protocols</var> list was not empty, and
- the value is not exactly equal to one of the strings in the <var
- title="">protocols</var> list, then <span>fail the WebSocket
- connection</span> and abort these steps.</p>
-
- <p>If the the value contains any characters outside the range
- U+0021 to U+007F, then <span>fail the WebSocket
- connection</span> and abort these steps.</p>
-
- <p>Otherwise, let the <dfn>selected WebSocket subprotocol</dfn>
- be the entry's value.</p>
-
- </dd>
-
-
- <dt>If the entry's name is "<code
- title="http-setcookie">set-cookie</code>" or "<code
- title="http-setcookie2">set-cookie2</code>" or another
- cookie-related field name</dt>
-
- <dd>
-
- <p>If the relevant specification is supported by the user agent,
- add the cookie, interpreted as defined by the appropriate
- specification, to the <var title="">list of cookies</var>, with
- the resource being the one with the host <var
- title="">host</var>, the port <var title="">port</var>, the path
- (and possibly query parameters) <var title="">resource
- name</var>, and the scheme <code title="">http</code> if <var
- title="">secure</var> is false and <code title="">https</code>
- if <var title="">secure</var> is true.
-<!--END complete--><!--END epub-->
- <a href="#refsRFC2109">[RFC2109]</a>
- <a href="#refsRFC2965">[RFC2965]</a>
-<!--START complete--><!--START epub--><!--END websocket-protocol-->
- <a href="#refsCOOKIES">[COOKIES]</a>
-<!--START websocket-protocol-->
- </p>
-
- <p>If the relevant specification is not supported by the user
- agent, then the field must be ignored.</p>
-
- <p class="note">The cookies added to the <var title="">list of
- cookies</var> are discarded if the connection fails to be
- established. Only if and when the connection is established do
- the cookies actually get applied.</p>
-
- </dd>
-
-
- <!--UAS: 'Server' -->
-
-
- <dt>Any other name</dt>
-
- <dd>Ignore it.</dd>
-
- </dl>
-
- <hr>
-<!--(v2-redirect)
-redirect support
-we should probably reintroduce this at some point, with the
-multi-origin semantics described in [ORIGIN] applying. (http-origin)
-
- <p>If <var title="">mode</var> is <i title="">redirect</i>, then:
- If there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="">location</code>", then <span>fail the WebSocket
- connection</span> and abort these steps. Otherwise, handle each
- entry in the <var title="">fields</var> list as follows:</p>
-
- <dl class="switch">
-
- <dt>If the entry's name is "<code
- title="">location</code>"</dt>
-
- <dd>
-
- <ol>
-
- <li><p>Let <var title="">was secure</var> have the value of
- <var title="">secure</var>.</p></li>
-
- <li><p><span>Parse a WebSocket URL's components</span> from
- the <var title="">url</var> argument, to obtain new values for
- <var title="">host</var>, <var title="">port</var>, <var
- title="">resource name</var>, and <var
- title="">secure</var>. If this fails, <span>fail the WebSocket
- connection</span> and abort these steps.</p></li>
-
- <li><p>If <var title="">was secure</var> is true but <var
- title="">secure</var> is now false, <span>fail the WebSocket
- connection</span> and abort these steps.</p></li>
-
- <li><p>If <var title="">port</var> is a port to which the user
- agent is configured to block access, then <span>fail the
- WebSocket connection</span> and abort these steps. (User agents
- typically block access to well-known ports like SMTP.)</p></li>
-
- <li><p>Close the connection if the server has not already done
- so.</p></li>
-
- <li><p><span>Apply the cookies</span> in the <var title="">list
- of cookies</var>.</p></li>
-
- <li><p>Jump back to the first step of the overall algorithm
- (the very top of the handshake).</p></li>
-
- </ol>
-
- </dd>
-
-
- <dt>Any other name</dt>
-
- <dd>Ignore it.</dd>
-
- </dl>
--->
-
-<!--(v2-ws-auth)
- <hr>
-
- <p>If <var title="">mode</var> is <i title="">authenticate</i>,
- then: If there is not exactly one entry in the <var
- title="">fields</var> list whose name is "<code
- title="">www-authenticate</code>", then <span>fail the WebSocket
- connection</span> and abort these steps. Otherwise, handle each
- entry in the <var title="">fields</var> list as follows:</p>
-
- <dl class="switch">
-
- <dt>If the entry's name is "<code
- title="">www-authenticate</code>"</dt>
-
- <dd>
-
- <p><span>Apply the cookies</span> in the <var title="">list of
- cookies</var>, then obtain credentials in a manner consistent
- with the requirements for handling the
- <code>WWW-Authenticate</code> header in HTTP, and then close
- the connection (if the server has not already done so) and jump
- back to the step labeled <i>connect</i>, including the relevant
- authentication headers in the new request.
---><!--END complete--><!--END epub--><!--
- <a href="#refsRFC2616">[RFC2616]</a>
---><!--START complete--><!--START epub--><!--END websocket-protocol--><!--
- <a href="#refsHTTP">[HTTP]</a>
---><!--START websocket-protocol--><!--
- </p>
-
- </dd>
-
- <dt>Any other name</dt>
-
- <dd>Ignore it.</dd>
-
- </dl>
--->
-
- </li>
-
- <li>
-
- <p>Let <var title="">challenge</var> be the concatenation of <var
- title="">number<sub>1</sub></var>, expressed as a big-endian
- unsigned 32-bit integer, <var title="">number<sub>2</sub></var>,
- expressed as a big-endian unsigned 32-bit integer, and the eight
- bytes of <var title="">key<sub>3</sub></var> in the order they
- were sent on the wire.</p>
-
- <!--
- perl -e 'foreach (@ARGV) { print pack 'N', $_ }' 777007543 114997259 | hexdump -C
- -->
-
- <p class="example">Using the examples given earlier, this leads to
- the 16 bytes 0x2E 0x50 0x31 0xB7 0x06 0xDA 0xB8 0x0B 0x47 0x30
- 0x22 0x2D 0x5A 0x3F 0x47 0x58.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">expected</var> be the MD5 fingerprint of <var
- title="">challenge</var> as a big-endian 128 bit string. <a
- href="#refsRFC1321">[RFC1321]</a></p>
-
- <!--
- perl -e "print pack 'c*', map { hex } @ARGV" 0x2E 0x50 0x31 0xB7 0x06 0xDA 0xB8 0x0B 0x47 0x30 0x22 0x2D 0x5A 0x3F 0x47 0x58 | md5sum -b
- -->
-
- <p class="example">Using the examples given earlier, this leads to
- the 16 bytes 0x30 0x73 0x74 0x33 0x52 0x6C 0x26 0x71 0x2D 0x32
- 0x5A 0x55 0x5E 0x77 0x65 0x75. In UTF-8, these bytes correspond to
- the string "0st3Rl&q-2ZU^weu".</p>
-
- </li>
-
- <li>
-
- <p>Read sixteen bytes from the server. Let <var
- title="">reply</var> be those bytes.</p>
-
- <p>If the connection closes before these bytes are received, then
- <span>fail the WebSocket connection</span> and abort these
- steps.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">reply</var> does not exactly equal <var
- title="">expected</var>, then <span>fail the WebSocket
- connection</span> and abort these steps.</p>
-
- </li>
-
- <li><p>If the <var title="">defer cookies</var> flag is not set,
- <span>apply the cookies</span> in the <var title="">list of
- cookies</var>.</p></li>
-
- <li>
-
- <p>The <dfn>WebSocket connection is established</dfn>. Now the
- user agent must send and receive to and from the connection as
- described in the next section.</p>
-
- <p>If the <var title="">defer cookies</var> flag is set, store the
- <var title="">list of cookies</var> for use by the component that
- invoked this algorithm.</p>
-
- </li>
-
- </ol>
-
- <p>Where the algorithm above requires that a user agent <span>fail
- the WebSocket connection</span>, the user agent may first read an
- arbitrary number of further bytes from the connection (and then
- discard them) before actually <span title="fail the WebSocket
- connection">failing the WebSocket connection</span>. Similarly, if a
- user agent can show that the bytes read from the connection so far
- are such that there is no subsequent sequence of bytes that the
- server can send that would not result in the user agent being
- required to <span>fail the WebSocket connection</span>, the user
- agent may immediately <span>fail the WebSocket connection</span>
- without waiting for those bytes.</p>
-
- <p class="note">The previous paragraph is intended to make it
- conforming for user agents to implement the algorithm in subtlely
- different ways that are equivalent in all ways except that they
- terminate the connection at earlier or later points. For example, it
- enables an implementation to buffer the entire handshake response
- before checking it, or to verify each field as it is received rather
- than collecting all the fields and then checking them as a
- block.</p>
-
- <p>When the user agent is to <dfn>apply the cookies</dfn> in a <var
- title="">list of cookies</var>, it must handle each cookie in the
- <var title="">list of cookies</var> as defined by the appropriate
- specification.
-<!--END complete--><!--END epub-->
- <a href="#refsRFC2109">[RFC2109]</a>
- <a href="#refsRFC2965">[RFC2965]</a>
-<!--START complete--><!--START epub--><!--END websocket-protocol-->
- <a href="#refsCOOKIES">[COOKIES]</a>
-<!--START websocket-protocol-->
- </p>
-
-
- <h6>Data framing</h6>
-
- <p>Once a <span>WebSocket connection is established</span>, the user
- agent must run through the following state machine for the bytes
- sent by the server. If at any point during these steps a read is
- attempted but fails because the <span>WebSocket connection is
- closed</span>, then abort.</p>
-
- <ol>
-
- <li>
-
- <p>Try to read a byte from the server. Let <var title="">frame
- type</var> be that byte.</p>
-
- </li>
-
- <li>
-
- <p>Try to read eight more bytes from the server. Let <var
- title="">frame length</var> be the result of interpreting those
- eight bytes as a big-endian 64 bit unsigned integer.</p>
-
- </li>
-
- <li>
-
- <p>Try to read <var title="">frame length</var> bytes from the
- server. Let <var title="">raw data</var> be those bytes.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">error</var> be false.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">frame length</var> is greater than the length
- of data the user agent is able to deal with at this time, set <var
- title="">error</var> to true.</p>
-
- <p>User agents should ensure they are always able to deal with
- lengths up to at least 65536 bytes.</p>
-
- <p class="note">The minimum expected supported length will likely
- be increased in future revisions of this protocol.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">error</var> is still false, handle the <var
- title="">frame type</var> byte as follows:</p>
-
- <dl>
-
- <dt>If the <var title="">frame type</var> byte is 0x00</dt>
-
- <dd>
-
- <p>If <var title="">frame length</var> is not zero, then set
- <var title="">error</var> to true. Otherwise, run these
- steps:</p>
-
- <ol>
-
- <li>If <span title="the WebSocket closing handshake has
- started">the WebSocket closing handshake has not yet
- started</span>, then <span>start the WebSocket closing
- handshake</span>.</li>
-
- <li>Wait until either <span>the WebSocket closing handshake
- has started</span> or the <span>WebSocket connection is
- closed</span>.</li>
-
- <li>If the <span title="WebSocket connection is
- closed">WebSocket connection is not already closed</span>,
- then <span>close the WebSocket connection</span>: <dfn>The
- WebSocket closing handshake has finished</dfn>. (If the
- connection closes before this happens, then the closing
- handshake doesn't finish.)</li>
-
- <li>Abort these steps. Any data on the connection after the
- 0x00 frame is discarded.</li>
-
- </ol>
-
- </dd>
-
- <dt>If the <var title="">frame type</var> byte is 0xFF</dt>
-
- <dd>
-
- <p><dfn>A WebSocket message has been received</dfn> with
- obtained by interpreting <var title="">raw data</var> as a UTF-8
- string.</p>
-
- </dd>
-
- <dt>Otherwise (the <var title="">frame type</var> byte is in the range 0x01 to 0xFE)</dt>
-
- <dd>
-
- <p>Set <var title="">error</var> to true.</p>
-
- </dd>
-
- </dl>
-
- </li>
-
- <li>
-
- <p>If <var title="">error</var> is true, then <dfn>a WebSocket
- error has been detected</dfn>. Discard <var title="">raw
- data</var>.</p>
-
- </li>
-
- <li><p>Return to the first step to read the next byte.</p></li>
-
- </ol>
-
- <p>If the user agent runs out of resources for buffering incoming
- data, or hits an artificial resource limit intended to avoid
- resource starvation, then it must <span>fail the WebSocket
- connection</span>.</p>
-
- <hr>
-
- <p>Once a <span>WebSocket connection is established</span>, but
- before <span>the WebSocket closing handshake has started</span>, the
- user agent must use the following steps to <dfn>send <var
- title="">data</var> using the WebSocket</dfn>:</p>
-
- <ol>
-
- <li><p>Encode the text in <var title="">data</var> using UTF-8 to
- obtain the byte stream <var title="">bytes</var>.</p></li>
-
- <li><p>Send a 0xFF byte to the server.</p></li>
-
- <li><p>Send the number of bytes in <var title="">bytes</var>, as a
- 64 bit big-endian unsigned integer, to the server.</p></li>
-
- <li><p>Send <var title="">raw data</var> to the server.</p></li>
-
- </ol>
-
- <p>Once <span>the WebSocket closing handshake has started</span>,
- the user agent must not send any further data on the connection.</p>
-
- <hr>
-
- <p>Once a <span>WebSocket connection is established</span>, the user
- agent must use the following steps to <dfn>start the WebSocket
- closing handshake</dfn>. These steps must be run asynchronously
- relative to whatever algorithm invoked this one.</p>
-
- <ol>
-
- <li><p>If <span>the WebSocket closing handshake has started</span>,
- then abort these steps.</p></li>
-
- <li><p>Send nine 0x00 bytes to the server.</p></li>
-
- <li><p><dfn>The WebSocket closing handshake has started</dfn>.</p></li>
-
- <li><p>Wait a user-agent-determined length of time, or until the
- <span>WebSocket connection is closed</span>.</p>
-
- <li>If the <span title="WebSocket connection is closed">WebSocket
- connection is not already closed</span>, then <span>close the
- WebSocket connection</span>. (If this happens, then the closing
- handshake doesn't finish.)</li>
-
- </ol>
-
- <p class="note">If the user agent initiates it, the closing
- handshake <span title="the WebSocket closing handshake has
- finished">finishes</span> once the server returns the 0x00 frame, as
- described above.</p>
-
- <hr>
-
- <p>If at any point there is a fatal problem with sending data to the
- server, the user agent must <span>fail the WebSocket
- connection</span>.</p>
-
-
- <h6>Handling errors in UTF-8 from the server</h6>
-
- <p>When a client is to interpret a byte stream as UTF-8 but finds
- that the byte stream is not in fact a valid UTF-8 stream, then any
- bytes or sequences of bytes that are not valid UTF-8 sequences must
- be interpreted as a U+FFFD REPLACEMENT CHARACTER.</p>
-
-
-
- <h5>Server-side requirements</h5>
-
- <p><i>This section only applies to servers.</i></p>
-
- <p>Servers may offload the management of the connection to other
- agents on the network, for example load balancers and reverse
- proxies. In such a situation, the server for the purposes of
- conformance is considered to include all parts of the server-side
- infrastructure from the first device to terminate the TCP connection
- all the way to the server that processes requests and sends
- responses.</p>
-
- <div class="example">
-
- <p>For example, a data center might have a server that responds to
- Web Socket requests with an appropriate handshake, and then passes
- the connection to another server to actually process the data
- frames. For the purposes of this specification, the "server" is the
- combination of both computers.</p>
-
- </div>
-
-
- <h6>Reading the client's opening handshake</h6>
-
- <p>When a client starts a WebSocket connection, it sends its part of
- the opening handshake. The server must parse at least part of this
- handshake in order to obtain the necessary information to generate
- the server part of the handshake.</p>
-
- <p>The client handshake consists of the following parts. If the
- server, while reading the handshake, finds that the client did not
- send a handshake that matches the description below, the server
- should <span>abort the WebSocket connection</span>.</p>
-
- <ol>
-
- <li><p>The three-character UTF-8 string "GET".</p></li>
-
- <li><p>A UTF-8-encoded U+0020 SPACE character (0x20 byte).</p></li>
-
- <li><p>A string consisting of all the bytes up to the next
- UTF-8-encoded U+0020 SPACE character (0x20 byte). The result of
- decoding this string as a UTF-8 string is the name of the resource
- requested by the server. If the server only supports one resource,
- then this can safely be ignored; the client verifies that the right
- resource is supported based on the information included in the
- server's own handshake. The resource name will begin with U+002F
- SOLIDUS character (/) and will only include characters in the range
- U+0021 to U+007E.</p></li>
-
- <li><p>A string of bytes terminated by a UTF-8-encoded U+000D
- CARRIAGE RETURN U+000A LINE FEED character pair (CRLF). All the
- characters from the second 0x20 byte up to the first 0x0D 0x0A byte
- pair in the data from the client can be safely ignored. (It will
- probably be the string "HTTP/1.1".)</p>
-
- <li>
-
- <p>A series of fields.</p>
-
- <p>Each field is terminated by a UTF-8-encoded U+000D CARRIAGE
- RETURN U+000A LINE FEED character pair (CRLF). The end of the
- fields is denoted by the terminating CRLF pair being followed
- immediately by another CRLF pair.</p>
-
- <p class="note">In other words, the fields start with the first
- 0x0D 0x0A byte pair, end with the first 0x0D 0x0A 0x0D 0x0A byte
- sequence, and are separate from each other by 0x0D 0x0A byte
- pairs.</p>
-
- <p>The fields are encoded as UTF-8.</p>
-
- <p>Each field consists of a name, consisting of one or more
- characters in the ranges U+0021 to U+0039 and U+003B to U+007E,
- followed by a U+003A COLON character (:) and a U+0020 SPACE
- character, followed by zero or more characters forming the
- value.</p>
-
- <p>The expected field names, the meaning of their corresponding
- values, and the processing servers are required to apply to those
- fields, are described below, after the description of the client
- handshake.</p>
-
- </li>
-
- <li>
-
- <p>After the first 0x0D 0x0A 0x0D 0x0A byte sequence, indicating
- the end of the fields, the client sends eight random bytes. These
- are used in constructing the server handshake.</p>
-
- </li>
-
- </ol>
-
- <p>The expected field names, and the meaning of their corresponding
- values, are as follows. Field names must be compared in an
- <span>ASCII case-insensitive</span> manner.</p>
-
- <dl>
-
- <dt><code title="http-upgrade">Upgrade</code></dt>
-
- <dd>
-
- <p>Invariant part of the handshake. Will always have a value that
- is an <span>ASCII case-insensitive</span> match for the string
- "WebSocket".</p>
-
- <p>Can be safely ignored, though the server should <span>abort the WebSocket
- connection</span> if this field is absent or has a different
- value, to avoid vulnerability to cross-protocol attacks.</p>
-
- </dd>
-
- <dt><code title="http-connection">Connection</code></dt>
-
- <dd>
-
- <p>Invariant part of the handshake. Will always have a value that
- is an <span>ASCII case-insensitive</span> match for the string
- "Upgrade".</p>
-
- <p>Can be safely ignored, though the server should <span>abort the WebSocket
- connection</span> if this field is absent or has a different
- value, to avoid vulnerability to cross-protocol attacks.</p>
-
- </dd>
-
- <dt><code title="http-host">Host</code></dt>
-
- <dd>
-
- <p>The value gives the hostname that the client intended to use
- when opening the WebSocket. It would be of interest in particular
- to virtual hosting environments, where one server might serve
- multiple hosts, and might therefore want to return different
- data.</p>
-
- <p>Can be safely ignored, though the server should <span>abort the WebSocket
- connection</span> if this field is absent or has a value that
- does not match the server's host name, to avoid vulnerability to
- cross-protocol attacks and DNS rebinding attacks.</p>
-
- </dd>
-
- <dt><code title="http-origin">Origin</code></dt>
-
- <dd>
-
- <p>The value gives the scheme, hostname, and port (if it's not the
- default port for the given scheme) of the page that asked the
- client to open the WebSocket. It would be interesting if the
- server's operator had deals with operators of other sites, since
- the server could then decide how to respond (or indeed,
- <em>whether</em> to respond) based on which site was requesting a
- connection. <a href="#refsORIGIN">[ORIGIN]</a></p>
-
- <p>Can be safely ignored, though the server should <span>abort the WebSocket
- connection</span> if this field is absent or has a value that
- does not match one of the origins the server is expecting to
- communicate with, to avoid vulnerability to cross-protocol attacks
- and cross-site scripting attacks.</p>
-
- </dd>
-
- <dt><code title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code></dt>
-
- <dd>
-
- <p>The value gives the names of subprotocols that the client is
- willing to use, as a space-separated list in the order that the
- client prefers the protocols. It would be interesting if the
- server supports multiple protocols or protocol versions.</p>
-
- <p>Can be safely ignored, though the server may <span>abort the
- WebSocket connection</span> if the field is absent but the
- conventions for communicating with the server are such that the
- field is expected; and the server should <span>abort the WebSocket
- connection</span> if the field does not contain a value that does
- matches one of the subprotocols that the server supports, to avoid
- integrity errors once the connection is established.</p>
-
- </dd>
-
- <dt><code title="http-sec-websocket-key1">Sec-WebSocket-Key1</code></dt>
- <dt><code title="http-sec-websocket-key2">Sec-WebSocket-Key2</code></dt>
-
- <dd>
-
- <p>The values provide the information required for computing the
- server's handshake, as described in the next section.</p>
-
- </dd>
-
- <!--UAS: 'User-Agent' -->
-
- <dt>Other fields</dt>
-
- <dd>
-
- <p>Other fields can be used, such as "<code
- title="">Cookie</code>"<!--(v2-ws-auth) or
- "<code>Authorization</code>"-->, for authentication
- purposes. Their semantics are equivalent to the semantics of the
- HTTP headers with the same names.</p>
-
- </dd>
-
- </dl>
-
- <p>Unrecognized fields can be safely ignored, and are probably
- either the result of intermediaries injecting fields unrelated to
- the operation of the WebSocket protocol, or clients that support
- future versions of the protocol offering options that the server
- doesn't support.</p>
-
-
- <h6>Sending the server's opening handshake</h6>
-
- <p>When a client establishes a WebSocket connection to a server, the
- server must run the following steps.</p>
-
- <ol>
-
- <li>
-
- <p>If the server supports encryption, perform a TLS handshake over
- the connection. If this fails (e.g. the client indicated a host
- name in the extended client hello "server_name" extension that the
- server does not host), then close the connection; otherwise, all
- further communication for the connection (including the server
- handshake) must run through the encrypted tunnel. <a
- href="#refsRFC2246">[RFC2246]</a></p>
-
- <p>Servers must support the Next Protocol Negotiation extension in
- the TLS handshake, advertising support for the
- "776562736f636b6574" protocol ("websocket" in UTF-8). <a
- href="#refsNPN">[NPN]</a>
-
- </li>
-
- <li>
-
- <p>Establish the following information:</p>
-
- <dl>
-
- <dt><var title="">host</var></dt>
-
- <dd>The host name or IP address of the WebSocket server, as it is
- to be addressed by clients. The host name must be
- punycode-encoded if necessary. If the server can respond to
- requests to multiple hosts (e.g. in a virtual hosting
- environment), then the value should be derived from the client's
- handshake, specifically from the "<code
- title="http-host">Host</code>" field. The <var
- title="">host</var> value must be lowercase (not containing
- characters in the range U+0041 LATIN CAPITAL LETTER A to U+005A
- LATIN CAPITAL LETTER Z).</dd>
-
- <dt><var title="">port</var></dt>
-
- <dd>The port number on which the server expected and/or received
- the connection.</dd>
-
- <dt><var title="">resource name</var></dt>
-
- <dd>An identifier for the service provided by the server. If the
- server provides multiple services, then the value should be
- derived from the resource name given in the client's
- handshake.</dd>
-
- <dt><var title="">secure flag</var></dt>
-
- <dd>True if the connection is encrypted or if the server expected
- it to be encrypted; false otherwise.</dd>
-
- <dt><var title="">origin</var></dt>
-
- <dd>The <span title="ASCII serialization of an origin">ASCII
- serialization</span> of the origin that the server is willing to
- communicate with, <span>converted to ASCII lowercase</span>. If
- the server can respond to requests from multiple origins (or
- indeed, all origins), then the value should be derived from the
- client's handshake, specifically from the "<code
- title="http-origin">Origin</code>" field. <a
- href="#refsORIGIN">[ORIGIN]</a></dd>
-
- <dt><var title="">subprotocol</var></dt>
-
- <dd>Either null, or a string representing the subprotocol the
- server is ready to use. If the server supports multiple
- subprotocols, then the value should be derived from the client's
- handshake, specifically from the "<code
- title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>"
- field. The absence of such a field is equivalent to the null
- value. The empty string is not the same as the null value for
- these purposes.</dd>
-
- <dt><var title="">key<sub title="">1</sub></var></dt>
-
- <dd>The value of the "<code
- title="http-sec-websocket-key1">Sec-WebSocket-Key1</code>"
- field in the client's handshake.</dd>
-
- <dt><var title="">key<sub title="">2</sub></var></dt>
-
- <dd>The value of the "<code
- title="http-sec-websocket-key2">Sec-WebSocket-Key2</code>"
- field in the client's handshake.</dd>
-
- <dt><var title="">key<sub title="">3</sub></var></dt>
-
- <dd>The eight random bytes sent after the first 0x0D 0x0A 0x0D
- 0x0A sequence in the client's handshake.</dd>
-
- </dl>
-
- </li>
-
- <li>
-
- <p>Let <var title="">location</var> be the string that results
- from <span title="construct a WebSocket URL">constructing a
- WebSocket URL</span> from <var title="">host</var>, <var
- title="">port</var>, <var title="">resource name</var>, and <var
- title="">secure flag</var>.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">key-number<sub title="">1</sub></var> be the digits (characters
- in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9)) in
- <var title="">key<sub title="">1</sub></var>, interpreted as a base ten integer,
- ignoring all other characters in <var title="">key<sub title="">1</sub></var>.</p>
-
- <p>Let <var title="">key-number<sub title="">2</sub></var> be the digits (characters
- in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9)) in
- <var title="">key<sub title="">2</sub></var>, interpreted as a base ten integer,
- ignoring all other characters in <var title="">key<sub title="">2</sub></var>.</p>
-
- <p>If either <var title="">key-number<sub title="">1</sub></var>
- or <var title="">key-number<sub title="">2</sub></var> is greater
- than 4,294,967,295, then <span>abort the WebSocket
- connection</span>. This is a symptom of an attack.</p>
-
- <p class="note">If the client is a conforming client, then both
- <var title="">key-number<sub title="">1</sub></var> and <var
- title="">key-number<sub title="">2</sub></var> will fit in
- unsigned 32-bit integers.</p>
-
- <div class="example">
-
- <p>For example, assume that the client handshake was:</p>
-
- <pre>GET / HTTP/1.1
-Connection: Upgrade
-Host: example.com
-Upgrade: WebSocket
-Sec-WebSocket-Key1: 3e6b263 4 17 80
-Origin: http://example.com
-Sec-WebSocket-Key2: 17 9 G`ZD9 2 2b 7X 3 /r90
-
-WjN}|M(6</pre>
-
- <p>The <var title="">key-number<sub title="">1</sub></var> would be the number
- 3,626,341,780, and the <var title="">key-number<sub title="">2</sub></var> would be
- the number 1,799,227,390.</p>
-
- <p>In this example, incidentally, <var title="">key<sub title="">3</sub></var> is
- "WjN}|M(6", or 0x57 0x6A 0x4E 0x7D 0x7C 0x4D 0x28 0x36.</p>
-
- </div>
-
- </li>
-
- <li>
-
- <p>Let <var title="">spaces<sub title="">1</sub></var> be the number of U+0020 SPACE
- characters in <var title="">key<sub title="">1</sub></var>.</p>
-
- <p>Let <var title="">spaces<sub title="">2</sub></var> be the number of U+0020 SPACE
- characters in <var title="">key<sub title="">2</sub></var>.</p>
-
- <p>If either <var title="">spaces<sub title="">1</sub></var> or
- <var title="">spaces<sub title="">2</sub></var> is zero, then
- <span>abort the WebSocket connection</span>. This is a symptom of
- a cross-protocol attack.</p>
-
- <p class="note">If the client is a conforming client, then both
- <var title="">spaces<sub title="">1</sub></var> and <var
- title="">spaces<sub title="">2</sub></var> will easily fit in
- unsigned 32-bit integers (indeed, they won't be greater than
- 12).</p>
-
- <p class="example">In the example above, <var
- title="">spaces<sub title="">1</sub></var> would be 4 and <var title="">spaces<sub title="">2</sub></var>
- would be 10.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">key-number<sub title="">1</sub></var> is not an integral multiple
- of <var title="">spaces<sub title="">1</sub></var>, then <span>abort the WebSocket
- connection</span>.</p>
-
- <p>If <var title="">key-number<sub title="">2</sub></var> is not an integral multiple
- of <var title="">spaces<sub title="">2</sub></var>, then <span>abort the WebSocket
- connection</span>.</p>
-
- <p class="note">This can only happen if the client is not a
- conforming WebSocket client.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">part<sub title="">1</sub></var> be <var
- title="">key-number<sub title="">1</sub></var> divided by <var title="">spaces<sub title="">1</sub></var>.</p>
-
- <p>Let <var title="">part<sub title="">2</sub></var> be <var
- title="">key-number<sub title="">2</sub></var> divided by <var title="">spaces<sub title="">2</sub></var>.</p>
-
- <p class="example">In the example above, <var title="">part<sub title="">1</sub></var>
- would be 906,585,445 and <var title="">part<sub title="">2</sub></var> would be
- 179,922,739.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">challenge</var> be the concatenation of <var
- title="">part<sub title="">1</sub></var>, expressed as a
- big-endian unsigned 32-bit integer, <var title="">part<sub
- title="">2</sub></var>, expressed as a big-endian unsigned 32-bit
- integer, and the eight bytes of <var title="">key<sub
- title="">3</sub></var> in the order they were sent on the
- wire.</p>
-
- <!--
- perl -e 'foreach (@ARGV) { print pack 'N', $_ }' 906585445 179922739 | hexdump -C
- -->
-
- <p class="example">In the example above, this would be the 16
- bytes 0x36 0x09 0x65 0x65 0x0A 0xB9 0x67 0x33 0x57 0x6A 0x4E 0x7D
- 0x7C 0x4D 0x28 0x36.</p>
-
- </li>
-
- <li>
-
- <p>Let <var title="">response</var> be the MD5 fingerprint of <var
- title="">challenge</var> as a big-endian 128 bit string. <a
- href="#refsRFC1321">[RFC1321]</a></p>
-
- <!--
- perl -e "print pack 'c*', map { hex } @ARGV" 0x36 0x09 0x65 0x65 0x0A 0xB9 0x67 0x33 0x57 0x6A 0x4E 0x7D 0x7C 0x4D 0x28 0x36 | md5sum -b
- -->
-
- <p class="example">In the example above, this would be the 16
- bytes 0x6E 0x60 0x39 0x65 0x42 0x6B 0x39 0x7A 0x24 0x52 0x38 0x70
- 0x4F 0x74 0x56 0x62, or "n`9eBk9z$R8pOtVb" in UTF-8.
-
- </li>
-
- <li>
-
- <p>Send the following line, terminated by the two characters
- U+000D CARRIAGE RETURN and U+000A LINE FEED (CRLF) and encoded as
- UTF-8, to the client:</p>
-
- <pre>HTTP/1.1 101 WebSocket Protocol Handshake</pre>
-
- <p>This line may be sent differently if necessary, but must match
- the Status-Line production defined in the HTTP specification, with
- the Status-Code having the value 101.</p>
-
- </li>
-
- <li>
-
- <p>Send the following fields to the client. Each field must be
- sent as a line consisting of the field name, which must be an
- <span>ASCII case-insensitive</span> match for the field name in
- the list below, followed by a U+003A COLON character (:) and a
- U+0020 SPACE character, followed by the field value as specified
- in the list below, followed by the two characters U+000D CARRIAGE
- RETURN and U+000A LINE FEED (CRLF). The lines must be encoded as
- UTF-8. The lines may be sent in any order.</p>
-
- <dl>
-
- <dt><code title="http-upgrade">Upgrade</code></dt>
-
- <dd><p>The value must be the string "WebSocket".</p></dd>
-
- <dt><code title="http-connection">Connection</code></dt>
-
- <dd><p>The value must be the string "Upgrade".</p></dd>
-
- <dt><code title="http-sec-websocket-location">Sec-WebSocket-Location</code></dt>
-
- <dd><p>The value must be <var title="">location</var></p></dd>
-
- <dt><code title="http-sec-websocket-origin">Sec-WebSocket-Origin</code></dt>
-
- <dd><p>The value must be <var title="">origin</var></p></dd>
-
- <dt><code title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code></dt>
-
- <dd>
-
- <p>This field must be included if <var
- title="">subprotocol</var> is not null, and must not be included
- if <var title="">subprotocol</var> is null.</p>
-
- <p>If included, the value must be <var title="">subprotocol</var></p>
-
- </dd>
-
- </dl>
-
- <p>Optionally, include "<code
- title="http-setcookie">Set-Cookie</code>", "<code
- title="http-setcookie2">Set-Cookie2</code>", or other
- cookie-related fields, with values equal to the values that would
- be used for the identically named HTTP headers.
-<!--END complete--><!--END epub-->
- <a href="#refsRFC2109">[RFC2109]</a>
- <a href="#refsRFC2965">[RFC2965]</a>
-<!--START complete--><!--START epub--><!--END websocket-protocol-->
- <a href="#refsCOOKIES">[COOKIES]</a>
-<!--START websocket-protocol-->
- </p>
-
- <!--UAS: optionally, include 'Server:' field -->
-
- </li>
-
- <li>
-
- <p>Send two bytes 0x0D 0x0A (UTF-8 CRLF).</p>
-
- </li>
-
- <li>
-
- <p>Send <var title="">response</var>.</p>
-
- </li>
-
- </ol>
-
- <p>This completes the server's handshake. If the server finishes
- these steps without <span title="abort the WebSocket
- connection">aborting the WebSocket connection</span>, and if the
- client does not then <span>fail the WebSocket connection</span>,
- then the connection is established and the server may begin and
- receiving sending data, as described in the next section.</p>
-
-
-
- <h6 id="ws-sd-framing">Data framing</h6>
-
- <p>The server must run through the following steps to process the
- bytes sent by the client. If at any point during these steps a read
- is attempted but fails because the <span>WebSocket connection is
- closed</span>, then abort.</p>
-
- <ol>
-
- <li>
-
- <p>Try to read a byte from the client. Let <var title="">frame
- type</var> be that byte.</p>
-
- </li>
-
- <li>
-
- <p>Try to read eight more bytes from the client. Let <var
- title="">frame length</var> be the result of interpreting those
- eight bytes as a big-endian 64 bit unsigned integer.</p>
-
- </li>
-
- <li>
-
- <p>Try to read <var title="">frame length</var> bytes from the
- client. Let <var title="">raw data</var> be those bytes.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">frame length</var> is greater than the length
- of data the server is able to deal with at this time, the server
- may abort these steps and either immediately disconnect from the
- client or set the <var title="">client terminated</var>
- flag. Alternatively, the server may just discard this frame and
- jump back to the first step.</p>
-
- </li>
-
- <li>
-
- <p>Handle the <var title="">frame type</var> byte as follows:</p>
-
- <dl>
-
- <dt>If the <var title="">frame type</var> byte is 0x00 and the <var title="">frame length</var> is 0</dt>
-
- <dd>
-
- <p>Set the <var title="">client terminated</var> flag and abort
- these steps. All further data sent by the client should be
- discarded.</p>
-
- </dd>
-
- <dt>If the <var title="">frame type</var> byte is 0xFF</dt>
-
- <dd>
-
- <p>Interpret <var title="">raw data</var> as a UTF-8 string, and
- apply whatever server-specific processing is to occur for the
- resulting string (the message from the client).</p>
-
- </dd>
-
- <dt>Otherwise</dt>
-
- <dd>
-
- <p>The server may abort these steps and either immediately
- disconnect from the client or set the <var title="">client
- terminated</var> flag.</p>
-
- </dd>
-
- </dl>
-
- </li>
-
- <li><p>Return to the first step to read the next byte.</p></li>
-
- </ol>
-
- <hr>
-
- <p>The server must run through the following steps to send strings
- to the client:</p>
-
- <ol>
-
- <li><p>Encode the text using UTF-8 to obtain the byte stream <var
- title="">raw data</var>.</p></li>
-
- <li><p>Send a 0xFF byte to the client.</p></li>
-
- <li><p>Send the number of bytes in <var title="">raw data</var>, as
- a 64 bit big-endian unsigned integer, to the client.</p></li>
-
- <li><p>Send <var title="">raw data</var> to the client.</p></li>
-
- </ol>
-
- <hr>
-
- <p>At any time, the server may decide to terminate the WebSocket
- connection by running through the following steps. These steps
- should be run when the <var title="">client terminated</var> flag is
- set, if they aren't already running.</p>
-
- <ol>
-
- <li><p>Send nine 0x00 bytes to the client to indicate the start of
- the closing handshake.</p></li>
-
- <li><p>Wait until the <var title="">client terminated</var> flag
- has been set, or until a server-defined timeout expires.</p></li>
-
- <li><p><span>Close the WebSocket connection</span>.</p></li>
-
- </ol>
-
- <p>Once these steps have started, the server must not send any
- further data to the client. The nine 0x00 bytes indicate the end of
- the server's data, and further bytes will be discarded by the
- client.</p>
-
-
- <h6>Handling errors in UTF-8 from the client</h6>
-
- <p>When a server is to interpret a byte stream as UTF-8 but finds
- that the byte stream is not in fact a valid UTF-8 stream, behavior
- is undefined. A server could close the connection, convert invalid
- byte sequences to U+FFFD REPLACEMENT CHARACTERs, store the data
- verbatim, or perform application-specific processing. Subprotocols
- layered on the WebSocket protocol might define specific behavior
- for servers.</p>
-
-
-
- <h5>Closing the connection</h5>
-
- <h6>Client-initiated closure</h6>
-
- <p>Certain algorithms require the user agent to <dfn>fail the
- WebSocket connection</dfn>. To do so, the user agent must
- <span>close the WebSocket connection</span>, and may report the
- problem to the user (which would be especially useful for
- developers).</p>
-
- <p>Except as indicated above or as specified by the application
- layer (e.g. a script using the WebSocket API), user agents should
- not close the connection.</p>
-
- <p>User agents must not convey any failure information to scripts in
- a way that would allow a script to distinguish the following
- situations:</p>
-
- <ul>
-
- <li>A server whose host name could not be resolved.</li>
-
- <li>A server to which packets could not successfully be
- routed.</li>
-
- <li>A server that refused the connection on the specified
- port.</li>
-
- <li>A server that did not complete the opening handshake
- (e.g. because it was not a WebSocket server).</li>
-
- <li>A WebSocket server that sent a correct opening handshake, but
- that specified options that caused the client to drop the
- connection (e.g. the server specified an origin that differed from
- the script's).</li>
-
- <li>A WebSocket server that abruptly closed the connection after
- successfully completing the opening handshake.</li>
-
- </ul>
-
-
- <h6>Server-initiated closure</h6>
-
- <p>Certain algorithms require or recommend that the server
- <dfn>abort the WebSocket connection</dfn> during the opening
- handshake. To do so, the server must simply <span>close the
- WebSocket connection</span>.</p>
-
-
- <h6>Closure</h6>
-
- <p>To <dfn>close the WebSocket connection</dfn>, the user agent or
- server must close the TCP connection, using whatever mechanism
- possible (e.g. either the TCP RST or FIN mechanisms). When a user
- agent notices that the server has closed its connection, it must
- immediately close its side of the connection also. Whether the user
- agent or the server closes the connection first, it is said that the
- <dfn>WebSocket connection is closed</dfn>. If the connection was
- closed after the client <span title="the WebSocket closing handshake
- has finished">finished the WebSocket closing handshake</span>, then
- the WebSocket connection is said to have been closed <i
- title="">cleanly</i>.</p>
-
- <p>Servers may <span>close the WebSocket connection</span> whenever
- desired. User agents should not <span>close the WebSocket
- connection</span> arbitrarily.</p>
-
-
- <h5>Security considerations</h5>
-
- <p>While this protocol is intended to be used by scripts in Web
- pages, it can also be used directly by hosts. Such hosts are acting
- on their own behalf, and can therefore send fake "Origin" fields,
- misleading the server. Servers should therefore be careful about
- assuming that they are talking directly to scripts from known
- origins, and must consider that they might be accessed in unexpected
- ways. In particular, a server should not trust that any input is
- valid.</p>
-
- <p class="example">For example, if the server uses input as part of
- SQL queries, all input text should be escaped before being passed to
- the SQL server, lest the server be susceptible to SQL injection.</p>
-
- <hr>
-
- <p>Servers that are not intended to process input from any Web page
- but only for certain sites should verify the "Origin" field is an
- origin they expect, and should only respond with the corresponding
- "Sec-WebSocket-Origin" if it is an accepted origin. Servers that
- only accept input from one origin can just send back that value in
- the "Sec-WebSocket-Origin" field, without bothering to check the
- client's value.</p>
-
- <hr>
-
- <p>If at any time a server is faced with data that it does not
- understand, or that violates some criteria by which the server
- determines safety of input, or when the server sees a handshake that
- does not correspond to the values the server is expecting
- (e.g. incorrect path or origin), the server should just
- disconnect. It is always safe to disconnect.</p>
-
- <hr>
-
- <p>The biggest security risk when sending text data using this
- protocol is sending data using the wrong encoding. If an attacker
- can trick the server into sending data encoded as ISO-8859-1
- verbatim (for instance), rather than encoded as UTF-8, then the
- attacker could inject arbitrary frames into the data stream.</p>
-
-
- <h5>IANA considerations</h5>
-
- <h6>Registration of <code title="">ws:</code> scheme</h6>
-
- <p>A <code title="">ws:</code> URL identifies a WebSocket server
- and resource name.</p>
-
- <dl>
-
- <dt>URI scheme name.</dt>
- <dd>ws</dd>
-
- <dt>Status.</dt>
- <dd>Permanent.</dd>
-
- <dt>URI scheme syntax.</dt>
- <dd>
- <p>In ABNF terms using the terminals from the URI specifications:
-<!--END complete--><!--END epub-->
- <a href="#refsRFC5234">[RFC5234]</a>
-<!--START complete--><!--START epub--><!--END websocket-protocol-->
- <a href="#refsABNF">[ABNF]</a>
-<!--START websocket-protocol-->
- <a href="#refsRFC3986">[RFC3986]</a>
- </p>
- <pre>"ws" ":" hier-part [ "?" query ]</pre>
- <p>The path and query components form the resource name sent to
- the server to identify the kind of service desired. Other
- components have the meanings described in RFC3986.</p>
- </dd>
-
- <dt>URI scheme semantics.</dt>
- <dd>The only operation for this scheme is to open a connection
- using the WebSocket protocol.</dd>
-
- <dt>Encoding considerations.</dt>
- <dd>
-
- <p>Characters in the host component that are excluded by the
- syntax defined above must be converted from Unicode to ASCII by
- applying the IDNA ToASCII algorithm to the Unicode host name, with
- both the AllowUnassigned and UseSTD3ASCIIRules flags set, and
- using the result of this algorithm as the host in the URI. <a
- href="#refsRFC3490">[RFC3490]</a></p>
-
- <p>Characters in other components that are excluded by the syntax
- defined above must be converted from Unicode to ASCII by first
- encoding the characters as UTF-8 and then replacing the
- corresponding bytes using their percent-encoded form as defined in
- the URI and IRI specification. <a
- href="#refsRFC3986">[RFC3986]</a> <a
- href="#refsRFC3987">[RFC3987]</a></p>
-
- </dd>
-
- <dt>Applications/protocols that use this URI scheme name.</dt>
- <dd>WebSocket protocol.</dd>
-
- <dt>Interoperability considerations.</dt>
- <dd>None.</dd>
-
- <dt>Security considerations.</dt>
- <dd>See "Security considerations" section above.</dd>
-
- <dt>Contact.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>Author/Change controller.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>References.</dt>
- <dd>This document.</dd>
-
- </dl>
-
-
- <h6>Registration of <code title="">wss:</code> scheme</h6>
-
- <p>A <code title="">wss:</code> URL identifies a WebSocket server
- and resource name, and indicates that traffic over that connection
- is to be encrypted.</p>
-
- <dl>
-
- <dt>URI scheme name.</dt>
- <dd>wss</dd>
-
- <dt>Status.</dt>
- <dd>Permanent.</dd>
-
- <dt>URI scheme syntax.</dt>
- <dd>
- <p>In ABNF terms using the terminals from the URI specifications:
-<!--END complete--><!--END epub-->
- <a href="#refsRFC5234">[RFC5234]</a>
-<!--START complete--><!--START epub--><!--END websocket-protocol-->
- <a href="#refsABNF">[ABNF]</a>
-<!--START websocket-protocol-->
- <a href="#refsRFC3986">[RFC3986]</a></p>
- <pre>"wss" ":" hier-part [ "?" query ]</pre>
- <p>The path and query components form the resource name sent to
- the server to identify the kind of service desired. Other
- components have the meanings described in RFC3986.</p>
- </dd>
-
- <dt>URI scheme semantics.</dt>
- <dd>The only operation for this scheme is to open a connection
- using the WebSocket protocol, encrypted using TLS.</dd>
-
- <dt>Encoding considerations.</dt>
- <dd>
-
- <p>Characters in the host component that are excluded by the
- syntax defined above must be converted from Unicode to ASCII by
- applying the IDNA ToASCII algorithm to the Unicode host name, with
- both the AllowUnassigned and UseSTD3ASCIIRules flags set, and
- using the result of this algorithm as the host in the URI. <a
- href="#refsRFC3490">[RFC3490]</a></p>
-
- <p>Characters in other components that are excluded by the syntax
- defined above must be converted from Unicode to ASCII by first
- encoding the characters as UTF-8 and then replacing the
- corresponding bytes using their percent-encoded form as defined in
- the URI and IRI specification. <a
- href="#refsRFC3986">[RFC3986]</a> <a
- href="#refsRFC3987">[RFC3987]</a></p>
-
- </dd>
-
- <dt>Applications/protocols that use this URI scheme name.</dt>
- <dd>WebSocket protocol over TLS.</dd>
-
- <dt>Interoperability considerations.</dt>
- <dd>None.</dd>
-
- <dt>Security considerations.</dt>
- <dd>See "Security considerations" section above.</dd>
-
- <dt>Contact.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>Author/Change controller.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>References.</dt>
- <dd>This document.</dd>
-
- </dl>
-
-
- <h6>Registration of the "<code title="">WebSocket</code>" HTTP Upgrade keyword</h6>
-
- <dl>
-
- <dt>Name of token.</dt>
- <dd>WebSocket</dd>
-
- <dt>Author/Change controller.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>Contact.</dt>
- <dd>Ian Hickson <ian at hixie.ch></dd>
-
- <dt>References.</dt>
- <dd>This document.</dd>
-
- </dl>
-
-
-
- <h6><dfn title="http-sec-websocket-key1"><code>Sec-WebSocket-Key1</code></dfn> and <dfn title="http-sec-websocket-key2"><code>Sec-WebSocket-Key2</code></dfn></h6>
-
- <p>This section describes two header fields for registration in the
- Permanent Message Header Field Registry. <a
- href="#refsRFC3864">[RFC3864]</a></p>
-
- <dl>
- <dt>Header field name</dt>
- <dd>Sec-WebSocket-Key1</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl>
-
- <dl>
- <dt>Header field name</dt>
- <dd>Sec-WebSocket-Key2</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl>
-
- <p>The <code
- title="http-sec-websocket-key1">Sec-WebSocket-Key1</code> and <code
- title="http-sec-websocket-key2">Sec-WebSocket-Key2</code> headers
- are used in the WebSocket handshake. They are sent from the client
- to the server to provide part of the information used by the server
- to prove that it received a valid WebSocket handshake. This helps
- ensure that the server does not accept connections from
- non-Web-Socket clients (e.g. HTTP clients) that are being abused to
- send data to unsuspecting WebSocket servers.</p>
-
-
- <h6><dfn title="http-sec-websocket-location"><code>Sec-WebSocket-Location</code></dfn></h6>
-
- <p>This section describes a header field for registration in the
- Permanent Message Header Field Registry. <a
- href="#refsRFC3864">[RFC3864]</a></p>
-
- <dl>
- <dt>Header field name</dt>
- <dd>Sec-WebSocket-Location</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl>
-
- <p>The <code
- title="http-sec-websocket-location">Sec-WebSocket-Location</code>
- header is used in the WebSocket handshake. It is sent from the
- server to the client to confirm the <span>URL</span> of the
- connection. This enables the client to verify that the connection
- was established to the right server, port, and path, instead of
- relying on the server to verify that the requested host, port, and
- path are correct.</p>
-
-
- <h6><dfn title="http-sec-websocket-origin"><code>Sec-WebSocket-Origin</code></dfn></h6>
-
- <p>This section describes a header field for registration in the
- Permanent Message Header Field Registry. <a
- href="#refsRFC3864">[RFC3864]</a></p>
-
- <dl>
- <dt>Header field name</dt>
- <dd>Sec-WebSocket-Origin</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl>
-
- <p>The <code
- title="http-sec-websocket-origin">Sec-WebSocket-Origin</code> header
- is used in the WebSocket handshake. It is sent from the server to
- the client to confirm the <span>origin</span> of the script that
- opened the connection. This enables user agents to verify that the
- server is willing to serve the script that opened the
- connection.</p>
-
-
- <h6><dfn title="http-sec-websocket-protocol"><code>Sec-WebSocket-Protocol</code></dfn></h6>
-
- <p>This section describes a header field for registration in the
- Permanent Message Header Field Registry. <a
- href="#refsRFC3864">[RFC3864]</a></p>
-
- <dl>
- <dt>Header field name</dt>
- <dd>Sec-WebSocket-Protocol</dd>
- <dt>Applicable protocol</dt>
- <dd>http</dd>
- <dt>Status</dt>
- <dd>reserved; do not use outside WebSocket handshake</dd>
- <dt>Author/Change controller</dt>
- <dd>IETF</dd>
- <dt>Specification document(s)</dt>
- <dd>
- This document is the relevant specification.
- </dd>
- <dt>Related information</dt>
- <dd>None.</dd>
- </dl>
-
- <p>The <code
- title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>
- header is used in the WebSocket handshake. It is sent from the
- client to the server and back from the server to the client to
- confirm the subprotocol of the connection. This enables scripts to
- both select a subprotocol and be sure that the server agreed to
- serve that subprotocol.</p>
-
-
-
-
- <h5>Using the WebSocket protocol from other specifications</h5>
-
- <p>The WebSocket protocol is intended to be used by another
- specification to provide a generic mechanism for dynamic
- author-defined content, e.g. in a specification defining a scripted
- API.</p>
-
- <p>Such a specification first needs to "<span>establish a WebSocket
- connection</span>", providing that algorithm with:</p>
-
- <ul>
-
- <li>The destination, consisting of a <var title="">host</var> and a
- <var title="">port</var>.</li>
-
- <li>A <var title="">resource name</var>, which allows for multiple
- services to be identified at one host and port.</li>
-
- <li>A <var title="">secure</var> flag, which is true if the
- connection is to be encrypted, and false otherwise.</li>
-
- <li>An <span>ASCII serialization of an origin</span> that is being
- made responsible for the connection. <a
- href="#refsORIGIN">[ORIGIN]</a></li>
-
- <li>Optionally a string identifying a <span>protocol</span> that is
- to be layered over the WebSocket connection.</li>
-
- </ul>
-
- <p>The <var title="">host</var>, <var title="">port</var>, <var
- title="">resource name</var>, and <var title="">secure</var> flag
- are usually obtained from a <span>URL</span> using the steps to
- <span>parse a WebSocket URL's components</span>. These steps fail
- if the URL does not specify a WebSocket.</p>
-
- <p>If a connection can be established, then it is said that the
- "<span>WebSocket connection is established</span>".</p>
-
- <p>If at any time the connection is to be closed, then the
- specification needs to use the "<span>close the WebSocket
- connection</span>" algorithm.</p>
-
- <p>When the connection is closed, for any reason including failure
- to establish the connection in the first place, it is said that the
- "<span>WebSocket connection is closed</span>".</p>
-
- <p>While a connection is open, the specification will need to handle
- the cases when "<span>a WebSocket message has been received</span>"
- with text <var title="">data</var>.</p>
-
- <p>To send some text <var title="">data</var> to an open connection,
- the specification needs to "<span>send <var title="">data</var>
- using the WebSocket</span>".</p>
-
-
- <!--END complete--><!--END epub-->
-
- <h5>Acknowledgements</h5>
-
- <p>The WebSocket protocol is the result of many years of
- development, and as such hundreds of people have contributed to the
- specification during its lifetime. Unfortunately, since the
- specification started as nothing but a minor section of the larger
- WHATWG Web Applications 1.0 specification, and later the HTML5
- specification, no record was kept of who exactly contributed to what
- ended up becoming this specification as opposed to who contributed
- to other parts of that document.</p>
-
- <p>The reader is therefore referred to the Acknowledgements section
- of the WHATWG HTML specification for a full list of all
- contributions that have been made to the source document from which
- this specification is generated. <a href="#refsHTML">[HTML]</a></p>
-
- <!--END websocket-protocol-->
- <!--END websocket-->
-
- <!--START complete--><!--START epub-->
<!--START html-->
- </div><!--data-component-->
-
<div data-component="Web Messaging (editor: Ian Hickson)">
<!--START postmsg-->
@@ -109662,13 +106518,10 @@
<dt id="refsWIN949">[WIN949]</dt>
<dd><cite><a href="http://www.microsoft.com/globaldev/reference/dbcs/949.mspx">Windows Codepage 949</a></cite>. Microsoft.</dd>
- <dt id="refsWSAPI">[WSAPI]</dt>
- <!--
- <dd><cite><a href="http://www.w3.org/TR/websockets/">WebSocket
- API</a></cite>, I. Hickson. W3C.</dd>
- -->
- <dd><cite><a href="http://dev.w3.org/html5/websockets/">WebSocket
- API</a></cite>, I. Hickson. W3C.</dd>
+ <dt id="refsWSP">[WSP]</dt>
+ <dd><cite><a
+ href="http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol">The
+ WebSocket protocol</a></cite>, I. Fette. IETF.</dd>
<dt id="refsX121">[X121]</dt>
<dd><cite>Recommendation X.121 — International Numbering Plan for
More information about the Commit-Watchers
mailing list