idnits 2.17.1 draft-ietf-xmpp-websocket-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 14, 2014) is 3668 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 XMPP Working Group L. Stout, Ed. 3 Internet-Draft &yet 4 Intended status: Standards Track J. Moffitt 5 Expires: September 15, 2014 Mozilla 6 E. Cestari 7 cstar industries 8 March 14, 2014 10 An XMPP Sub-protocol for WebSocket 11 draft-ietf-xmpp-websocket-02 13 Abstract 15 This document defines a binding for the XMPP protocol over a 16 WebSocket transport layer. A WebSocket binding for XMPP provides 17 higher performance than the current HTTP binding for XMPP. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on September 15, 2014. 36 Copyright Notice 38 Copyright (c) 2014 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. XMPP Sub-Protocol . . . . . . . . . . . . . . . . . . . . . . 3 56 3.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3.2. Messages . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.3. XMPP Stream Setup . . . . . . . . . . . . . . . . . . . . 4 59 3.4. Stream Errors . . . . . . . . . . . . . . . . . . . . . . 5 60 3.5. Closing the Connection . . . . . . . . . . . . . . . . . 5 61 3.5.1. see-other-uri . . . . . . . . . . . . . . . . . . . . 6 62 3.6. Stanzas . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 3.7. Stream Restarts . . . . . . . . . . . . . . . . . . . . . 7 64 3.8. Pings and Keepalives . . . . . . . . . . . . . . . . . . 7 65 3.9. Use of TLS . . . . . . . . . . . . . . . . . . . . . . . 8 66 3.10. Stream Management . . . . . . . . . . . . . . . . . . . . 8 67 4. Discovering the WebSocket Connection Method . . . . . . . . . 8 68 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 69 5.1. WebSocket Subprotocol Name . . . . . . . . . . . . . . . 9 70 5.2. URN Sub-Namespace . . . . . . . . . . . . . . . . . . . . 9 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 72 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 73 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 74 7.2. Informative References . . . . . . . . . . . . . . . . . 10 75 Appendix A. XML Schema . . . . . . . . . . . . . . . . . . . . . 11 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 78 1. Introduction 80 Applications using the Extensible Messaging and Presence Protocol 81 (XMPP) (see [RFC6120] and [RFC6121]) on the Web currently make use of 82 BOSH (see [XEP-0124] and [XEP-0206]), an XMPP binding to HTTP. BOSH 83 is based on the HTTP long polling technique, and it suffers from high 84 transport overhead compared to XMPP's native binding to TCP. In 85 addition, there are a number of other known issues with long polling 86 [RFC6202], which have an impact on BOSH-based systems. 88 It would be much better in most circumstances to avoid tunneling XMPP 89 over HTTP long polled connections and instead use the XMPP protocol 90 directly. However, the APIs and sandbox that browsers have provided 91 do not allow this. The WebSocket protocol [RFC6455] exists to solve 92 these kinds of problems. The WebSocket protocol is a bidirectional 93 protocol that provides a simple message-based framing layer over raw 94 sockets and allows for more robust and efficient communication in web 95 applications. 97 The WebSocket protocol enables two-way communication between a client 98 and a server, effectively emulating TCP at the application layer and 99 therefore overcoming many of the problems with existing long-polling 100 techniques for bidirectional HTTP. This document defines a WebSocket 101 sub-protocol for XMPP. 103 2. Terminology 105 The basic unit of framing in the WebSocket protocol is called a 106 message. In XMPP, the basic unit is the stanza, which is a subset of 107 the first-level children of each document in an XMPP stream (see 108 Section 9 of [RFC6120]). XMPP also has a concept of messages, which 109 are stanzas with a top-level element of . In this 110 document, the word "message" will mean a WebSocket message, not an 111 XMPP message stanza, unless otherwise noted. 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in [RFC2119]. 117 3. XMPP Sub-Protocol 119 3.1. Handshake 121 The XMPP sub-protocol is used to transport XMPP over a WebSocket 122 connection. The client and server agree to this protocol during the 123 WebSocket handshake (see Section 1.3 of [RFC6455]). 125 During the WebSocket handshake, the client MUST include the |Sec- 126 WebSocket-Protocol| header in its handshake, and the value |xmpp| 127 MUST be included in the list of protocols. The reply from the server 128 MUST also contain |xmpp| in its own |Sec-WebSocket-Protocol| header 129 in order for an XMPP sub-protocol connection to be established. 131 Once the handshake is complete, WebSocket messages sent or received 132 will conform to the protocol defined in the rest of this document. 134 C: GET /xmpp-websocket HTTP/1.1 135 Host: example.com 136 Upgrade: websocket 137 Connection: Upgrade 138 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 139 Origin: http://example.com 140 ... 141 Sec-WebSocket-Protocol: xmpp 142 Sec-WebSocket-Version: 13 144 S: HTTP/1.1 101 Switching Protocols 145 Upgrade: websocket 146 Connection: Upgrade 147 ... 148 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 149 Sec-WebSocket-Protocol: xmpp 151 [WebSocket connection established] 153 C: 157 3.2. Messages 159 Data frame messages in the XMPP sub-protocol MUST be of the text type 160 and contain UTF-8 encoded data. The close control frame's contents 161 are specified in Section 3.5. Control frames other than close are 162 not restricted. 164 3.3. XMPP Stream Setup 166 The first message sent after the handshake is complete MUST be an 167 element qualified by the "urn:ietf:params:xml:ns:xmpp- 168 framing" namespace. The 'from', 'id', 'to', and 'version' attributes 169 of this element mirror those of the XMPP opening stream tag as 170 defined for the 'http://etherx.jabber.org/streams' namespace in XMPP 171 [RFC6120]. The '<' character of the open tag MUST be the first 172 character of the text payload. 174 The server MUST respond with an element, or a 175 element (see Section 3.5.1). 177 Clients MUST NOT attempt to multiplex XMPP streams for multiple JIDs 178 over the same WebSocket. 180 3.4. Stream Errors 182 Stream level errors in XMPP are terminal. Should such an error 183 occur, the server MUST send the stream error as a complete element in 184 a message to the client. 186 If the error occurs during the opening of a stream, the server MUST 187 send the initial open element response, followed by the stream level 188 error in a second WebSocket message frame. The server MUST then 189 close the connection as specified in Section 3.5. 191 3.5. Closing the Connection 193 Either the server or the client may close the connection at any time. 194 Before closing the connection, the closing party SHOULD close the 195 XMPP stream, if it has been established, by sending a message with 196 the element, qualified by the "urn:ietf:params:xml:ns:xmpp- 197 framing" namespace. The stream is considered closed when a 198 corresponding element is received from the other party. 200 To initiate closing the WebSocket connection, the closing party MUST 201 send a normal WebSocket close message with an empty body. The 202 connection is considered closed when a matching close message is 203 received (see Section 1.4 of [RFC6455]). 205 An example of ending an XMPP over WebSocket session by first closing 206 the XMPP stream layer and then the WebSocket connection layer: 208 Client (XMPP WSS) Server 209 | | | | 210 | | | | 213 | |<------------------------------------------------------------| | 214 | | | | 215 | | (XMPP Stream Closed) | | 216 | +-------------------------------------------------------------+ | 217 | | 218 | WS CLOSE FRAME | 219 |------------------------------------------------------------------>| 220 | WS CLOSE FRAME | 221 |<------------------------------------------------------------------| 222 | | 223 | (Connection Closed) | 224 +-------------------------------------------------------------------+ 226 If a client closes the WebSocket connection without closing the XMPP 227 stream after having enabled stream management (see Section 3.10), the 228 server SHOULD keep the XMPP session alive for a period of time based 229 on server policy, as specified in [XEP-0198]. If the client has not 230 negotiated the use of [XEP-0198], there is no distinction between a 231 stream that was closed as described above and a simple disconnection; 232 the stream is then considered implicitly closed and the XMPP session 233 ended. 235 3.5.1. see-other-uri 237 If the server (or a connection mananger intermediary) wishes to 238 instruct the client to move to a different WebSocket endpoint (e.g. 239 for load balancing purposes), the server MAY send a element 240 and set the "see-other-uri" attribute to the URI of the new WebSocket 241 endpoint. 243 Clients MUST NOT accept suggested endpoints with a lower security 244 context (e.g. moving from a "wss://" endpoint to a "ws://" endpoint). 246 An example of the server closing a stream and instructing the client 247 to connect at a different WebSocket endpoint: 249 S: 252 3.6. Stanzas 254 Every XMPP stanza or other XML element sent directly over the XMPP 255 stream (e.g. ) 256 MUST be sent in its own message. As such, every WebSocket text 257 message that is received MUST be a complete and parsable XML 258 fragment, with all relevant xmlns and xml:lang declarations 259 specified. 261 As it is already mandated that the content of each message is UTF-8 262 encoded, XML text declarations SHOULD NOT be included in messages. 264 Examples of WebSocket messages that contain independently parsable 265 XML fragments (note that for stream features and errors, there is no 266 parent context element providing the "stream" namespace prefix as in 267 [RFC6120], and thus the stream namespace MUST be declared): 269 270 271 273 274 275 277 278 Every WebSocket message is parsable by itself. 279 281 3.7. Stream Restarts 283 After successful SASL authentication, an XMPP stream needs to be 284 restarted. In these cases, as soon as the message is sent (or 285 received) containing the success indication, both the server and 286 client streams are implicitly closed, and new streams need to be 287 opened. The client MUST open a new stream as in Section 3.3 and MUST 288 NOT send a closing element. 290 S: 292 [Streams implicitly closed] 294 C: 298 3.8. Pings and Keepalives 300 XMPP servers often send "whitespace keepalives" (see Section 4.6.1 of 301 [RFC6120]) between stanzas to maintain an XML stream, and XMPP 302 clients can do the same as these extra whitespace characters are not 303 significant in the protocol. Servers and clients SHOULD use 304 WebSocket ping control frames instead for this purpose. 306 In some cases, the WebSocket connection might be served by an 307 intermediary connection manager and not the XMPP server. In these 308 situations, the use of WebSocket ping messages are insufficient to 309 test that the XMPP stream is still alive. Both the XMPP Ping 310 extension [XEP-0199] and the XMPP Stream Management extension 311 [XEP-0198] provide mechanisms to ping the XMPP server, and either 312 extension (or both) MAY be used to determine the state of the 313 connection. 315 3.9. Use of TLS 317 TLS cannot be used at the XMPP sub-protocol layer because the sub- 318 protocol does not allow for raw binary data to be sent. Instead, 319 enabling TLS SHOULD be done at the WebSocket layer using secure 320 WebSocket connections via the |wss| URI scheme. (See Section 10.6 of 321 [RFC6455].) 323 Because TLS is to be provided outside of the XMPP sub-protocol layer, 324 a server MUST NOT advertise TLS as a stream feature (see Section 4.6 325 of [RFC6120]), and a client MUST ignore any advertised TLS stream 326 feature, when using the XMPP sub-protocol. 328 3.10. Stream Management 330 In order to alleviate the problems of temporary disconnections, the 331 XMPP Stream Management extension [XEP-0198] MAY be used to confirm 332 when stanzas have been received by the server. 334 In particular, the use of session resumption in [XEP-0198] MAY be 335 used to allow for recreating the same stream session state after a 336 temporary network unavailability or after navigating to a new URL in 337 a browser. 339 4. Discovering the WebSocket Connection Method 341 Section 3 of [RFC6120] defines a procedure for connecting to an XMPP 342 server, including ways to discover the TCP/IP address and port of the 343 server. When using the WebSocket binding as specified in this 344 document (instead of the TCP binding as specified in [RFC6120]), a 345 client needs an alternative way to discover information about the 346 server's connection methods, since web browsers and other WebSocket- 347 capable software applications typically cannot obtain such 348 information from the Domain Name System. 350 The alternative lookup process uses Web Host Metadata [RFC6415] and 351 Web Linking [RFC5988], where the link relation type is "urn:xmpp:alt- 352 connections:websocket" as described in Discovering Alternate XMPP 353 Connection Methods [XEP-0156]. An example follows. 355 356 358 359 Servers MAY expose discovery information using host-meta documents, 360 and clients MAY use such information to determine the WebSocket 361 endpoint for a server. 363 Use of web-host metadata MAY be used to establish trust between the 364 XMPP server domain and the WebSocket endpoint, particularly in multi- 365 tenant situations where the same WebSocket endpoint is serving 366 multiple XMPP domains. 368 5. IANA Considerations 370 5.1. WebSocket Subprotocol Name 372 This specification requests IANA to register the WebSocket XMPP sub- 373 protocol under the "WebSocket Subprotocol Name" Registry with the 374 following data: 376 Subprotocol Identifier: xmpp 378 Subprotocol Common Name: WebSocket Transport for the Extensible 379 Messaging and Presence Protocol (XMPP) 381 Subprotocol Definition: this document 383 5.2. URN Sub-Namespace 385 A URN sub-namespace for framing of Extensible Messaging and Presence 386 Protocol (XMPP) streams is defined as follows. 388 URI: urn:ietf:params:xml:ns:xmpp-framing 390 Specification: this document 392 Description: This is the XML namespace name for framing of 393 Extensible Messaging and Presence Protocol (XMPP) streams as 394 defined by RFC XXXX. 396 Registrant Contact: IESG 398 6. Security Considerations 400 Since application level TLS cannot be used (see Section 3.9), 401 applications need to protect the privacy of XMPP traffic at the 402 WebSocket or other appropriate layer. 404 Browser based applications are not able to inspect and verify at the 405 application layer the certificate used for the WebSocket connection 406 to ensure that it corresponds to the domain specified as the "to" 407 address of the XMPP stream. For hosts whose domain matches the 408 origin for the WebSocket connection, that check is already performed 409 by the browser. However, in situations where the domain of the XMPP 410 server might not match the origin for the WebSocket endpoint 411 (especially multi-tenant hosting situations), the web host metadata 412 method (see [RFC6415] and [XEP-0156]) MAY be used to delegate trust 413 from the XMPP server domain to the WebSocket origin. 415 When presented with a new WebSocket endpoint via the "see-other-uri" 416 attribute of a element, clients MUST NOT accept the 417 suggestion if the security context of the new endpoint is lower than 418 the current one in order to prevent downgrade attacks from a "wss://" 419 endpoint to "ws://". 421 The Security Considerations for both WebSocket (see Section 10 of 422 [RFC6455] and XMPP (see Section 13 of [RFC6120]) apply to the 423 WebSocket XMPP sub-protocol. 425 7. References 427 7.1. Normative References 429 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 430 Requirement Levels", BCP 14, RFC 2119, March 1997. 432 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 433 Protocol (XMPP): Core", RFC 6120, March 2011. 435 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 436 6455, December 2011. 438 7.2. Informative References 440 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 442 [RFC6121] Saint-Andre, P., "Extensible Messaging and Presence 443 Protocol (XMPP): Instant Messaging and Presence", RFC 444 6121, March 2011. 446 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 447 "Known Issues and Best Practices for the Use of Long 448 Polling and Streaming in Bidirectional HTTP", RFC 6202, 449 April 2011. 451 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 452 6415, October 2011. 454 [XEP-0124] 455 Paterson, I., Smith, D., Saint-Andre, P., Moffitt, J., and 456 L. Stout, "Bidirectional-streams Over Synchronous HTTP 457 (BOSH)", XSF XEP 0124, November 2013. 459 [XEP-0156] 460 Hildebrand, J., Saint-Andre, P., and L. Stout, 461 "Discovering Alternative XMPP Connection Methods", XSF XEP 462 0156, January 2014. 464 [XEP-0198] 465 Karneges, J., Saint-Andre, P., Hildebrand, J., Forno, F., 466 Cridland, D., and M. Wild, "Stream Management", XSF XEP 467 0198, June 2011. 469 [XEP-0199] 470 Saint-Andre, P., "XMPP Ping", XSF XEP 0199, June 2009. 472 [XEP-0206] 473 Paterson, I., Saint-Andre, P., and L. Stout, "XMPP Over 474 BOSH", XSF XEP 0206, November 2013. 476 [XML-SCHEMA] 477 Thompson, H., Maloney, M., Mendelsohn, N., and D. Beech, 478 "XML Schema Part 1: Structures Second Edition", World Wide 479 Web Consortium Recommendation REC-xmlschema-1-20041028, 480 October 2004, 481 . 483 Appendix A. XML Schema 485 The following schema formally defines the 'urn:ietf:params:xml:ns 486 :xmpp-framing' namespace used in this document, in conformance with 487 W3C XML Schema [XML-SCHEMA]. Because validation of XML streams and 488 stanzas is optional, this schema is not normative and is provided for 489 descriptive purposes only. 491 493 499 500 501 502 503 505 507 509 511 513 514 515 516 518 519 520 521 522 524 526 528 530 532 534 535 536 537 539 540 541 542 543 545 547 Authors' Addresses 549 Lance Stout (editor) 550 &yet 552 Email: lance@andyet.net 554 Jack Moffitt 555 Mozilla 557 Email: jack@metajack.im 559 Eric Cestari 560 cstar industries 562 Email: eric@cestari.info