idnits 2.17.1 draft-ietf-xmpp-websocket-06.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 22, 2014) is 3650 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 24, 2014 Mozilla 6 E. Cestari 7 cstar industries 8 April 22, 2014 10 An XMPP Sub-protocol for WebSocket 11 draft-ietf-xmpp-websocket-06 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 24, 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 . . . . . . . . . . . . . . . . . 7 65 3.6.1. see-other-uri . . . . . . . . . . . . . . . . . . . . 8 66 3.7. Stream Restarts . . . . . . . . . . . . . . . . . . . . . 8 67 3.8. Pings and Keepalives . . . . . . . . . . . . . . . . . . 8 68 3.9. Use of TLS . . . . . . . . . . . . . . . . . . . . . . . 9 69 3.10. Stream Management . . . . . . . . . . . . . . . . . . . . 9 70 4. Discovering the WebSocket Connection Method . . . . . . . . . 9 71 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 72 5.1. WebSocket Subprotocol Name . . . . . . . . . . . . . . . 10 73 5.2. URN Sub-Namespace . . . . . . . . . . . . . . . . . . . . 10 74 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . . . . 14 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 129 value |xmpp| in the list of protocols for the |Sec-WebSocket- 130 Protocol| header. The reply from the server MUST also contain |xmpp| 131 in its own |Sec-WebSocket-Protocol| header in order for an XMPP sub- 132 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 S: 166 3.2. WebSocket Messages 168 Data frame messages in the XMPP sub-protocol MUST be of the text type 169 and contain UTF-8 encoded data. 171 3.3. XMPP Framing 173 The WebSocket XMPP sub-protocol deviates from the standard method of 174 constructing and using XML streams as defined in [RFC6120] by 175 adopting the message framing provided by WebSocket to delineate the 176 stream open and close headers, stanzas, and other top-level stream 177 elements. 179 3.3.1. Framed XML Stream 181 The start of a framed XML stream is marked by the use of an opening 182 "stream header" which is an element with the appropriate 183 attributes and namespace declarations (see Section 3.3.2). The 184 attributes of the element are the same as those of the 185 element defined defined for the 'http://etherx.jabber.org/ 186 streams' namespace in [RFC6120] and with the same semantics and 187 restrictions. 189 The end of a framed XML stream is denoted by the closing "stream 190 header" which is a element with its associated attributes 191 and namespace declarations (see Section 3.3.2). 193 The introduction of the and elements is motivated by 194 the parsable XML document framing restriction in Section 3.3.3. As a 195 consequence, note that a framed XML stream does not provided a 196 wrapping element encompassing the entirety of the 197 XML stream, as in [RFC6120]. 199 3.3.2. Framed Stream Namespace 201 The XML stream "headers" (the and elements) MUST be 202 qualified by the namespace 'urn:ietf:params:xml:ns:xmpp-framing' (the 203 "framed stream namespace"). If this rule is violated, the entity 204 that receives the offending stream header MUST close the stream with 205 an error, which MUST be (see Section 4.9.3.10 of 206 [RFC6120]). 208 3.3.3. Stream Frames 210 The individual frames of a framed XML stream have a one-to-one 211 correspondence with WebSocket messages, and MUST be parsable as 212 standalone XML documents, complete with all relevant namespace and 213 language declarations. The inclusion of XML declarations, however, 214 is NOT RECOMMENDED as WebSocket messages are already mandated to be 215 UTF-8 encoded and therefore would only add a constant size overhead 216 to each message. 218 The first character of each frame MUST be a '<' character. 220 Every XMPP stanza or other XML element (including the stream open and 221 close headers) sent directly over the XML stream MUST be sent in its 222 own frame. 224 Example of a WebSocket message that contains an independently 225 parsable XML document: 227 228 Every WebSocket message is parsable by itself. 229 230 Note that for stream features and errors, there is no parent context 231 element providing the "stream" namespace prefix as in [RFC6120], and 232 thus the stream prefix MUST be declared or use an unprefixed form: 234 235 236 238 -- OR -- 240 241 242 244 3.4. Stream Initiation 246 The first message sent after the WebSocket opening handshake MUST be 247 from the initiating entity, and MUST be an element qualified 248 by the "urn:ietf:params:xml:ns:xmpp-framing" namespace and with the 249 same attributes mandated for the opening tag as described in 250 Section 4.7 of [RFC6120]. 252 The receiving entity MUST respond with either an element 253 (whose attributes match those described in Section 4.7 of [RFC6120]) 254 or a element (see Section 3.6.1). 256 An example of a successful stream initiation exchange: 258 C: 262 S: 268 Clients MUST NOT multiplex XMPP streams over the same WebSocket. 270 3.5. Stream Errors 272 Stream level errors in XMPP are terminal. Should such an error 273 occur, the server MUST send the stream error as a complete element in 274 a message to the client. 276 If the error occurs during the opening of a stream, the server MUST 277 send the initial open element response, followed by the stream level 278 error in a second WebSocket message frame. The server MUST then 279 close the connection as specified in Section 3.6. 281 3.6. Closing the Connection 283 The closing process for the XMPP sub-protocol mirrors that of the 284 XMPP TCP binding as defined in Section 4.4 of [RFC6120], except that 285 a element is used instead of the ending 286 tag. 288 Either the server or the client may close the connection at any time. 289 Before closing the connection, the closing party is expected to first 290 close the XMPP stream (if one has been opened) by sending a message 291 with the element, qualified by the "urn:ietf:params:xml:ns 292 :xmpp-framing" namespace. The stream is considered closed when a 293 corresponding element is received from the other party, and 294 the XMPP session is ended. 296 To then close the WebSocket connection, the closing party MUST 297 initiate the WebSocket closing handshake (see Section 7.1.2 of 298 [RFC6455]). 300 An example of ending an XMPP over WebSocket session by first closing 301 the XMPP stream layer and then the WebSocket connection layer: 303 Client (XMPP WSS) Server 304 | | | | 305 | | | | 308 | |<------------------------------------------------------------| | 309 | | | | 310 | | (XMPP Stream Closed) | | 311 | +-------------------------------------------------------------+ | 312 | | 313 | WS CLOSE FRAME | 314 |------------------------------------------------------------------>| 315 | WS CLOSE FRAME | 316 |<------------------------------------------------------------------| 317 | | 318 | (Connection Closed) | 319 +-------------------------------------------------------------------+ 321 If the WebSocket connection is closed or broken without the XMPP 322 stream having been closed first, then the XMPP stream is considered 323 implicitly closed and the XMPP session ended; however, if the use of 324 stream management resumption was negotiated (see [XEP-0198]), the 325 server SHOULD consider the XMPP session still alive for a period of 326 time based on server policy as specified in [XEP-0198]. 328 3.6.1. see-other-uri 330 If the server (or a connection manager intermediary) wishes at any 331 point to instruct the client to move to a different WebSocket 332 endpoint (e.g. for load balancing purposes), the server MAY send a 333 element and set the "see-other-uri" attribute to the URI of 334 the new connection endpoint (which MAY be for a different transport 335 method, such as BOSH (see [XEP-0124] and [XEP-0206]). 337 Clients MUST NOT accept suggested endpoints with a lower security 338 context (e.g. moving from a "wss://" endpoint to a "ws://" or "http:/ 339 /" endpoint). 341 An example of the server closing a stream and instructing the client 342 to connect at a different WebSocket endpoint: 344 S: 347 3.7. Stream Restarts 349 Whenever a stream restart is mandated, both the server and client 350 streams are implicitly closed and new streams MUST be opened, using 351 the same process as in Section 3.4. The client MUST send a new 352 stream element and MUST NOT send a closing element. 354 An example of restarting the stream after successful SASL 355 negotiation: 357 S: 359 [Streams implicitly closed] 361 C: 365 3.8. Pings and Keepalives 367 Traditionally, XMPP servers and clients often send "whitespace 368 keepalives" (see Section 4.6.1 of [RFC6120]) between stanzas to 369 maintain an XML stream. However, for the XMPP sub-protocol, each 370 message is required to start with a '<' character, and as such 371 whitespace keepalives MUST NOT be used. 373 As alternatives, the XMPP Ping extension [XEP-0199] and the XMPP 374 Stream Management extension [XEP-0198] provide pinging mechanisms. 375 The use of either of these extensions (or both) MAY be used to 376 determine the state of the connection. 378 Clients and servers MAY also use WebSocket ping control frames for 379 this purpose, but note that some environments, such as browsers, do 380 not provide access for generating or monitoring ping control frames. 382 3.9. Use of TLS 384 TLS cannot be used at the XMPP sub-protocol layer because the sub- 385 protocol does not allow for raw binary data to be sent. Instead, 386 when TLS is used, it MUST be enabled the WebSocket layer using secure 387 WebSocket connections via the |wss| URI scheme. (See Section 10.6 of 388 [RFC6455].) 390 Because TLS is to be provided outside of the XMPP sub-protocol layer, 391 a server MUST NOT advertise TLS as a stream feature (see Section 4.6 392 of [RFC6120]), and a client MUST ignore any advertised TLS stream 393 feature, when using the XMPP sub-protocol. 395 3.10. Stream Management 397 In order to alleviate the problems of temporary disconnections, the 398 XMPP Stream Management extension [XEP-0198] MAY be used to confirm 399 when stanzas have been received by the server. 401 In particular, the use of session resumption in [XEP-0198] MAY be 402 used to allow for recreating the same stream session state after a 403 temporary network unavailability or after navigating to a new URL in 404 a browser. 406 4. Discovering the WebSocket Connection Method 408 Section 3 of [RFC6120] defines a procedure for connecting to an XMPP 409 server, including ways to discover the TCP/IP address and port of the 410 server. When using the WebSocket binding as specified in this 411 document (instead of the TCP binding as specified in [RFC6120]), a 412 client needs an alternative way to discover information about the 413 server's connection methods, since web browsers and other WebSocket- 414 capable software applications typically cannot obtain such 415 information from the Domain Name System. 417 The alternative lookup process uses Web Host Metadata [RFC6415] and 418 Web Linking [RFC5988], where the link relation type is "urn:xmpp:alt- 419 connections:websocket" as described in Discovering Alternate XMPP 420 Connection Methods [XEP-0156]. An example follows. 422 423 425 427 Servers MAY expose discovery information using host-meta documents, 428 and clients MAY use such information to determine the WebSocket 429 endpoint for a server. 431 Use of web-host metadata MAY be used to establish trust between the 432 XMPP server domain and the WebSocket endpoint, particularly in multi- 433 tenant situations where the same WebSocket endpoint is serving 434 multiple XMPP domains. 436 5. IANA Considerations 438 5.1. WebSocket Subprotocol Name 440 This specification requests IANA to register the WebSocket XMPP sub- 441 protocol under the "WebSocket Subprotocol Name" Registry with the 442 following data: 444 Subprotocol Identifier: xmpp 446 Subprotocol Common Name: WebSocket Transport for the Extensible 447 Messaging and Presence Protocol (XMPP) 449 Subprotocol Definition: this document 451 5.2. URN Sub-Namespace 453 A URN sub-namespace for framing of Extensible Messaging and Presence 454 Protocol (XMPP) streams is defined as follows. 456 URI: urn:ietf:params:xml:ns:xmpp-framing 458 Specification: this document 460 Description: This is the XML namespace name for framing of 461 Extensible Messaging and Presence Protocol (XMPP) streams as 462 defined by RFC XXXX. 464 Registrant Contact: IESG 466 6. Security Considerations 468 Since application level TLS cannot be used (see Section 3.9), 469 applications need to protect the privacy of XMPP traffic at the 470 WebSocket or other appropriate layer. 472 Browser based applications are not able to inspect and verify at the 473 application layer the certificate used for the WebSocket connection 474 to ensure that it corresponds to the domain specified as the "to" 475 address of the XMPP stream. For hosts whose domain matches the 476 origin for the WebSocket connection, that check is already performed 477 by the browser. However, in situations where the domain of the XMPP 478 server might not match the origin for the WebSocket endpoint 479 (especially multi-tenant hosting situations), the web host metadata 480 method (see [RFC6415] and [XEP-0156]) MAY be used to delegate trust 481 from the XMPP server domain to the WebSocket origin. 483 When presented with a new WebSocket endpoint via the "see-other-uri" 484 attribute of a element, clients MUST NOT accept the 485 suggestion if the security context of the new endpoint is lower than 486 the current one in order to prevent downgrade attacks from a "wss://" 487 endpoint to "ws://". 489 The Security Considerations for both WebSocket (see Section 10 of 490 [RFC6455] and XMPP (see Section 13 of [RFC6120]) apply to the 491 WebSocket XMPP sub-protocol. 493 7. References 495 7.1. Normative References 497 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 498 Requirement Levels", BCP 14, RFC 2119, March 1997. 500 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 501 Protocol (XMPP): Core", RFC 6120, March 2011. 503 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 504 6455, December 2011. 506 7.2. Informative References 508 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 510 [RFC6121] Saint-Andre, P., "Extensible Messaging and Presence 511 Protocol (XMPP): Instant Messaging and Presence", RFC 512 6121, March 2011. 514 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 515 "Known Issues and Best Practices for the Use of Long 516 Polling and Streaming in Bidirectional HTTP", RFC 6202, 517 April 2011. 519 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 520 6415, October 2011. 522 [XEP-0124] 523 Paterson, I., Smith, D., Saint-Andre, P., Moffitt, J., and 524 L. Stout, "Bidirectional-streams Over Synchronous HTTP 525 (BOSH)", XSF XEP 0124, November 2013. 527 [XEP-0156] 528 Hildebrand, J., Saint-Andre, P., and L. Stout, 529 "Discovering Alternative XMPP Connection Methods", XSF XEP 530 0156, January 2014. 532 [XEP-0198] 533 Karneges, J., Saint-Andre, P., Hildebrand, J., Forno, F., 534 Cridland, D., and M. Wild, "Stream Management", XSF XEP 535 0198, June 2011. 537 [XEP-0199] 538 Saint-Andre, P., "XMPP Ping", XSF XEP 0199, June 2009. 540 [XEP-0206] 541 Paterson, I., Saint-Andre, P., and L. Stout, "XMPP Over 542 BOSH", XSF XEP 0206, November 2013. 544 [XML-SCHEMA] 545 Thompson, H., Maloney, M., Mendelsohn, N., and D. Beech, 546 "XML Schema Part 1: Structures Second Edition", World Wide 547 Web Consortium Recommendation REC-xmlschema-1-20041028, 548 October 2004, 549 . 551 Appendix A. XML Schema 553 The following schema formally defines the 'urn:ietf:params:xml:ns 554 :xmpp-framing' namespace used in this document, in conformance with 555 W3C XML Schema [XML-SCHEMA]. Because validation of XML streams and 556 stanzas is optional, this schema is not normative and is provided for 557 descriptive purposes only. 559 561 567 568 569 570 571 573 575 577 579 581 582 583 584 586 587 588 589 590 592 594 596 598 600 602 603 604 605 607 608 609 611 612 614 616 Authors' Addresses 618 Lance Stout (editor) 619 &yet 621 Email: lance@andyet.net 623 Jack Moffitt 624 Mozilla 626 Email: jack@metajack.im 628 Eric Cestari 629 cstar industries 631 Email: eric@cstar.io