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