idnits 2.17.1 draft-ietf-xmpp-websocket-03.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 (April 19, 2014) is 3631 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: October 21, 2014 Mozilla 6 E. Cestari 7 cstar industries 8 April 19, 2014 10 An XMPP Sub-protocol for WebSocket 11 draft-ietf-xmpp-websocket-03 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 October 21, 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. WebSocket Messages . . . . . . . . . . . . . . . . . . . 4 58 3.3. XMPP Framing . . . . . . . . . . . . . . . . . . . . . . 4 59 3.3.1. Framed XML Stream . . . . . . . . . . . . . . . . . . 4 60 3.3.2. Framed Stream Namespace . . . . . . . . . . . . . . . 5 61 3.3.3. Stream Frames . . . . . . . . . . . . . . . . . . . . 5 62 3.4. Stream Initiation . . . . . . . . . . . . . . . . . . . . 6 63 3.5. Stream Errors . . . . . . . . . . . . . . . . . . . . . . 6 64 3.6. Closing the Connection . . . . . . . . . . . . . . . . . 6 65 3.6.1. see-other-uri . . . . . . . . . . . . . . . . . . . . 7 66 3.7. Stream Restarts . . . . . . . . . . . . . . . . . . . . . 8 67 3.8. Pings and Keepalives . . . . . . . . . . . . . . . . . . 8 68 3.9. Use of TLS . . . . . . . . . . . . . . . . . . . . . . . 8 69 3.10. Stream Management . . . . . . . . . . . . . . . . . . . . 9 70 4. Discovering the WebSocket Connection Method . . . . . . . . . 9 71 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 72 5.1. WebSocket Subprotocol Name . . . . . . . . . . . . . . . 9 73 5.2. URN Sub-Namespace . . . . . . . . . . . . . . . . . . . . 10 74 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 75 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 76 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 77 7.2. Informative References . . . . . . . . . . . . . . . . . 11 78 Appendix A. XML Schema . . . . . . . . . . . . . . . . . . . . . 12 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 81 1. Introduction 83 Applications using the Extensible Messaging and Presence Protocol 84 (XMPP) (see [RFC6120] and [RFC6121]) on the Web currently make use of 85 BOSH (see [XEP-0124] and [XEP-0206]), an XMPP binding to HTTP. BOSH 86 is based on the HTTP long polling technique, and it suffers from high 87 transport overhead compared to XMPP's native binding to TCP. In 88 addition, there are a number of other known issues with long polling 89 [RFC6202], which have an impact on BOSH-based systems. 91 It would be much better in most circumstances to avoid tunneling XMPP 92 over HTTP long polled connections and instead use the XMPP protocol 93 directly. However, the APIs and sandbox that browsers have provided 94 do not allow this. The WebSocket protocol [RFC6455] exists to solve 95 these kinds of problems and is a bidirectional protocol that provides 96 a simple message-based framing layer over raw sockets, allowing for 97 more robust and efficient communication in web applications. 99 The WebSocket protocol enables two-way communication between a client 100 and a server, effectively emulating TCP at the application layer and 101 therefore overcoming many of the problems with existing long-polling 102 techniques for bidirectional HTTP. This document defines a WebSocket 103 sub-protocol for XMPP. 105 2. Terminology 107 The basic unit of framing in the WebSocket protocol is called a 108 message. In XMPP, the basic unit is the stanza, which is a subset of 109 the first-level children of each document in an XMPP stream (see 110 Section 9 of [RFC6120]). XMPP also has a concept of messages, which 111 are stanzas with a top-level element of . In this 112 document, the word "message" will mean a WebSocket message, not an 113 XMPP message stanza, unless otherwise noted. 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 117 "OPTIONAL" in this document are to be interpreted as described in 118 [RFC2119]. 120 3. XMPP Sub-Protocol 122 3.1. Handshake 124 The XMPP sub-protocol is used to transport XMPP over a WebSocket 125 connection. The client and server agree to this protocol during the 126 WebSocket handshake (see Section 1.3 of [RFC6455]). 128 During the WebSocket handshake, the client MUST include the |Sec- 129 WebSocket-Protocol| header in its handshake, and the value |xmpp| 130 MUST be included in the list of protocols. The reply from the server 131 MUST also contain |xmpp| in its own |Sec-WebSocket-Protocol| header 132 in order for an XMPP sub-protocol connection to be established. 134 Once the handshake is complete, WebSocket messages sent or received 135 will conform to the protocol defined in the rest of this document. 137 C: GET /xmpp-websocket HTTP/1.1 138 Host: example.com 139 Upgrade: websocket 140 Connection: Upgrade 141 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 142 Origin: http://example.com 143 ... 144 Sec-WebSocket-Protocol: xmpp 145 Sec-WebSocket-Version: 13 147 S: HTTP/1.1 101 Switching Protocols 148 Upgrade: websocket 149 Connection: Upgrade 150 ... 151 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 152 Sec-WebSocket-Protocol: xmpp 154 [WebSocket connection established] 156 C: 160 3.2. WebSocket Messages 162 Data frame messages in the XMPP sub-protocol MUST be of the text type 163 and contain UTF-8 encoded data. 165 3.3. XMPP Framing 167 The WebSocket XMPP sub-protocol deviates from the standard method of 168 constructing and using XML streams as defined in [RFC6120] by 169 adopting the message framing provided by WebSocket to delineate the 170 stream open and close headers, stanzas, and other top-level stream 171 elements. 173 3.3.1. Framed XML Stream 175 The start of a framed XML stream is marked by the use of an opening 176 "stream header" which is an element with the appropriate 177 attributes and namespace declarations (see Section 3.3.2). The 178 attributes of the element are the same as those of the 179 element defined in [RFC6120], and with the same semantics. 181 The end of a framed XML stream is denoted by the closing "stream 182 header" which is a element with its associated attributes 183 and namespace declarations (see Section 3.3.2). 185 The introduction of the and elements is motivated by 186 the parsable XML document framing restriction in Section 3.3.3. As a 187 consequence, note that a framed XML stream does not provided a 188 wrapping element encompassing the entirety of the 189 XML stream, as in [RFC6120]. 191 3.3.2. Framed Stream Namespace 193 The XML stream "headers" (the and elements) MUST be 194 qualified by the namespace 'urn:ietf:params:xml:ns:xmpp-framing' (the 195 "framed stream namespace"). If this rule is violated, the entity 196 that receives the offending stream header MUST close the stream with 197 an error, which SHOULD be (see Section 4.9.3.10 198 of [RFC6120]). 200 3.3.3. Stream Frames 202 The individual frames of a framed XML stream have a one-to-one 203 correspondence with WebSocket messages, and MUST be parsable as 204 standalone XML documents, complete with all relevant namespace and 205 language declarations. The inclusion of XML declarations, however, 206 is NOT RECOMMENDED as WebSocket messages are already mandated to be 207 UTF-8 encoded and therefore would only add a constant size overhead 208 to each message. 210 The first character of each frame MUST be a '<' character. 212 Every XMPP stanza or other XML element (including the stream open and 213 close headers) sent directly over the XML stream MUST be sent in its 214 own frame. 216 Examples of WebSocket messages that contain independently parsable 217 XML documents (note that for stream features and errors, there is no 218 parent context element providing the "stream" namespace prefix as in 219 [RFC6120], and thus the stream namespace MUST be declared): 221 -- WS Message boundary -- 222 223 224 225 -- WS Message boundary -- 226 227 228 229 -- WS Message boundary -- 230 231 Every WebSocket message is parsable by itself. 232 234 3.4. Stream Initiation 236 The first message sent by the initiating entity after the WebSocket 237 opening handshake is complete MUST be an element qualified by 238 the "urn:ietf:params:xml:ns:xmpp-framing" namespace. The 'from', 239 'id', 'to', and 'version' attributes of this element mirror those of 240 the XMPP opening stream tag as defined for the 241 'http://etherx.jabber.org/streams' namespace in XMPP [RFC6120]. 243 The receiving entity MUST respond with an element, or a 244 element (see Section 3.6.1). 246 Clients MUST NOT multiplex XMPP streams over the same WebSocket. 248 3.5. Stream Errors 250 Stream level errors in XMPP are terminal. Should such an error 251 occur, the server MUST send the stream error as a complete element in 252 a message to the client. 254 If the error occurs during the opening of a stream, the server MUST 255 send the initial open element response, followed by the stream level 256 error in a second WebSocket message frame. The server MUST then 257 close the connection as specified in Section 3.6. 259 3.6. Closing the Connection 261 Either the server or the client may close the connection at any time. 262 Before closing the connection, the closing party SHOULD close the 263 XMPP stream, if it has been established, by sending a message with 264 the element, qualified by the "urn:ietf:params:xml:ns:xmpp- 265 framing" namespace. The stream is considered closed when a 266 corresponding element is received from the other party. 268 To close the WebSocket connection, the closing party MUST initiate 269 the WebSocket closing handshake (see Section 7.1.2 of [RFC6455]). 271 An example of ending an XMPP over WebSocket session by first closing 272 the XMPP stream layer and then the WebSocket connection layer: 274 Client (XMPP WSS) Server 275 | | | | 276 | | | | 279 | |<------------------------------------------------------------| | 280 | | | | 281 | | (XMPP Stream Closed) | | 282 | +-------------------------------------------------------------+ | 283 | | 284 | WS CLOSE FRAME | 285 |------------------------------------------------------------------>| 286 | WS CLOSE FRAME | 287 |<------------------------------------------------------------------| 288 | | 289 | (Connection Closed) | 290 +-------------------------------------------------------------------+ 292 If a client closes the WebSocket connection without closing the XMPP 293 stream after having enabled stream management (see Section 3.10), the 294 server SHOULD keep the XMPP session alive for a period of time based 295 on server policy, as specified in [XEP-0198]. If the client has not 296 negotiated the use of [XEP-0198], there is no distinction between a 297 stream that was closed as described above and a simple disconnection; 298 the stream is then considered implicitly closed and the XMPP session 299 ended. 301 3.6.1. see-other-uri 303 If the server (or a connection manager intermediary) wishes to 304 instruct the client to move to a different WebSocket endpoint (e.g. 305 for load balancing purposes), the server MAY send a element 306 and set the "see-other-uri" attribute to the URI of the new 307 connection endpoint (which MAY be for a different transport method, 308 such as BOSH (see [XEP-0124] and [XEP-0206]). 310 Clients MUST NOT accept suggested endpoints with a lower security 311 context (e.g. moving from a "wss://" endpoint to a "ws://" or "http:/ 312 /" endpoint). 314 An example of the server closing a stream and instructing the client 315 to connect at a different WebSocket endpoint: 317 S: 320 3.7. Stream Restarts 322 Whenever a stream restart is mandated, both the server and client 323 streams are implicitly closed and new streams MUST be opened, using 324 the same process as in Section 3.4. The client MUST send a new 325 stream element and MUST NOT send a closing element. 327 An example of restarting the stream after successful SASL 328 negotiation: 330 S: 332 [Streams implicitly closed] 334 C: 338 3.8. Pings and Keepalives 340 XMPP servers often send "whitespace keepalives" (see Section 4.6.1 of 341 [RFC6120]) between stanzas to maintain an XML stream, and XMPP 342 clients can do the same as these extra whitespace characters are not 343 significant in the protocol. Servers and clients SHOULD use 344 WebSocket ping control frames instead for this purpose. 346 In some cases, the WebSocket connection might be served by an 347 intermediary connection manager and not the XMPP server. In these 348 situations, the use of WebSocket ping messages are insufficient to 349 test that the XMPP stream is still alive. Both the XMPP Ping 350 extension [XEP-0199] and the XMPP Stream Management extension 351 [XEP-0198] provide mechanisms to ping the XMPP server, and either 352 extension (or both) MAY be used to determine the state of the 353 connection. 355 3.9. Use of TLS 357 TLS cannot be used at the XMPP sub-protocol layer because the sub- 358 protocol does not allow for raw binary data to be sent. Instead, 359 enabling TLS SHOULD be done at the WebSocket layer using secure 360 WebSocket connections via the |wss| URI scheme. (See Section 10.6 of 361 [RFC6455].) 363 Because TLS is to be provided outside of the XMPP sub-protocol layer, 364 a server MUST NOT advertise TLS as a stream feature (see Section 4.6 365 of [RFC6120]), and a client MUST ignore any advertised TLS stream 366 feature, when using the XMPP sub-protocol. 368 3.10. Stream Management 370 In order to alleviate the problems of temporary disconnections, the 371 XMPP Stream Management extension [XEP-0198] MAY be used to confirm 372 when stanzas have been received by the server. 374 In particular, the use of session resumption in [XEP-0198] MAY be 375 used to allow for recreating the same stream session state after a 376 temporary network unavailability or after navigating to a new URL in 377 a browser. 379 4. Discovering the WebSocket Connection Method 381 Section 3 of [RFC6120] defines a procedure for connecting to an XMPP 382 server, including ways to discover the TCP/IP address and port of the 383 server. When using the WebSocket binding as specified in this 384 document (instead of the TCP binding as specified in [RFC6120]), a 385 client needs an alternative way to discover information about the 386 server's connection methods, since web browsers and other WebSocket- 387 capable software applications typically cannot obtain such 388 information from the Domain Name System. 390 The alternative lookup process uses Web Host Metadata [RFC6415] and 391 Web Linking [RFC5988], where the link relation type is "urn:xmpp:alt- 392 connections:websocket" as described in Discovering Alternate XMPP 393 Connection Methods [XEP-0156]. An example follows. 395 396 398 400 Servers MAY expose discovery information using host-meta documents, 401 and clients MAY use such information to determine the WebSocket 402 endpoint for a server. 404 Use of web-host metadata MAY be used to establish trust between the 405 XMPP server domain and the WebSocket endpoint, particularly in multi- 406 tenant situations where the same WebSocket endpoint is serving 407 multiple XMPP domains. 409 5. IANA Considerations 411 5.1. WebSocket Subprotocol Name 413 This specification requests IANA to register the WebSocket XMPP sub- 414 protocol under the "WebSocket Subprotocol Name" Registry with the 415 following data: 417 Subprotocol Identifier: xmpp 419 Subprotocol Common Name: WebSocket Transport for the Extensible 420 Messaging and Presence Protocol (XMPP) 422 Subprotocol Definition: this document 424 5.2. URN Sub-Namespace 426 A URN sub-namespace for framing of Extensible Messaging and Presence 427 Protocol (XMPP) streams is defined as follows. 429 URI: urn:ietf:params:xml:ns:xmpp-framing 431 Specification: this document 433 Description: This is the XML namespace name for framing of 434 Extensible Messaging and Presence Protocol (XMPP) streams as 435 defined by RFC XXXX. 437 Registrant Contact: IESG 439 6. Security Considerations 441 Since application level TLS cannot be used (see Section 3.9), 442 applications need to protect the privacy of XMPP traffic at the 443 WebSocket or other appropriate layer. 445 Browser based applications are not able to inspect and verify at the 446 application layer the certificate used for the WebSocket connection 447 to ensure that it corresponds to the domain specified as the "to" 448 address of the XMPP stream. For hosts whose domain matches the 449 origin for the WebSocket connection, that check is already performed 450 by the browser. However, in situations where the domain of the XMPP 451 server might not match the origin for the WebSocket endpoint 452 (especially multi-tenant hosting situations), the web host metadata 453 method (see [RFC6415] and [XEP-0156]) MAY be used to delegate trust 454 from the XMPP server domain to the WebSocket origin. 456 When presented with a new WebSocket endpoint via the "see-other-uri" 457 attribute of a element, clients MUST NOT accept the 458 suggestion if the security context of the new endpoint is lower than 459 the current one in order to prevent downgrade attacks from a "wss://" 460 endpoint to "ws://". 462 The Security Considerations for both WebSocket (see Section 10 of 463 [RFC6455] and XMPP (see Section 13 of [RFC6120]) apply to the 464 WebSocket XMPP sub-protocol. 466 7. References 468 7.1. Normative References 470 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 471 Requirement Levels", BCP 14, RFC 2119, March 1997. 473 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 474 Protocol (XMPP): Core", RFC 6120, March 2011. 476 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 477 6455, December 2011. 479 7.2. Informative References 481 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 483 [RFC6121] Saint-Andre, P., "Extensible Messaging and Presence 484 Protocol (XMPP): Instant Messaging and Presence", RFC 485 6121, March 2011. 487 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 488 "Known Issues and Best Practices for the Use of Long 489 Polling and Streaming in Bidirectional HTTP", RFC 6202, 490 April 2011. 492 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 493 6415, October 2011. 495 [XEP-0124] 496 Paterson, I., Smith, D., Saint-Andre, P., Moffitt, J., and 497 L. Stout, "Bidirectional-streams Over Synchronous HTTP 498 (BOSH)", XSF XEP 0124, November 2013. 500 [XEP-0156] 501 Hildebrand, J., Saint-Andre, P., and L. Stout, 502 "Discovering Alternative XMPP Connection Methods", XSF XEP 503 0156, January 2014. 505 [XEP-0198] 506 Karneges, J., Saint-Andre, P., Hildebrand, J., Forno, F., 507 Cridland, D., and M. Wild, "Stream Management", XSF XEP 508 0198, June 2011. 510 [XEP-0199] 511 Saint-Andre, P., "XMPP Ping", XSF XEP 0199, June 2009. 513 [XEP-0206] 514 Paterson, I., Saint-Andre, P., and L. Stout, "XMPP Over 515 BOSH", XSF XEP 0206, November 2013. 517 [XML-SCHEMA] 518 Thompson, H., Maloney, M., Mendelsohn, N., and D. Beech, 519 "XML Schema Part 1: Structures Second Edition", World Wide 520 Web Consortium Recommendation REC-xmlschema-1-20041028, 521 October 2004, 522 . 524 Appendix A. XML Schema 526 The following schema formally defines the 'urn:ietf:params:xml:ns 527 :xmpp-framing' namespace used in this document, in conformance with 528 W3C XML Schema [XML-SCHEMA]. Because validation of XML streams and 529 stanzas is optional, this schema is not normative and is provided for 530 descriptive purposes only. 532 534 540 541 542 543 544 546 548 550 552 554 555 556 557 559 560 561 562 563 565 567 569 571 573 575 576 577 578 580 581 582 583 584 586 588 Authors' Addresses 590 Lance Stout (editor) 591 &yet 593 Email: lance@andyet.net 595 Jack Moffitt 596 Mozilla 598 Email: jack@metajack.im 600 Eric Cestari 601 cstar industries 603 Email: eric@cstar.io