idnits 2.17.1
draft-ietf-xmpp-websocket-04.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 20, 2014) is 3652 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 22, 2014 Mozilla
6 E. Cestari
7 cstar industries
8 April 20, 2014
10 An XMPP Sub-protocol for WebSocket
11 draft-ietf-xmpp-websocket-04
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 22, 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 . . . . . . . . . . . . . . . . . . . . . . 7
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 |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 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 SHOULD be (see Section 4.9.3.10
206 of [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 Examples of WebSocket messages that contain independently parsable
225 XML documents (note that for stream features and errors, there is no
226 parent context element providing the "stream" namespace prefix as in
227 [RFC6120], and thus the stream namespace MUST be declared):
229 -- WS Message boundary --
230
231
232
233 -- WS Message boundary --
234
235
236
237 -- WS Message boundary --
238
239 Every WebSocket message is parsable by itself.
240
242 3.4. Stream Initiation
244 The first message sent after the WebSocket opening handshake MUST be
245 from the initiating entity, and MUST be an element qualified
246 by the "urn:ietf:params:xml:ns:xmpp-framing" namespace and with the
247 same attributes mandated for the opening tag as described in
248 Section 4.7 of [RFC6120].
250 The receiving entity MUST respond with either an element
251 (whose attributes match those described in Section 4.7 of [RFC6120])
252 or a element (see Section 3.6.1).
254 An example of a successful stream initiation exchange:
256 C:
260 S:
266 Clients MUST NOT multiplex XMPP streams over the same WebSocket.
268 3.5. Stream Errors
270 Stream level errors in XMPP are terminal. Should such an error
271 occur, the server MUST send the stream error as a complete element in
272 a message to the client.
274 If the error occurs during the opening of a stream, the server MUST
275 send the initial open element response, followed by the stream level
276 error in a second WebSocket message frame. The server MUST then
277 close the connection as specified in Section 3.6.
279 3.6. Closing the Connection
281 Either the server or the client may close the connection at any time.
282 Before closing the connection, the closing party SHOULD close the
283 XMPP stream, if it has been established, by sending a message with
284 the element, qualified by the "urn:ietf:params:xml:ns:xmpp-
285 framing" namespace. The stream is considered closed when a
286 corresponding element is received from the other party.
288 To close the WebSocket connection, the closing party MUST initiate
289 the WebSocket closing handshake (see Section 7.1.2 of [RFC6455]).
291 An example of ending an XMPP over WebSocket session by first closing
292 the XMPP stream layer and then the WebSocket connection layer:
294 Client (XMPP WSS) Server
295 | | | |
296 | | | |
299 | |<------------------------------------------------------------| |
300 | | | |
301 | | (XMPP Stream Closed) | |
302 | +-------------------------------------------------------------+ |
303 | |
304 | WS CLOSE FRAME |
305 |------------------------------------------------------------------>|
306 | WS CLOSE FRAME |
307 |<------------------------------------------------------------------|
308 | |
309 | (Connection Closed) |
310 +-------------------------------------------------------------------+
312 If a client closes the WebSocket connection without closing the XMPP
313 stream after having enabled stream management (see Section 3.10), the
314 server SHOULD keep the XMPP session alive for a period of time based
315 on server policy, as specified in [XEP-0198]. If the client has not
316 negotiated the use of [XEP-0198], there is no distinction between a
317 stream that was closed as described above and a simple disconnection;
318 the stream is then considered implicitly closed and the XMPP session
319 ended.
321 3.6.1. see-other-uri
323 If the server (or a connection manager intermediary) wishes to
324 instruct the client to move to a different WebSocket endpoint (e.g.
325 for load balancing purposes), the server MAY send a element
326 and set the "see-other-uri" attribute to the URI of the new
327 connection endpoint (which MAY be for a different transport method,
328 such as BOSH (see [XEP-0124] and [XEP-0206]).
330 Clients MUST NOT accept suggested endpoints with a lower security
331 context (e.g. moving from a "wss://" endpoint to a "ws://" or "http:/
332 /" endpoint).
334 An example of the server closing a stream and instructing the client
335 to connect at a different WebSocket endpoint:
337 S:
340 3.7. Stream Restarts
342 Whenever a stream restart is mandated, both the server and client
343 streams are implicitly closed and new streams MUST be opened, using
344 the same process as in Section 3.4. The client MUST send a new
345 stream element and MUST NOT send a closing element.
347 An example of restarting the stream after successful SASL
348 negotiation:
350 S:
352 [Streams implicitly closed]
354 C:
358 3.8. Pings and Keepalives
360 XMPP servers often send "whitespace keepalives" (see Section 4.6.1 of
361 [RFC6120]) between stanzas to maintain an XML stream, and XMPP
362 clients can do the same as these extra whitespace characters are not
363 significant in the protocol. Servers and clients SHOULD use
364 WebSocket ping control frames instead for this purpose.
366 In some cases, the WebSocket connection might be served by an
367 intermediary connection manager and not the XMPP server. In these
368 situations, the use of WebSocket ping messages are insufficient to
369 test that the XMPP stream is still alive. Both the XMPP Ping
370 extension [XEP-0199] and the XMPP Stream Management extension
371 [XEP-0198] provide mechanisms to ping the XMPP server, and either
372 extension (or both) MAY be used to determine the state of the
373 connection.
375 3.9. Use of TLS
377 TLS cannot be used at the XMPP sub-protocol layer because the sub-
378 protocol does not allow for raw binary data to be sent. Instead,
379 enabling TLS SHOULD be done at the WebSocket layer using secure
380 WebSocket connections via the |wss| URI scheme. (See Section 10.6 of
381 [RFC6455].)
383 Because TLS is to be provided outside of the XMPP sub-protocol layer,
384 a server MUST NOT advertise TLS as a stream feature (see Section 4.6
385 of [RFC6120]), and a client MUST ignore any advertised TLS stream
386 feature, when using the XMPP sub-protocol.
388 3.10. Stream Management
390 In order to alleviate the problems of temporary disconnections, the
391 XMPP Stream Management extension [XEP-0198] MAY be used to confirm
392 when stanzas have been received by the server.
394 In particular, the use of session resumption in [XEP-0198] MAY be
395 used to allow for recreating the same stream session state after a
396 temporary network unavailability or after navigating to a new URL in
397 a browser.
399 4. Discovering the WebSocket Connection Method
401 Section 3 of [RFC6120] defines a procedure for connecting to an XMPP
402 server, including ways to discover the TCP/IP address and port of the
403 server. When using the WebSocket binding as specified in this
404 document (instead of the TCP binding as specified in [RFC6120]), a
405 client needs an alternative way to discover information about the
406 server's connection methods, since web browsers and other WebSocket-
407 capable software applications typically cannot obtain such
408 information from the Domain Name System.
410 The alternative lookup process uses Web Host Metadata [RFC6415] and
411 Web Linking [RFC5988], where the link relation type is "urn:xmpp:alt-
412 connections:websocket" as described in Discovering Alternate XMPP
413 Connection Methods [XEP-0156]. An example follows.
415
416
418
420 Servers MAY expose discovery information using host-meta documents,
421 and clients MAY use such information to determine the WebSocket
422 endpoint for a server.
424 Use of web-host metadata MAY be used to establish trust between the
425 XMPP server domain and the WebSocket endpoint, particularly in multi-
426 tenant situations where the same WebSocket endpoint is serving
427 multiple XMPP domains.
429 5. IANA Considerations
431 5.1. WebSocket Subprotocol Name
433 This specification requests IANA to register the WebSocket XMPP sub-
434 protocol under the "WebSocket Subprotocol Name" Registry with the
435 following data:
437 Subprotocol Identifier: xmpp
439 Subprotocol Common Name: WebSocket Transport for the Extensible
440 Messaging and Presence Protocol (XMPP)
442 Subprotocol Definition: this document
444 5.2. URN Sub-Namespace
446 A URN sub-namespace for framing of Extensible Messaging and Presence
447 Protocol (XMPP) streams is defined as follows.
449 URI: urn:ietf:params:xml:ns:xmpp-framing
451 Specification: this document
453 Description: This is the XML namespace name for framing of
454 Extensible Messaging and Presence Protocol (XMPP) streams as
455 defined by RFC XXXX.
457 Registrant Contact: IESG
459 6. Security Considerations
461 Since application level TLS cannot be used (see Section 3.9),
462 applications need to protect the privacy of XMPP traffic at the
463 WebSocket or other appropriate layer.
465 Browser based applications are not able to inspect and verify at the
466 application layer the certificate used for the WebSocket connection
467 to ensure that it corresponds to the domain specified as the "to"
468 address of the XMPP stream. For hosts whose domain matches the
469 origin for the WebSocket connection, that check is already performed
470 by the browser. However, in situations where the domain of the XMPP
471 server might not match the origin for the WebSocket endpoint
472 (especially multi-tenant hosting situations), the web host metadata
473 method (see [RFC6415] and [XEP-0156]) MAY be used to delegate trust
474 from the XMPP server domain to the WebSocket origin.
476 When presented with a new WebSocket endpoint via the "see-other-uri"
477 attribute of a element, clients MUST NOT accept the
478 suggestion if the security context of the new endpoint is lower than
479 the current one in order to prevent downgrade attacks from a "wss://"
480 endpoint to "ws://".
482 The Security Considerations for both WebSocket (see Section 10 of
483 [RFC6455] and XMPP (see Section 13 of [RFC6120]) apply to the
484 WebSocket XMPP sub-protocol.
486 7. References
488 7.1. Normative References
490 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
491 Requirement Levels", BCP 14, RFC 2119, March 1997.
493 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence
494 Protocol (XMPP): Core", RFC 6120, March 2011.
496 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC
497 6455, December 2011.
499 7.2. Informative References
501 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
503 [RFC6121] Saint-Andre, P., "Extensible Messaging and Presence
504 Protocol (XMPP): Instant Messaging and Presence", RFC
505 6121, March 2011.
507 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins,
508 "Known Issues and Best Practices for the Use of Long
509 Polling and Streaming in Bidirectional HTTP", RFC 6202,
510 April 2011.
512 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC
513 6415, October 2011.
515 [XEP-0124]
516 Paterson, I., Smith, D., Saint-Andre, P., Moffitt, J., and
517 L. Stout, "Bidirectional-streams Over Synchronous HTTP
518 (BOSH)", XSF XEP 0124, November 2013.
520 [XEP-0156]
521 Hildebrand, J., Saint-Andre, P., and L. Stout,
522 "Discovering Alternative XMPP Connection Methods", XSF XEP
523 0156, January 2014.
525 [XEP-0198]
526 Karneges, J., Saint-Andre, P., Hildebrand, J., Forno, F.,
527 Cridland, D., and M. Wild, "Stream Management", XSF XEP
528 0198, June 2011.
530 [XEP-0199]
531 Saint-Andre, P., "XMPP Ping", XSF XEP 0199, June 2009.
533 [XEP-0206]
534 Paterson, I., Saint-Andre, P., and L. Stout, "XMPP Over
535 BOSH", XSF XEP 0206, November 2013.
537 [XML-SCHEMA]
538 Thompson, H., Maloney, M., Mendelsohn, N., and D. Beech,
539 "XML Schema Part 1: Structures Second Edition", World Wide
540 Web Consortium Recommendation REC-xmlschema-1-20041028,
541 October 2004,
542 .
544 Appendix A. XML Schema
546 The following schema formally defines the 'urn:ietf:params:xml:ns
547 :xmpp-framing' namespace used in this document, in conformance with
548 W3C XML Schema [XML-SCHEMA]. Because validation of XML streams and
549 stanzas is optional, this schema is not normative and is provided for
550 descriptive purposes only.
552
554
560
561
562
563
564
566
568
570
572
574
575
576
577
579
580
581
582
583
585
587
589
591
593
595
596
597
598
600
601
602
604
605
607
609 Authors' Addresses
611 Lance Stout (editor)
612 &yet
614 Email: lance@andyet.net
616 Jack Moffitt
617 Mozilla
619 Email: jack@metajack.im
621 Eric Cestari
622 cstar industries
624 Email: eric@cstar.io