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