idnits 2.17.1 draft-realvnc-websocket-01.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 (September 17, 2013) is 3873 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Taskforce N. Wilson 3 Internet-Draft RealVNC Ltd. 4 Intended status: Informational September 17, 2013 5 Expires: March 21, 2014 7 Use of the WebSocket Protocol as a Transport for the Remote Framebuffer 8 Protocol 9 draft-realvnc-websocket-01 11 Abstract 13 The Remote Framebuffer protocol (RFB) enables clients to connect to 14 and control remote graphical resources. This document describes a 15 transport for RFB using the WebSocket protocol, and defines a 16 corresponding WebSocket subprotocol, enabling an RFB server to offer 17 resources to clients with WebSocket connectivity, such as web- 18 browsers. 20 Requirements Language 22 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 23 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 24 document are to be interpreted as described in RFC 2119 [RFC2119]. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on March 21, 2014. 43 Copyright Notice 45 Copyright (c) 2013 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.2. Overview of the WebSocket Protocol as a stream transport 3 63 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. Interaction with the WebSocket Protocol . . . . . . . . . . . 4 65 3.1. The "Sec-WebSocket-Protocol" header . . . . . . . . . . . 4 66 3.2. Close Frames . . . . . . . . . . . . . . . . . . . . . . 5 67 3.3. Data Frames . . . . . . . . . . . . . . . . . . . . . . . 6 68 4. Versioning Considerations . . . . . . . . . . . . . . . . . . 6 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 70 5.1. Registration of the RFB WebSocket Subprotocol . . . . . . 7 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 72 6.1. Origin checking . . . . . . . . . . . . . . . . . . . . . 7 73 6.2. Data authentication and integrity . . . . . . . . . . . . 8 74 6.3. Creating a Safe JavaScript Environment . . . . . . . . . 8 75 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 76 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 77 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 78 8.2. Informative References . . . . . . . . . . . . . . . . . 9 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 81 1. Introduction 83 1.1. Background 85 _This section is non-normative._ 87 The WebSocket Protocol [RFC6455] provides a reliable, full-duplex, 88 message-oriented transport. The opening handshake is formatted as an 89 HTTP request and response, enabling access to resources through 90 intermediaries obeying HTTP semantics, such as proxies. This enables 91 resources served over a WebSocket-based transport to be accessible to 92 all web user-agents. 94 In addition, although untrusted websites cannot be given a mechanism 95 to make arbitrary TCP connections, web-browsers are able to offer web 96 resources such as JavaScript scripts the ability to make arbitrary 97 connections using the WebSocket protocol. The initial HTTP-formatted 98 handshake is performed by the user agent rather than the untrusted 99 web resource, and it conveys origin context, unlike a TCP handshake. 100 The web-browser is therefore able to allow pages to open WebSocket 101 connections, without opening up remote access to servers on the local 102 network, because WebSocket servers are able to check the origin 103 passed by the browser. 105 Therefore, offering RFB resources over a WebSocket-based transport 106 opens access to a variety of applications such as web pages, which 107 are unable to use the TCP transport described in The RFB Protocol 108 [RFC6143]. 110 The purpose of defining a WebSocket subprotocol is firstly to give 111 endpoints a clear way to indicate how the RFB stream is mapped to 112 WebSocket frames, ensuring compatible transport of the stream by 113 using an agreed mapping. Secondly, using a WebSocket subprotocol 114 enables multiple services to run at once on a single server. 115 Services which run over TCP/IP commonly use a port number allocated 116 for each service to enable multiple listening services on one 117 machine, but the behaviour of HTTP proxies makes it likely that 118 WebSocket servers will commonly be run only on ports 80 and 443. The 119 WebSocket subprotocol mechanism is analogous to the port number 120 system of IP addressing, but uses a short string naturally associated 121 with the service for identification, rather than an allocated number. 123 1.2. Overview of the WebSocket Protocol as a stream transport 125 _This section is non-normative._ 127 The RFB Protocol [RFC6143], section 7 explains that the protocol may 128 operate over any reliable stream- or message-oriented transport, but 129 only describes the RFB protocol as a stream of octets. This gives a 130 clear mapping for the TCP/IP transport, but for message-oriented 131 transport layers, the encapsulation of the RFB octet-stream must be 132 specified. 134 In this document, the WebSocket subprotocol for RFB is defined to 135 place no importance on the message boundaries of the WebSocket layer. 136 Instead, WebSocket messages are concatenated to form an octet stream 137 in each direction. 139 This is firstly because some RFB messages may be large, such as those 140 containing pixel data, and it may be a significant burden to some 141 client to require these to be processed as a single message. The 142 WebSocket API [WSAPI] requires clients to buffer the fragments of the 143 WebSocket message until the entire message has been received. 145 Although the RFB server and any WebSocket-aware proxy can fragment 146 the message as it chooses, a client application such as a mobile web- 147 browser would have to consume several megabytes of memory to satisfy 148 the requirements of the WebSocket API, if an RFB FramebufferUpdate 149 message could not be split across multiple WebSocket messages. 151 Secondly, it is advantageous to RFB servers to be able to wrap the 152 RFB stream in WebSocket messages flexibly. As well as being a 153 convenience to implementors of RFB servers, it also enables WebSocket 154 connectivity to be added to legacy software using a proxy. Without 155 requiring knowledge the protocol, a generic proxy may be used which 156 concatenates WebSocket messages received from the WebSocket client to 157 send over TCP to the RFB server, and reads bytes from the RFB server 158 and sends them to the client via WebSocket messages. 160 2. Definitions 162 RFB client, server, endpoint: As defined in The RFB Protocol 163 [RFC6143], section 1. An RFB endpoint is an RFB client or server. 165 WebSocket client, server, endpoint: As described in The WebSocket 166 Protocol [RFC6455], section 1.2. 168 RFB WebSocket subprotocol: The WebSocket subprotocol (described in 169 [RFC6455] section 1.9) which acts as a transport for the RFB 170 Protocol, as described in this document. 172 RFB WebSocket client, server, endpoint: An RFB client, server, or 173 endpoint respectively which is also a WebSocket client, server, or 174 endpoint and uses the RFB WebSocket subprotocol as the RFB 175 transport. 177 3. Interaction with the WebSocket Protocol 179 The WebSocket Protocol contains a number of features not present in 180 TCP. These are discussed here in turn, and their interpretation by 181 RFB entities conforming to the RFB WebSocket subprotocol. 183 3.1. The "Sec-WebSocket-Protocol" header 185 The WebSocket Protocol [RFC6455] section 4, "Opening Handshake", 186 describes the use of the "Sec-WebSocket-Protocol" header to indicate 187 negotiation of a WebSocket subprotocol. The requirements of this 188 section as described by the key words "MUST", "SHOULD", and so on, 189 are not superseded by use of the RFB WebSocket subprotocol. A 190 WebSocket client aware of the RFB WebSocket subprotocol may choose to 191 request the subprotocol by including the token "rfb" in the "Sec- 192 WebSocket-Protocol" header in its request. A WebSocket server aware 193 of the RFB WebSocket subprotocol may choose to respond to such a 194 request by including a "Sec-WebSocket-Protocol" header in its 195 response containing the token "rfb". 197 The interpretation of any data following the opening WebSocket 198 handshake is determined by the subprotocol in effect, if any. If the 199 RFB WebSocket subprotocol was not requested by the client or was not 200 selected by the server, then this document does not place any 201 interpretation on the subsequent data. In particular, if a client 202 requests any subprotocol but the server not include it in its 203 response, the client cannot assume any particular meaning for the 204 data that follows. This is because WebSocket servers may ignore 205 requests for any unknown subprotocols and proceed, and in practice 206 are expected to do so. If the WebSocket client requires use of a 207 particular subprotocol, it is its responsibility to close the 208 connection if use of the subprotocol was not successfully negotiated. 210 The RFB WebSocket subprotocol does not place any restrictions on use 211 of the subprotocol alongside WebSocket extensions. The effect of any 212 such extensions is outside the scope of this document. 214 3.2. Close Frames 216 When the RFB WebSocket subprotocol is in use, the status code and 217 reason of any WebSocket Close frames relate only to the WebSocket 218 transport, not the RFB stream using the transport. The WebSocket 219 connection will normally be closed by a status code 1000 ("Normal 220 Closure") or 1001 ("Going Away"). Any status code or reason sent by 221 the WebSocket client or server SHOULD NOT convey RFB-specific 222 information. No status codes in the private use range 4000-4999 are 223 defined by this subprotocol. No mapping is provided between 224 WebSocket Close frame status codes and the strings used in RFB Close 225 messages. 227 Any RFB-specific close data MAY be conveyed using an appropriate RFB 228 message. For example, in the case of an RFB authentication failure, 229 the close condition may be conveyed using an RFB SecurityResult 230 message as appropriate, after which the WebSocket connection may be 231 closed using a Close frame status code indicating success. As long 232 as there were no errors in the transport, the WebSocket Close frame 233 does not use a status code indicating failure, even though the RFB 234 connection failed to be established, because the RFB error was 235 conveyed as application data over the WebSocket transport. 237 The meaning of any status codes used in Close frames MUST refer to 238 the state of the WebSocket protocol, for status codes defined in the 239 WebSocket Protocol and any subsequent versions, or other status codes 240 registered by the IANA in the Close Code Number Registry. For 241 example, the status code 1002 ("Protocol Error") describes errors in 242 the WebSocket protocol and not an error in the RFB stream carried by 243 the transport. 245 3.3. Data Frames 247 The RFB octet-stream is transported using Data frames with opcode 0x2 248 (Binary). When the RFB WebSocket subprotocol is in use and no 249 WebSocket extensions are in use, WebSocket clients MUST send RFB data 250 using Binary messages. 252 RFB WebSocket subprotocol does not specify any multiplexing of 253 connections or interleaving of data with other streams. Where no 254 WebSocket extensions are in use, RFB WebSocket clients MUST use 255 Binary messages exclusively for RFB data, such that the octets from 256 the ordered stream of Binary WebSocket messages when truncated 257 conform with the description given in the RFB Protocol [RFC6143]. 259 The frame boundaries do not have to be aligned in any way with the 260 RFB stream. RFB WebSocket endpoints, when receiving messages, MUST 261 NOT vary their behaviour based on the framing of the RFB stream using 262 WebSocket messages. It is suggested that RFB WebSocket endpoints 263 avoid sending empty messages, and that endpoints impose a suitable 264 limit on the size of the messages they send to avoid placing 265 unnecessary load on clients. 267 The interpretation of Text messages (with opcode 0x1) is unspecified. 268 RFB WebSocket endpoints SHOULD NOT send Text messages, but if a 269 WebSocket extension is in use which uses these messages they may be 270 sent. An RFB WebSocket client receiving such a message SHOULD fail 271 the WebSocket connection (as defined in section 7.1.7 of [RFC6455]) 272 except where any method has been used to negotiate a meaning for 273 these messages. 275 4. Versioning Considerations 277 The RFB WebSocket subprotocol is identified by the token "rfb". This 278 token contains no version component, since the RFB protocol is 279 already versioned in its initial handshake. The definition of this 280 subprotocol makes no reference to the specific format of messages in 281 RFB 3.8, so is applicable to subsequent versions of the RFB protocol. 283 5. IANA Considerations 285 RFC Editor Note: Please set the RFC number assigned for this document 286 in the sub-sections below and remove this note. 288 5.1. Registration of the RFB WebSocket Subprotocol 290 This specification describes a WebSocket subprotocol registered in 291 the WebSocket Subprotocol Name Registry defined in [RFC6455], section 292 11.5. 294 Subprotocol Identifier: "rfb" 296 Subprotocol Common Name: RFB 298 Subprotocol Definition: RFC??? (this document) 300 6. Security Considerations 302 6.1. Origin checking 304 Using the WebSocket protocol as a transport presents fresh 305 challenges, since the connections can be created by untrusted 306 resources which originate outside the local subnetwork and have 307 traversed any firewalls in place. This differs from TCP connections. 308 For example, an RFB server accessible over TCP on the local 309 subnetwork may be configured on the assumption that connections 310 originate inside the trusted subnet, and this assumption may be 311 enforced using a firewall. To make a connection, any client has to 312 have already gained access to the subnet. 314 This is not the case for a RFB server accepting connections over the 315 WebSocket protocol. The WebSocket protocol is specifically designed 316 so that it is safe to allow untrusted resources to make connections, 317 on the assumption that WebSocket servers carefully enforce any 318 applicable restrictions on the origin of content. In the TCP 319 example, the RFB server does not need to enforce the restriction that 320 connections originate inside the subnet, is this is implemented by 321 the firewall. However, a web-browser running on a machine in the 322 subnet may open up WebSocket connection based on scripts loaded from 323 any source at all on a web page, originating outside the subnet. The 324 web-browser is only able to allow the script to do this on the basis 325 that the Origin header it sends conveys enough information for the 326 WebSocket server to apply any policies and decide if the connection 327 is to be accepted. 329 Therefore, any WebSocket server implementers must carefully consider 330 the implications of opening up access to resources via the WebSocket 331 Protocol. Any WebSocket server must act as its own firewall, since 332 it receives essentially unfiltered connections from the public 333 Internet. In the case of an RFB server which is accessible over TCP 334 as well as the RFB WebSocket subprotocol, the TCP connection may be 335 hidden behind a firewall or NAT or for any other reason may be not 336 publicly accessible on the Internet. In this case, the origin 337 restrictions in place for the TCP connections should be also enforced 338 by the WebSocket server implementation, or else clearly documented in 339 such a way that administrators of the software do not misunderstand 340 the scope of who can connect in to the server. 342 Unless all WebSocket software that runs in a LAN environment is 343 implemented to enforce these restrictions, web-browser vendors may 344 not be able to justify permitting untrusted web resources 345 (JavaScript) to make WebSocket connections. 347 6.2. Data authentication and integrity 349 Where applicable, the Secure WebSocket Protocol (using the WebSocket 350 Protocol over TLS [RFC5246]) may be used. However, it is not 351 practicable in all circumstances to provision many dynamically-run 352 RFB servers on a LAN with a certificate which browsers can verify, so 353 implementors may choose to use an unencrypted WebSocket connection, 354 but authenticate the server at the application level using an 355 encrypting RFB Security Type, verifying the peer using identities 356 known to the RFB client rather than the browser. 358 Therefore, use of TLS is encouraged alongside other mechanisms 359 including secure RFB Security Types. It is strongly recommended that 360 one of these two mechanisms is used to provide authentication of the 361 server, and integrity and confidentiality of RFB data. 363 6.3. Creating a Safe JavaScript Environment 365 Many of the RFB clients using WebSockets are likely to be implemented 366 in JavaScript and executed by web-browsers. In this case, 367 implementors must be aware of the difficulties of executing 368 JavaScript in a safe context. Banners and other resources loaded 369 alongside the page may substitute functions into top-level objects 370 and subvert the security of the connection or skim passwords. When 371 implementing any application which prompts for a user's password or 372 sends and receives data which may be sensitive, the application must 373 be loaded from a safe context, such as a web page served over HTTPS, 374 and which loads no untrusted external resources. Certain operations 375 required for encryption, such as secure random number generation, may 376 require browser support such as the Web Cryptography API [WCAPI]. 378 7. Acknowledgements 380 Thanks to Pierre Garnero of Visteon for feedback during drafting. 382 8. References 383 8.1. Normative References 385 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 386 Requirement Levels", BCP 14, RFC 2119, March 1997. 388 [RFC6143] Richardson, T. and J. Levine, "The Remote Framebuffer 389 Protocol", RFC 6143, March 2011. 391 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 392 6455, December 2011. 394 8.2. Informative References 396 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 397 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 399 [WCAPI] Dahl, D., Ed. and R. Sleevi, Ed., "Web Cryptography API, 400 W3C Working Draft", June 2013. 402 [WSAPI] Hickson, I., Ed., "The WebSocket API", April 2013. 404 Author's Address 406 Nicholas Wilson 407 RealVNC Ltd. 408 Betjeman House, 104 Hills Road 409 Cambridge CB2 1LQ 410 UK 412 Phone: +44 1223 310411 413 Email: ncw@realvnc.com