11. IANA Considerations
11.1. Registration of New URI Schemes
11.1.1. Registration of "ws" Scheme
A |ws| URI identifies a WebSocket server and resource name. URI scheme name ws Status Permanent URI scheme syntax Using the ABNF [RFC5234] syntax and ABNF terminals from the URI specification [RFC3986]: "ws:" "//" authority path-abempty [ "?" query ] The <path-abempty> and <query> [RFC3986] components form the resource name sent to the server to identify the kind of service desired. Other components have the meanings described in [RFC3986]. URI scheme semantics The only operation for this scheme is to open a connection using the WebSocket Protocol. Encoding considerations Characters in the host component that are excluded by the syntax defined above MUST be converted from Unicode to ASCII as specified in [RFC3987] or its replacement. For the purposes of scheme-based normalization, Internationalized Domain Name (IDN) forms of the host component and their conversions to punycode are considered equivalent (see Section 5.3.3 of [RFC3987]).
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 [RFC3986] and Internationalized Resource Identifier (IRI) [RFC3987] specifications. Applications/protocols that use this URI scheme name WebSocket Protocol Interoperability considerations Use of WebSocket requires use of HTTP version 1.1 or higher. Security considerations See "Security Considerations" section. Contact HYBI WG <hybi@ietf.org> Author/Change controller IETF <iesg@ietf.org> References RFC 645511.1.2. Registration of "wss" Scheme
A |wss| URI identifies a WebSocket server and resource name and indicates that traffic over that connection is to be protected via TLS (including standard benefits of TLS such as data confidentiality and integrity and endpoint authentication). URI scheme name wss Status Permanent URI scheme syntax Using the ABNF [RFC5234] syntax and ABNF terminals from the URI specification [RFC3986]: "wss:" "//" authority path-abempty [ "?" query ] The <path-abempty> 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].
URI scheme semantics The only operation for this scheme is to open a connection using the WebSocket Protocol, encrypted using TLS. Encoding considerations Characters in the host component that are excluded by the syntax defined above MUST be converted from Unicode to ASCII as specified in [RFC3987] or its replacement. For the purposes of scheme-based normalization IDN forms of the host component and their conversions to punycode are considered equivalent (see Section 5.3.3 of [RFC3987]). 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 [RFC3986] and IRI [RFC3987] specifications. Applications/protocols that use this URI scheme name WebSocket Protocol over TLS Interoperability considerations Use of WebSocket requires use of HTTP version 1.1 or higher. Security considerations See "Security Considerations" section. Contact HYBI WG <hybi@ietf.org> Author/Change controller IETF <iesg@ietf.org> References RFC 645511.2. Registration of the "WebSocket" HTTP Upgrade Keyword
This section defines a keyword registered in the HTTP Upgrade Tokens Registry as per RFC 2817 [RFC2817]. Name of token WebSocket Author/Change controller IETF <iesg@ietf.org>
Contact HYBI <hybi@ietf.org> References RFC 645511.3. Registration of New HTTP Header Fields
11.3.1. Sec-WebSocket-Key
This section describes a header field registered in the Permanent Message Header Field Names registry [RFC3864]. Header field name Sec-WebSocket-Key Applicable protocol http Status standard Author/Change controller IETF Specification document(s) RFC 6455 Related information This header field is only used for WebSocket opening handshake. The |Sec-WebSocket-Key| header field is used in the WebSocket opening handshake. It is 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 opening handshake. This helps ensure that the server does not accept connections from non-WebSocket clients (e.g., HTTP clients) that are being abused to send data to unsuspecting WebSocket servers. The |Sec-WebSocket-Key| header field MUST NOT appear more than once in an HTTP request.
11.3.2. Sec-WebSocket-Extensions
This section describes a header field for registration in the Permanent Message Header Field Names registry [RFC3864]. Header field name Sec-WebSocket-Extensions Applicable protocol http Status standard Author/Change controller IETF Specification document(s) RFC 6455 Related information This header field is only used for WebSocket opening handshake. The |Sec-WebSocket-Extensions| header field is used in the WebSocket opening handshake. It is initially sent from the client to the server, and then subsequently sent from the server to the client, to agree on a set of protocol-level extensions to use for the duration of the connection. The |Sec-WebSocket-Extensions| header field MAY appear multiple times in an HTTP request (which is logically the same as a single |Sec-WebSocket-Extensions| header field that contains all values. However, the |Sec-WebSocket-Extensions| header field MUST NOT appear more than once in an HTTP response.11.3.3. Sec-WebSocket-Accept
This section describes a header field registered in the Permanent Message Header Field Names registry [RFC3864]. Header field name Sec-WebSocket-Accept Applicable protocol http Status standard
Author/Change controller IETF Specification document(s) RFC 6455 Related information This header field is only used for the WebSocket opening handshake. The |Sec-WebSocket-Accept| header field is used in the WebSocket opening handshake. It is sent from the server to the client to confirm that the server is willing to initiate the WebSocket connection. The |Sec-WebSocket-Accept| header MUST NOT appear more than once in an HTTP response.11.3.4. Sec-WebSocket-Protocol
This section describes a header field registered in the Permanent Message Header Field Names registry [RFC3864]. Header field name Sec-WebSocket-Protocol Applicable protocol http Status standard Author/Change controller IETF Specification document(s) RFC 6455 Related information This header field is only used for the WebSocket opening handshake. The |Sec-WebSocket-Protocol| header field is used in the WebSocket opening 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.
The |Sec-WebSocket-Protocol| header field MAY appear multiple times in an HTTP request (which is logically the same as a single |Sec-WebSocket-Protocol| header field that contains all values). However, the |Sec-WebSocket-Protocol| header field MUST NOT appear more than once in an HTTP response.11.3.5. Sec-WebSocket-Version
This section describes a header field registered in the Permanent Message Header Field Names registry [RFC3864]. Header field name Sec-WebSocket-Version Applicable protocol http Status standard Author/Change controller IETF Specification document(s) RFC 6455 Related information This header field is only used for the WebSocket opening handshake. The |Sec-WebSocket-Version| header field is used in the WebSocket opening handshake. It is sent from the client to the server to indicate the protocol version of the connection. This enables servers to correctly interpret the opening handshake and subsequent data being sent from the data, and close the connection if the server cannot interpret that data in a safe manner. The |Sec-WebSocket- Version| header field is also sent from the server to the client on WebSocket handshake error, when the version received from the client does not match a version understood by the server. In such a case, the header field includes the protocol version(s) supported by the server. Note that there is no expectation that higher version numbers are necessarily backward compatible with lower version numbers.
The |Sec-WebSocket-Version| header field MAY appear multiple times in an HTTP response (which is logically the same as a single |Sec-WebSocket-Version| header field that contains all values). However, the |Sec-WebSocket-Version| header field MUST NOT appear more than once in an HTTP request.11.4. WebSocket Extension Name Registry
This specification creates a new IANA registry for WebSocket Extension names to be used with the WebSocket Protocol in accordance with the principles set out in RFC 5226 [RFC5226]. As part of this registry, IANA maintains the following information: Extension Identifier The identifier of the extension, as will be used in the |Sec-WebSocket-Extensions| header field registered in Section 11.3.2 of this specification. The value must conform to the requirements for an extension-token as defined in Section 9.1 of this specification. Extension Common Name The name of the extension, as the extension is generally referred to. Extension Definition A reference to the document in which the extension being used with the WebSocket Protocol is defined. Known Incompatible Extensions A list of extension identifiers with which this extension is known to be incompatible. WebSocket Extension names are to be subject to the "First Come First Served" IANA registration policy [RFC5226]. There are no initial values in this registry.11.5. WebSocket Subprotocol Name Registry
This specification creates a new IANA registry for WebSocket Subprotocol names to be used with the WebSocket Protocol in accordance with the principles set out in RFC 5226 [RFC5226].
As part of this registry, IANA maintains the following information: Subprotocol Identifier The identifier of the subprotocol, as will be used in the |Sec-WebSocket-Protocol| header field registered in Section 11.3.4 of this specification. The value must conform to the requirements given in item 10 of Section 4.1 of this specification -- namely, the value must be a token as defined by RFC 2616 [RFC2616]. Subprotocol Common Name The name of the subprotocol, as the subprotocol is generally referred to. Subprotocol Definition A reference to the document in which the subprotocol being used with the WebSocket Protocol is defined. WebSocket Subprotocol names are to be subject to the "First Come First Served" IANA registration policy [RFC5226].11.6. WebSocket Version Number Registry
This specification creates a new IANA registry for WebSocket Version Numbers to be used with the WebSocket Protocol in accordance with the principles set out in RFC 5226 [RFC5226]. As part of this registry, IANA maintains the following information: Version Number The version number to be used in the |Sec-WebSocket-Version| is specified in Section 4.1 of this specification. The value must be a non-negative integer in the range between 0 and 255 (inclusive). Reference The RFC requesting a new version number or a draft name with version number (see below). Status Either "Interim" or "Standard". See below for description. A version number is designated as either "Interim" or "Standard". A "Standard" version number is documented in an RFC and used to identify a major, stable version of the WebSocket protocol, such as the version defined by this RFC. "Standard" version numbers are subject to the "IETF Review" IANA registration policy [RFC5226].
An "Interim" version number is documented in an Internet-Draft and used to help implementors identify and interoperate with deployed versions of the WebSocket protocol, such as versions developed before the publication of this RFC. "Interim" version numbers are subject to the "Expert Review" IANA registration policy [RFC5226], with the chairs of the HYBI Working Group (or, if the working group closes, the Area Directors for the IETF Applications Area) being the initial Designated Experts. IANA has added initial values to the registry as follows. +--------+-----------------------------------------+----------+ |Version | Reference | Status | | Number | | | +--------+-----------------------------------------+----------+ | 0 + draft-ietf-hybi-thewebsocketprotocol-00 | Interim | +--------+-----------------------------------------+----------+ | 1 + draft-ietf-hybi-thewebsocketprotocol-01 | Interim | +--------+-----------------------------------------+----------+ | 2 + draft-ietf-hybi-thewebsocketprotocol-02 | Interim | +--------+-----------------------------------------+----------+ | 3 + draft-ietf-hybi-thewebsocketprotocol-03 | Interim | +--------+-----------------------------------------+----------+ | 4 + draft-ietf-hybi-thewebsocketprotocol-04 | Interim | +--------+-----------------------------------------+----------+ | 5 + draft-ietf-hybi-thewebsocketprotocol-05 | Interim | +--------+-----------------------------------------+----------+ | 6 + draft-ietf-hybi-thewebsocketprotocol-06 | Interim | +--------+-----------------------------------------+----------+ | 7 + draft-ietf-hybi-thewebsocketprotocol-07 | Interim | +--------+-----------------------------------------+----------+ | 8 + draft-ietf-hybi-thewebsocketprotocol-08 | Interim | +--------+-----------------------------------------+----------+ | 9 + Reserved | | +--------+-----------------------------------------+----------+ | 10 + Reserved | | +--------+-----------------------------------------+----------+ | 11 + Reserved | | +--------+-----------------------------------------+----------+ | 12 + Reserved | | +--------+-----------------------------------------+----------+ | 13 + RFC 6455 | Standard | +--------+-----------------------------------------+----------+
11.7. WebSocket Close Code Number Registry
This specification creates a new IANA registry for WebSocket Connection Close Code Numbers in accordance with the principles set out in RFC 5226 [RFC5226]. As part of this registry, IANA maintains the following information: Status Code The Status Code denotes a reason for a WebSocket connection closure as per Section 7.4 of this document. The status code is an integer number between 1000 and 4999 (inclusive). Meaning The meaning of the status code. Each status code has to have a unique meaning. Contact A contact for the entity reserving the status code. Reference The stable document requesting the status codes and defining their meaning. This is required for status codes in the range 1000-2999 and recommended for status codes in the range 3000-3999. WebSocket Close Code Numbers are subject to different registration requirements depending on their range. Requests for status codes for use by this protocol and its subsequent versions or extensions are subject to any one of the "Standards Action", "Specification Required" (which implies "Designated Expert"), or "IESG Review" IANA registration policies and should be granted in the range 1000-2999. Requests for status codes for use by libraries, frameworks, and applications are subject to the "First Come First Served" IANA registration policy and should be granted in the range 3000-3999. The range of status codes from 4000-4999 is designated for Private Use. Requests should indicate whether they are requesting status codes for use by the WebSocket Protocol (or a future version of the protocol), by extensions, or by libraries/frameworks/applications.
IANA has added initial values to the registry as follows. |Status Code | Meaning | Contact | Reference | -+------------+-----------------+---------------+-----------| | 1000 | Normal Closure | hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1001 | Going Away | hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1002 | Protocol error | hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1003 | Unsupported Data| hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1004 | ---Reserved---- | hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1005 | No Status Rcvd | hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1006 | Abnormal Closure| hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1007 | Invalid frame | hybi@ietf.org | RFC 6455 | | | payload data | | | -+------------+-----------------+---------------+-----------| | 1008 | Policy Violation| hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1009 | Message Too Big | hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1010 | Mandatory Ext. | hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------| | 1011 | Internal Server | hybi@ietf.org | RFC 6455 | | | Error | | | -+------------+-----------------+---------------+-----------| | 1015 | TLS handshake | hybi@ietf.org | RFC 6455 | -+------------+-----------------+---------------+-----------|11.8. WebSocket Opcode Registry
This specification creates a new IANA registry for WebSocket Opcodes in accordance with the principles set out in RFC 5226 [RFC5226]. As part of this registry, IANA maintains the following information: Opcode The opcode denotes the frame type of the WebSocket frame, as defined in Section 5.2. The opcode is an integer number between 0 and 15, inclusive. Meaning The meaning of the opcode value.
Reference The specification requesting the opcode. WebSocket Opcode numbers are subject to the "Standards Action" IANA registration policy [RFC5226]. IANA has added initial values to the registry as follows. |Opcode | Meaning | Reference | -+--------+-------------------------------------+-----------| | 0 | Continuation Frame | RFC 6455 | -+--------+-------------------------------------+-----------| | 1 | Text Frame | RFC 6455 | -+--------+-------------------------------------+-----------| | 2 | Binary Frame | RFC 6455 | -+--------+-------------------------------------+-----------| | 8 | Connection Close Frame | RFC 6455 | -+--------+-------------------------------------+-----------| | 9 | Ping Frame | RFC 6455 | -+--------+-------------------------------------+-----------| | 10 | Pong Frame | RFC 6455 | -+--------+-------------------------------------+-----------|11.9. WebSocket Framing Header Bits Registry
This specification creates a new IANA registry for WebSocket Framing Header Bits in accordance with the principles set out in RFC 5226 [RFC5226]. This registry controls assignment of the bits marked RSV1, RSV2, and RSV3 in Section 5.2. These bits are reserved for future versions or extensions of this specification. WebSocket Framing Header Bits assignments are subject to the "Standards Action" IANA registration policy [RFC5226].12. Using the WebSocket Protocol from Other Specifications
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. Such a specification first needs to _Establish a WebSocket Connection_, providing that algorithm with: o The destination, consisting of a /host/ and a /port/.
o A /resource name/, which allows for multiple services to be identified at one host and port. o A /secure/ flag, which is true if the connection is to be encrypted and false otherwise. o An ASCII serialization of an origin [RFC6454] that is being made responsible for the connection. o Optionally, a string identifying a protocol that is to be layered over the WebSocket connection. The /host/, /port/, /resource name/, and /secure/ flag are usually obtained from a URI using the steps to parse a WebSocket URI's components. These steps fail if the URI does not specify a WebSocket. If at any time the connection is to be closed, then the specification needs to use the _Close the WebSocket Connection_ algorithm (Section 7.1.1). Section 7.1.4 defines when _The WebSocket Connection is Closed_. While a connection is open, the specification will need to handle the cases when _A WebSocket Message Has Been Received_ (Section 6.2). To send some data /data/ to an open connection, the specification needs to _Send a WebSocket Message_ (Section 6.1).13. Acknowledgements
Special thanks are due to Ian Hickson, who was the original author and editor of this protocol. The initial design of this specification benefitted from the participation of many people in the WHATWG and WHATWG mailing list. Contributions to that specification are not tracked by section, but a list of all who contributed to that specification is given in the WHATWG HTML specification at http://whatwg.org/html5. Special thanks also to John Tamplin for providing a significant amount of text for the "Data Framing" section of this specification. Special thanks also to Adam Barth for providing a significant amount of text and background research for the "Data Masking" section of this specification.
Special thanks to Lisa Dusseault for the Apps Area review (and for helping to start this work), Richard Barnes for the Gen-Art review, and Magnus Westerlund for the Transport Area Review. Special thanks to HYBI WG past and present WG chairs who tirelessly worked behind the scene to move this work toward completion: Joe Hildebrand, Salvatore Loreto, and Gabriel Montenegro. And last but not least, special thank you to the responsible Area Director Peter Saint-Andre. Thank you to the following people who participated in discussions on the HYBI WG mailing list and contributed ideas and/or provided detailed reviews (the list is likely to be incomplete): Greg Wilkins, John Tamplin, Willy Tarreau, Maciej Stachowiak, Jamie Lokier, Scott Ferguson, Bjoern Hoehrmann, Julian Reschke, Dave Cridland, Andy Green, Eric Rescorla, Inaki Baz Castillo, Martin Thomson, Roberto Peon, Patrick McManus, Zhong Yu, Bruce Atherton, Takeshi Yoshino, Martin J. Duerst, James Graham, Simon Pieters, Roy T. Fielding, Mykyta Yevstifeyev, Len Holgate, Paul Colomiets, Piotr Kulaga, Brian Raymor, Jan Koehler, Joonas Lehtolahti, Sylvain Hellegouarch, Stephen Farrell, Sean Turner, Pete Resnick, Peter Thorson, Joe Mason, John Fallows, and Alexander Philippou. Note that people listed above didn't necessarily endorse the end result of this work.14. References
14.1. Normative References
[ANSI.X3-4.1986] American National Standards Institute, "Coded Character Set - 7-bit American Standard Code for Information Interchange", ANSI X3.4, 1986. [FIPS.180-3] National Institute of Standards and Technology, "Secure Hash Standard", FIPS PUB 180-3, October 2008, <http://csrc.nist.gov/publications/fips/fips180-3/ fips180-3_final.pdf>. [RFC1928] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and L. Jones, "SOCKS Protocol Version 5", RFC 1928, March 1996. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", RFC 2817, May 2000. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, September 2004. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005. [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness Requirements for Security", BCP 106, RFC 4086, June 2005. [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: Extension Definitions", RFC 6066, January 2011. [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, December 2011.14.2. Informative References
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, July 2005.
[RFC4270] Hoffman, P. and B. Schneier, "Attacks on Cryptographic Hashes in Internet Protocols", RFC 4270, November 2005. [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, October 2008. [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, "Known Issues and Best Practices for the Use of Long Polling and Streaming in Bidirectional HTTP", RFC 6202, April 2011. [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, April 2011. [TALKING] Huang, L-S., Chen, E., Barth, A., Rescorla, E., and C. Jackson, "Talking to Yourself for Fun and Profit", 2010, <http://w2spconf.com/2011/papers/websocket.pdf>. [W3C.REC-wsc-ui-20100812] Roessler, T. and A. Saldhana, "Web Security Context: User Interface Guidelines", World Wide Web Consortium Recommendation REC-wsc-ui-20100812, August 2010, <http://www.w3.org/TR/2010/REC-wsc-ui-20100812/>. Latest version available at <http://www.w3.org/TR/wsc-ui/>. [WSAPI] Hickson, I., "The WebSocket API", W3C Working Draft WD- websockets-20110929, September 2011, <http://www.w3.org/TR/2011/WD-websockets-20110929/>. Latest version available at <http://www.w3.org/TR/websockets/>. [XMLHttpRequest] van Kesteren, A., Ed., "XMLHttpRequest", W3C Candidate Recommendation CR-XMLHttpRequest-20100803, August 2010, <http://www.w3.org/TR/2010/CR-XMLHttpRequest-20100803/>. Latest version available at <http://www.w3.org/TR/XMLHttpRequest/>.
Authors' Addresses
Ian Fette Google, Inc. EMail: ifette+ietf@google.com URI: http://www.ianfette.com/ Alexey Melnikov Isode Ltd. 5 Castle Business Village 36 Station Road Hampton, Middlesex TW12 2BX UK EMail: Alexey.Melnikov@isode.com