[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

HTTPbis Working Group                                          Y. Hirano
Internet-Draft                                              Google, Inc.
Intended status: Standards Track                       February 14, 2014
Expires: August 18, 2014


                        WebSocket over HTTP/2.0
              draft-hirano-httpbis-websocket-over-http2-00

Abstract

   The WebSocket protocol enables two-way communication between a client
   running untrusted code in a controlled environment to a remote host
   that has opted-in to communications from that code.  Since it
   requires one TCP connection for every WebSocket connection, having
   multiple WebSocket connections between the same client and the same
   server is inefficient.  On the other hand, HTTP/2.0 specifies a fast,
   secure, multiplexed framing protocol.  This document provides bi-
   directional multiplexed communication by layering WebSocket on top of
   HTTP/2.0.

   Please send feedback to the ietf-http-wg@w3.org mailing list.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on August 18, 2014.

Copyright Notice

   Copyright (c) 2014 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of



Hirano                   Expires August 18, 2014                [Page 1]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Document Organization  . . . . . . . . . . . . . . . . . .  3
   2.  Conformance Requirements and Terminology . . . . . . . . . . .  4
   3.  Cross Protocol Negotiation . . . . . . . . . . . . . . . . . .  5
     3.1.  Supported scheme negotiation using SETTINGS frame  . . . .  6
   4.  Opening Handshake  . . . . . . . . . . . . . . . . . . . . . .  8
     4.1.  Handshake Request  . . . . . . . . . . . . . . . . . . . .  8
     4.2.  Handshake Response . . . . . . . . . . . . . . . . . . . .  8
   5.  Data Framing . . . . . . . . . . . . . . . . . . . . . . . . . 10
     5.1.  Overview . . . . . . . . . . . . . . . . . . . . . . . . . 10
     5.2.  Frame representation . . . . . . . . . . . . . . . . . . . 10
       5.2.1.  Tunneling RFC6455 framing (Plan D) . . . . . . . . . . 10
       5.2.2.  Tunneling RFC6455 framing with END_SEGMENT mark
               (Plan A) . . . . . . . . . . . . . . . . . . . . . . . 10
       5.2.3.  HEADERS + DATAs (Plan C) . . . . . . . . . . . . . . . 10
     5.3.  Masking  . . . . . . . . . . . . . . . . . . . . . . . . . 11
   6.  Closing the Connection . . . . . . . . . . . . . . . . . . . . 12
     6.1.  Definitions  . . . . . . . . . . . . . . . . . . . . . . . 12
       6.1.1.  Close the WebSocket Connection . . . . . . . . . . . . 12
       6.1.2.  Start the WebSocket Closing Handshake  . . . . . . . . 12
       6.1.3.  The WebSocket Closing Handshake is Started . . . . . . 12
       6.1.4.  The WebSocket Connection is Closed . . . . . . . . . . 12
       6.1.5.  The WebSocket Connection Close Code  . . . . . . . . . 12
       6.1.6.  The WebSocket Connection Close Reason  . . . . . . . . 12
       6.1.7.  Fail the WebSocket Connection  . . . . . . . . . . . . 13
     6.2.  Abnormal Closures  . . . . . . . . . . . . . . . . . . . . 13
       6.2.1.  Client-Initiated Closure . . . . . . . . . . . . . . . 13
       6.2.2.  Server-initiated closure . . . . . . . . . . . . . . . 13
       6.2.3.  Recovering from Abnormal Closure . . . . . . . . . . . 13
     6.3.  Normal Closure of Connections  . . . . . . . . . . . . . . 13
     6.4.  Status Codes . . . . . . . . . . . . . . . . . . . . . . . 13
   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 14
   8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 15
   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 16
     9.2.  Informative References . . . . . . . . . . . . . . . . . . 16
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 17




Hirano                   Expires August 18, 2014                [Page 2]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


1.  Introduction

   The WebSocket protocol was standardized to enable efficient
   bidirectional messaging mainly for browsers.  However, the core spec
   in RFC 6455 left one problem about scalability unaddressed.  That is
   that one WebSocket connection uses one TCP connection.  Use of
   multiple WebSocket connections provides flexibility for web apps,
   while using more TCP connections leads to more load to the end hosts
   and also to network intermediaries.

   For the HTTP/1.1, there has been effort to multiplex HTTP traffic
   into one TCP connection called HTTP/2.0.  The HTTP/2.0 defines a
   general multiplexed transport on which not only HTTP but other
   messaging application protocol may be layered onto.  We can address
   the scalability issue of WebSocket by using HTTP/2.0 framing's
   multiplexing functionality.

   In this document, we describe how to layer WebSocket semantics onto
   HTTP/2.0 semantics by defining detailed mapping, replacement of
   operations and events defined in RFC 6455.

1.1.  Document Organization

   WebSocket over HTTP/2.0 is a protocol that layers the WebSocket
   protocol over an HTTP/2.0 stream rather than a TCP connection.  This
   document introduces some abstractions and overrides some definitions
   in [RFC6455].  Definitions in [RFC6455] not overridden by this
   document such as Error Handling or Extensions are still valid.

   Section 3 describes how to choose the protocol to use between native
   WebSocket and WebSocket over HTTP/2.0 for each server.  Each of
   Section 4, Section 5 and Section 6 overrides definitions and rules in
   its counterpart in [RFC6455].


















Hirano                   Expires August 18, 2014                [Page 3]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


2.  Conformance Requirements and Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   Requirements phrased in the imperative as part of algorithms (such as
   "strip any leading space characters" or "return false and abort these
   steps") are to be interpreted with the meaning of the key word
   ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm.

   Conformance requirements phrased as algorithms or specific steps can
   be implemented in any manner, so long as the end result is
   equivalent.  In particular, the algorithms defined in this
   specification are intended to be easy to understand and are not
   intended to be performant.

   Native WebSocket means the WebSocket specified in [RFC6455].

   "Frame" has two meanings, WebSocket frame and HTTP/2.0 frame.  When
   it is obvious "WebSocket" and "HTTP/2.0" can be omitted.  For
   example, "DATA frame" means "HTTP/2.0 DATA frame" and "Close frame"
   means "WebSocket Close frame".




























Hirano                   Expires August 18, 2014                [Page 4]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


3.  Cross Protocol Negotiation

   To establish a WebSocket connection, a client needs to decide the
   protocol to use by the following steps.

   1.  If the client has an HTTP/2.0 connection established by previous
       requests and it knows that the connection supports WebSocket over
       HTTP/2.0 by the SETTINGS_SUPPORTED_SCHEMES notification, the
       client SHOULD create a new HTTP/2.0 stream in the existing
       HTTP/2.0 connection and start the opening handshake on it with an
       appropriate scheme.  Both of WebSocket (ws) and secure WebSocket
       (wss) could share the same HTTP/2.0 connection.

   2.  If the client is going to establish a secure WebSocket
       connection, create a WebSocket connection over TLS with
       Application Layer Protocol Negotiation (ALPN) [ALPN draft].  The
       client SHOULD send one or two of the following application
       protocols as ProtocolNameList as specified in [ALPN draft] in any
       order.

       *  "HTTP/1.1[wss]" for the native WebSocket over TLS

       *  "HTTP/2.0[wss]" for secure WebSocket over HTTP/2.0.

       If the server does not support ALPN, the client SHOULD establish
       a TLS connection and start a native WebSocket opening handshake.
       If the server returns "no_application_protocol" alert, the client
       MUST _Fail the WebSocket connection_.  If the server selects
       "HTTP/1.1[wss]" protocol, the client SHOULD establish a TLS
       connection and start a native WebSocket opening handshake.  If
       the server selects "HTTP/2.0[wss]" protocol, the client SHOULD
       create an HTTP/2.0 connection, create an HTTP/2.0 stream on it
       and start the WebSocket opening handshake on the stream with the
       "wss" scheme.

   3.  If the client is going to establish a non-secure WebSocket
       connection, try the native WebSocket protocol negotiation.  If
       the server advertises WebSocket over HTTP/2.0 in its opening
       handshake via an Alternate-Protocol header, the client MAY switch
       its protocol to WebSocket over HTTP/2.0.  Otherwise, the client
       continues to use the native WebSocket protocol.

          EXAMPLE:








Hirano                   Expires August 18, 2014                [Page 5]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


            GET /chat HTTP/1.1
            Host: server.example.com
            Upgrade: websocket
            Connection: Upgrade
            Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
            Sec-WebSocket-Protocol: chat, superchat
            Sec-WebSocket-Version: 13
            Origin: http://example.com

          Then, the server responds as follows:

            HTTP/1.1 101 Switching Protocols
            Upgrade: websocket
            Connection: Upgrade
            Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
            Sec-WebSocket-Protocol: chat
            Alternate-Protocol: 443:http/2[http,ws]

       If the client wants to switch its protocol, the client SHOULD
       send a Close frame with code 1006 and reason like "Switching
       Protocols: 443:http/2;websocket" after the opening handshake,
       then close the WebSocket connection as soon as possible.  These
       transactions MUST be hidden and MUST NOT be notified to upper
       layers like the JavaScript event queue.  Then, the client SHOULD
       reconnect to the advertised server via HTTP/2.0.

3.1.  Supported scheme negotiation using SETTINGS frame

   _THIS SECTION SHOULD BE INTRODUCED IN THE HTTP/2.0 SPEC_.

   By default, a client can send HEADERS frames with schemes advertised
   by the selected ALPN protocol.  A server SHOULD send a SETTINGS frame
   as soon as possible whether it supports other schemes or not.

   EXAMPLE: Imagine a client creates an HTTP/2.0 connection to a server
   which supports both HTTP/2.0 and WebSocket over HTTP/2.0.  Assume
   that the client advertised "http/2" and the server selected it.  Now
   the client knows that the client knows that server supports HTTP/2.0
   with schemes "http" and "https".  The server SHOULD send a SETTINGS
   frame as soon as possible to let the client know that the server
   supports "ws" and "wss" schemes as well.  Once the client receives
   the SETTINGS frame, the client can use the information on the next
   WebSocket protocol selection.

   Here is a proposed ID and value which should be defined in the
   HTTP/2.0 specification.  If the server received a HEADERS with an
   unsupported scheme, the server MUST send an RST_STREAM frame.




Hirano                   Expires August 18, 2014                [Page 6]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


   9 - SETTINGS_SUPPORTED_SCHEMES allows the sender to inform the remote
   endpoint the supported protocol schemes.  The corresponding value
   must be a 32-bit value, and which contains flags as follows:

      bit 0: http

      bit 1: https

      bit 2: ws

      bit 3: wss








































Hirano                   Expires August 18, 2014                [Page 7]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


4.  Opening Handshake

4.1.  Handshake Request

   The client initiates an opening handshake by sending a HEADERS frame.
   The frame MUST NOT set the END_STREAM flag because WebSocket intends
   to establish a bi-directional communication port and to send
   arbitrary data after success in opening handshake.  The HEADERS Name/
   Value section will contain all of the following headers which are
   associated with the WebSocket protocol [RFC6455] opening handshake.
   Upgrade, Connection, Sec-WebSocket-Key, and Sec-WebSocket-Version
   headers MUST NOT be included because we do not have to take care of
   protocol upgrading or verification over HTTP.  The following name/
   value pairs MUST be present in every request:

      ":path": /resource name/ as used in the "Client Requirements"
      section of the WebSocket protocol specification.  (See [RFC6455])

      ":host": /host:port/ (e.g. "www.example.com:1234") as used in the
      "Client Requirements" section of the WebSocket protocol
      specification.  (See [RFC6455])

      ":version": the WebSocket protocol version of this request.  MUST
      be "WebSocket/13" or so.  The number MUST be matched with the Sec-
      WebSocket-Version header.  (See [RFC6455])

      ":scheme": the scheme portion of the URI.  MUST be "ws" or "wss".
      (See also /secure/ flag in [RFC6455])

      ":origin": /origin/ as used in the "Client Requirements" section
      of the WebSocket protocol specification.  (See [RFC6455])

   In addition, the following OPTIONAL name/value pairs MAY be present:

      ":sec-websocket-protocol" - the Sec-WebSocket-Protocol header (See
      [RFC6455])

      ":sec-websocket-extensions" - the Sec-WebSocket-Extensions header
      (See [RFC6455])

   Also, other HTTP compatible header name/value pairs MAY be present.

4.2.  Handshake Response

   The server responds to a client request with a HEADERS frame.  If the
   server intends to allow the client connection, the HEADERS frame MUST
   NOT set the END_STREAM flag and MUST have ":status" containing "101".
   Any status code other than 101 indicates that the WebSocket handshake



Hirano                   Expires August 18, 2014                [Page 8]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


   has not completed and that the semantics of HTTP still apply.  The
   client MAY send some data to the server before receiving the
   successful response.  The server MUST ignore this data when opening
   handshake fails.  After sending successful response, the server can
   send arbitrary data frames at any time.  The response status line is
   unfolded into name/value pairs like other WebSocket handshake headers
   and MUST be present: ":status" - The WebSocket or fallback HTTP
   response status code (e.g. "101" or "101 Switching Protocols".  See
   [RFC6455]).  In addition, the following OPTIONAL name/value pairs MAY
   be present:

      ":sec-websocket-protocol" - the Sec-WebSocket-Protocol header (See
      [RFC6455])

      ":sec-websocket-extensions" - the Sec-WebSocket-Extensions header
      (See [RFC6455])

   Also, other HTTP compatible header name/value pairs MAY be present.
   All header names MUST be lowercase.  The successful server response
   MUST have ":status" containing "101".































Hirano                   Expires August 18, 2014                [Page 9]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


5.  Data Framing

5.1.  Overview

   [RFC6455] states that data is transmitted using a sequence of
   WebSocket frames.  This protocol follows that abstraction.  This
   section corresponds to "5.  Data Framing" section in [RFC6455] and
   specifies the following things:

   o  The representation of a WebSocket frame.

   o  The masking mechanism.

   Other things such as fragmentation and control frames remain
   unchanged.

5.2.  Frame representation

   Several representations are proposed.  In each representation, an
   endpoint MUST set END_STREAM flag at the last HTTP/2.0 frame it sends
   on the WebSocket connection.

5.2.1.  Tunneling RFC6455 framing (Plan D)

   The WebSocket frame byte representation is embedded in payload in
   HTTP/2.0 DATA frame.  DATA frames can be re-framed, i.e.  One
   WebSocket frame can be split over multiple DATA frames and one DATA
   frames can contain multiple WebSocket frames.

5.2.2.  Tunneling RFC6455 framing with END_SEGMENT mark (Plan A)

   This plan is almost same as Plan D, but it uses END_SEGMENT flag in a
   DATA frame to make intermediaries enable to flush data appropriately
   without understanding the embedded WebSocket framing.

   An endpoint MUST set END_SEGMENT on an HTTP/2.0 DATA frame containing
   the end of a WebSocket frame with FIN flag set.

5.2.3.  HEADERS + DATAs (Plan C)

   In this plan, an HTTP/2.0 HEADERS frame and subsequent multiple DATA
   frames represent a WebSocket frame.  END_SEGMENT flag MUST be set at
   the last HTTP/2.0 DATA frame for each WebSocket frame.  That is,
   WebSocket over HTTP/2.0 defines _segment_ in [HTTP/2.0 draft] as
   _WebSocket frame_.  The WebSocket frame headers are stored in the
   HEADERS frame in the following manner.





Hirano                   Expires August 18, 2014               [Page 10]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


   o  The ":fin" header field

         If the FIN WebSocket frame header is set, the HEADERS frame
         MUST contain this field with value of "1".  Otherwise the
         HEADERS frame MUST NOT contain this field.

   o  The ":rsv1" header field

         If the RSV1 WebSocket frame header is set, the HEADERS frame
         MUST contain this field with value of "1".  Otherwise the
         HEADERS frame MUST NOT contain this field.

   o  The ":rsv2" header field

         If the RSV2 WebSocket frame header is set, the HEADERS frame
         MUST contain this field with value of "1".  Otherwise the
         HEADERS frame MUST NOT contain this field.

   o  The ":rsv3" header field

         If the RSV3 WebSocket frame header is set, the HEADERS frame
         MUST contain this field with value of "1".  Otherwise the
         HEADERS frame MUST NOT contain this field.

   o  The ":length" header field

         The HEADERS frame MUST contain this field with the hexadecimal
         text representation of the payload length represented by
         "Payload len" WebSocket header field and "Extended payload
         length" WebSocket header field" if present, without leading
         zeros.

5.3.  Masking

   [RFC6455] defines the masking mechanism which masks WebSocket frame
   data payload with a random masking-key.  On WebSocket over HTTP/2.0,
   masking mechanism MUST be disabled.














Hirano                   Expires August 18, 2014               [Page 11]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


6.  Closing the Connection

   Some definitions in [RFC6455] are overridden in this section.

6.1.  Definitions

6.1.1.  Close the WebSocket Connection

   To _Close the WebSocket Connection_, an endpoint closes the
   underlying HTTP/2.0 stream.  If the stream is already closed, the
   endpoint MUST do nothing.  Otherwise, the endpoint MUST send an
   RST_STREAM frame with an appropriate error code.

6.1.2.  Start the WebSocket Closing Handshake

   To _Start the WebSocket Closing Handshake_ with a status code
   (Section 6.4) /code/ and an optional close reason (Section 6.1.6)
   /reason/, an endpoint MUST send a Close control frame, as described
   in [RFC6455] whose status code is set to /code/ and whose close
   reason is set to /reason/.  The last HTTP/2.0 frame of the WebSocket
   Close control frame MUST turn END_STREAM flag on.

6.1.3.  The WebSocket Closing Handshake is Started

   Same as Section 7.1.3 in [RFC6455].

6.1.4.  The WebSocket Connection is Closed

   When the underlying HTTP stream is closed, it is said that _The
   WebSocket Connection is Closed_ and that the WebSocket connection is
   in the CLOSED state.  If the stream was closed after the WebSocket
   closing handshake was completed, the WebSocket connection is said to
   have been closed _cleanly_.

   If the WebSocket connection could not be established, it is also said
   that _The WebSocket Connection is Closed_, but not cleanly.

6.1.5.  The WebSocket Connection Close Code

   Same as Section 7.1.5 in [RFC6455].

6.1.6.  The WebSocket Connection Close Reason

   Same as Section 7.1.6 in [RFC6455].







Hirano                   Expires August 18, 2014               [Page 12]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


6.1.7.  Fail the WebSocket Connection

   Same as Section 7.1.7 in [RFC6455].

6.2.  Abnormal Closures

6.2.1.  Client-Initiated Closure

   If at any point the underlying HTTP/2.0 stream is unexpectedly
   terminated, the client MUST _Fail the WebSocket Connection_.

   Except as indicated above or as specified by the application layer
   (e.g. a script using the WebSocket API), clients SHOULD NOT close the
   connection.

6.2.2.  Server-initiated closure

   Same as Section 7.2.2 in [RFC6455].

6.2.3.  Recovering from Abnormal Closure

   Same as Section 7.2.3 in [RFC6455].

6.3.  Normal Closure of Connections

   Same as Section 7.3 in [RFC6455].

6.4.  Status Codes

   Same as Section 7.4 in [RFC6455].





















Hirano                   Expires August 18, 2014               [Page 13]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


7.  Security Considerations

   [RFC6455] frame has the masking mechanism for two purposes.

   o  To prevent a misbehavior of transparent proxies.

   o  To prevent TLS side-channel attacks such as [BEAST].

   These should be addressed at the HTTP/2.0 framing layer and WebSocket
   over HTTP/2.0 has no masking mechanism.









































Hirano                   Expires August 18, 2014               [Page 14]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


8.  IANA Considerations


















































Hirano                   Expires August 18, 2014               [Page 15]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


9.  References

9.1.  Normative References

   [RFC6455]  Fette, I. and A. Melnikov, "The WebSocket Protocol",
              RFC 6455, December 2011.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [HTTP/2.0 draft]
              Belshe, M., Peon, R., Thomson, M., and A. Melnikov,
              "Hypertext Transfer Protocol version 2.0", September 2012.

   [ALPN draft]
              Friedl, S., Popov, A., Langley, A., and E. Stephan,
              "Transport Layer Security (TLS) Application Layer Protocol
              Negotiation Extension", January 2014.

9.2.  Informative References

   [BEAST]    Duong, T. and J. Rizzo, "The BEAST attack".





























Hirano                   Expires August 18, 2014               [Page 16]

Internet-Draft           WebSocket over HTTP/2.0           February 2014


Author's Address

   Yutaka Hirano
   Google, Inc.

   Email: yhirano@google.com













































Hirano                   Expires August 18, 2014               [Page 17]


Html markup produced by rfcmarkup 1.108, available from http://tools.ietf.org/tools/rfcmarkup/