idnits 2.17.1 draft-realvnc-websocket-00.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 (August 13, 2013) is 3881 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 August 13, 2013 5 Expires: February 14, 2014 7 Use of the WebSocket Protocol as a Transport for the Remote Framebuffer 8 Protocol 9 draft-realvnc-websocket-00 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 February 14, 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 . . . . . . . . . . . . . . . . . . . . . . . 5 68 4. Versioning Considerations . . . . . . . . . . . . . . . . . . 6 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 70 5.1. Registration of the RFB WebSocket Subprotocol . . . . . . 6 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 72 6.1. Origin checking . . . . . . . . . . . . . . . . . . . . . 7 73 6.2. Encryption . . . . . . . . . . . . . . . . . . . . . . . 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. This is because the 98 initial HTTP handshake, performed by the user agent rather than the 99 untrusted web resource, conveys origin context, preventing a remote 100 webpage from accessing servers on the local network unless the server 101 is configured to allow such access. 103 Therefore, offering RFB resources over a WebSocket-based transport 104 opens access to a variety of devices unable to use the TCP transport 105 described in The RFB Protocol [RFC6143]. 107 The purpose of defining a WebSocket subprotocol is firstly to give 108 endpoints a clear way to indicate how the RFB stream is mapped to 109 WebSocket frames, ensuring compatible transport of the stream by 110 using an agreed mapping. Secondly, using a WebSocket subprotocol 111 enables multiple services to run at once on a single server. 112 Services which run over TCP/IP commonly use a port number allocated 113 for each service to enable multiple services, but the behaviour of 114 HTTP proxies makes it likely that WebSocket servers will commonly be 115 run only on ports 80 and 443. The WebSocket subprotocol mechanism is 116 analogous to the port number system of IP addressing, but a short 117 string naturally associated with the service is to identify it, 118 rather than a number. 120 1.2. Overview of the WebSocket Protocol as a stream transport 122 _This section is non-normative._ 124 The RFB Protocol [RFC6143], section 7 explains that the protocol may 125 operate over any reliable stream- or message-oriented transport, but 126 only describes the RFB as a stream of octets. This gives a clear 127 mapping for the TCP/IP transport, but for message-oriented transport 128 layers, the encapsulation of the RFB octet-stream must be specified. 130 In this document, the WebSocket subprotocol for RFB is defined to 131 place no importance on the message boundaries of the WebSocket layer. 132 Instead, WebSocket messages are concatenated to form in each 133 direction an octet-stream. 135 This is firstly because some RFB messages may be large, such as those 136 containing pixel data, and requiring these to be processed as a 137 single message may be large burden for some clients. The WebSocket 138 API [WSAPI] requires an implementation of the API to buffer the 139 fragments of the WebSocket message until the entire message has been 140 received. Although the RFB server and any WebSocket-aware proxy can 141 fragment the message as it chooses, a client application such as a 142 mobile web-browser may have to consume several megabytes of memory to 143 satisfy the requirements of the WebSocket API. 145 Secondly, it is advantageous to RFB servers to be able to wrap the 146 RFB stream in WebSocket messages flexibly. As well as being a 147 convenience to implementors of RFB servers, it also enables WebSocket 148 connectivity to be added to legacy software using a proxy. Without 149 requiring knowledge the protocol, and generic proxy may be used which 150 concatenates WebSocket messages received from the WebSocket client to 151 send over TCP to the RFB server, and reads bytes from the RFB server 152 and sends them to the client via WebSocket messages. 154 2. Definitions 156 RFB client, server, endpoint: As defined in The RFB Protocol 157 [RFC6143], section 1. An RFB endpoint is an RFB client or server. 159 WebSocket client, server, endpoint: As described in The WebSocket 160 Protocol [RFC6455], section 1.2. 162 RFB WebSocket subprotocol: The WebSocket subprotocol (described in 163 [RFC6455] section 1.9) which acts as a transport for the RFB 164 Protocol, as described in this document. 166 RFB WebSocket client, server, endpoint: An RFB client, server, or 167 endpoint respectively which is also a WebSocket client, server, or 168 endpoint and uses the RFB WebSocket subprotocol as the RFB 169 transport. 171 3. Interaction with the WebSocket Protocol 173 The WebSocket Protocol contains a number of features not present in 174 TCP. These are discussed here in turn, and their interpretation by 175 RFB entities conforming to the RFB WebSocket subprotocol. 177 3.1. The "Sec-WebSocket-Protocol" header 179 The WebSocket Protocol [RFC6455] section 4, "Opening Handshake", 180 describes the use of the "Sec-WebSocket-Protocol" header to indicate 181 negotiation of a WebSocket subprotocol. The requirements of this 182 section as described by the key words "MUST", "SHOULD", and so on, 183 are not superseded by use of the RFB WebSocket subprotocol. A 184 WebSocket client aware of the RFB WebSocket subprotocol may choose to 185 request the subprotocol by including the token "rfb" in the "Sec- 186 WebSocket-Protocol" header in its request. A WebSocket server aware 187 of the RFB WebSocket subprotocol may choose to respond to such a 188 request by including a "Sec-WebSocket-Protocol" header in its 189 response containing the token "rfb". 191 The interpretation of any data following the opening WebSocket 192 handshake is determined by any subprotocols in effect. If the RFB 193 WebSocket subprotocol was not requested by the client or was not 194 selected by the server, then this document does not place any 195 interpretation on the subsequent data. In particular, if a client 196 requests any subprotocol but the server not include it in its 197 response, the client need not assume any particular meaning for the 198 data that follows. This is because WebSocket servers are likely to 199 ignore requsts for any unknown subprotocols and proceed. If the 200 WebSocket client requires use of a particular subprotocol, it is its 201 responsibility to close the connection if use of the subprotocol was 202 not successfully negotiated. 204 The RFB WebSocket subprotocol does not place any restrictions on use 205 of the subprotocol alongside WebSocket extensions. (Note that only 206 one subprotocol may be used by a WebSocket connection.) The effect 207 of any such extensions is outside the scope of this document. 209 3.2. Close Frames 211 When the RFB WebSocket subprotocol is in use, the status code and 212 reason of any WebSocket Close frames relate only to the WebSocket 213 transport, not the RFB stream using the transport. The WebSocket 214 connection will normally be closed by a status code 1000 ("Normal 215 Closure") or 1001 ("Going Away"). Any status code or reason sent by 216 the WebSocket client or server SHOULD NOT convey RFB-specific 217 information. No status codes in the private use range 4000-4999 are 218 defined by this subprotocol. No mapping is provided between 219 WebSocket Close frame status codes and strings using RFB messages. 221 Any RFB-specific close data MAY be conveyed using an appropriate RFB 222 message. For example, in the case of an RFB authentication failure, 223 the close condition may be conveyed using an RFB SecurityResult 224 message as appropriate, after which the WebSocket connection may be 225 closed using a Close frame status code indicating success. As long 226 as there were no errors in the transport, the WebSocket Close frame 227 does not use a status code indicating failure, even though the RFB 228 connection failed to be established, because the RFB error was 229 conveyed as application data over the WebSocket transport. 231 The meaning of any status codes used in Close frames MUST refer to 232 the state of the WebSocket protocol, for status codes defined in the 233 WebSocket Protocol and any subsequent versions or other 234 specifications registered by the IANA in the Close Code Number 235 Registry. For example, the status code 1002 ("Protocol Error") 236 describes errors in the WebSocket protocol and not an error in the 237 RFB stream carried by the transport. 239 3.3. Data Frames 240 The RFB octet-stream is transported using Data frames with opcode 0x2 241 (Binary). When the RFB WebSocket subprotocol is in use and no 242 WebSocket extensions are in use, WebSocket clients MUST send RFB data 243 using Binary messages. 245 RFB WebSocket subprotocol does not specify any multiplexing of 246 connections or interleaving of data with other streams. Where no 247 WebSocket extensions are in use, RFB WebSocket clients MUST use 248 Binary messages exclusively for RFB data, such that the octets from 249 the ordered stream of Binary WebSocket messages when truncated 250 conform with the description given in the RFB Protocol [RFC6143]. 252 The frame boundaries do not have to be aligned in any way with the 253 RFB stream. RFB WebSocket endpoints, when receiving messages, MUST 254 NOT vary their behaviour based on the framing of the RFB stream using 255 WebSocket messages. It is suggested that RFB WebSocket endpoints 256 avoid sending empty messages, and that endpoints impose a suitable 257 limit on the size of the messages they send to avoid placing 258 unnecessary load on clients. 260 The interpration of Text messages (with opcode 0x1) is unspecified. 261 RFB WebSocket endpoints SHOULD NOT send Text messages, but if a 262 WebSocket extension is in use which uses these messages they may be 263 sent. An RFB WebSocket client receiving such a message SHOULD fail 264 the WebSocket connection (as defined in section 7.1.7 of [RFC6455]) 265 except where any mechanism has been used to negotiate a meaning for 266 these messages. In general, WebSocket extensions may modify the 267 interpretation of data, and as appropriate each the definition of 268 each extension must specify how it interacts with application data 269 using Binary messages in order to be compatible with the RFB 270 WebSocket subprotocol, which is beyond the scope of this document. 272 4. Versioning Considerations 274 The RFB WebSocket subprotocol is identified by the token "rfb". This 275 token contains no version component, since the RFB protocol is 276 already versioned in its initial handshake. The definition of this 277 subprotocol makes no reference to the specific format of messages in 278 RFB 3.8, so is applicable to subsequent versions of the RFB protocol. 280 5. IANA Considerations 282 RFC Editor Note: Please set the RFC number assigned for this document 283 in the sub-sections below and remove this note. 285 5.1. Registration of the RFB WebSocket Subprotocol 286 This specification describes a WebSocket subprotocol registered in 287 the WebSocket Subprotocol Name Registry defined in [RFC6455], section 288 11.5. 290 Subprotocol Identifier: "rfb" 292 Subprotocol Common Name: RFB 294 Subprotocol Definition: RFC??? (this document) 296 6. Security Considerations 298 6.1. Origin checking 300 Using the WebSocket protocol as a transport presents fresh 301 challenges, since the connections can be created by untrusted 302 resources which originate outside the local subnetwork and have 303 traversed any firewalls in place. This differs from TCP connections. 304 For example, an RFB server accessible over TCP on the local 305 subnetwork may be configured on the assumption that connections 306 originate inside the trusted subnet, and this assumption may be 307 enforced using a firewall. To make a connection, any client has to 308 have already gained access to the subnet. 310 This is not the case for a RFB server which accepts connections over 311 the WebSocket protocol, which is specifically designed so that it is 312 safe to allow untrusted resources to make WebSocket connections, on 313 the assumption that WebSocket servers carefully enforce any 314 applicable restrictions on the origin of content. In the TCP 315 example, the RFB server does not need to enforce the restriction that 316 connections originate inside the subnet, as this is implemented using 317 the firewall. A web-browser running on a machine in the subnet may 318 open up WebSocket connections though based on scripts loaded from any 319 source at all on a webpage, originating outside the subnet. The web- 320 browser is only able to allow the script to do this on the basis that 321 the Origin header it sends conveys enough information for the 322 WebSocket server to apply any policies and decide if the connection 323 is to be accepted. 325 Therefore, any WebSocket server implementers must carefully consider 326 the implications of opening up access to resources via the WebSocket 327 Protocol. In the case of an RFB server which is accessible over TCP 328 as well as the RFB WebSocket subprotocol, the TCP connection may be 329 hidden behind a firewall or NAT or for any other reason may be not 330 publicly accessible on the internet. In this case, the origin 331 restrictions in place for the TCP connections should be enforced for 332 the WebSocket server also, or else clearly documented in such a way 333 that administrators of the software do not misunderstand the scope of 334 who can connect in to the server. 336 Unless all WebSocket software that runs in a LAN environment is 337 implemented to enforce these restrictions, web-browsers vendors may 338 not be able to justify continuing to permit untrusted web resources 339 (JavaScript) to make WebSocket connections. 341 6.2. Encryption 343 Where applicable, the Secure WebSocket Protocol (using the WebSocket 344 Protocol over TLS [RFC5246]) may be used. However, it is not 345 practicable in all circumstances to provision many dynamic RFB 346 servers on a LAN with a certificate which browsers can verify, so 347 implementors may choose to perform encryption at the application 348 level using an encrypting RFB Security Type, and verify the peer 349 using identities which can be verified by the RFB implementation 350 rather than the browser. 352 6.3. Creating a Safe JavaScript Environment 354 Many of the RFB clients using WebSockets are likely to be implemented 355 in JavaScript and executed by web-browsers. In this case, 356 implementors must be aware of the difficulties of executing 357 JavaScript in a safe context. Banners and other resources loaded 358 alongside the page may substitute functions into top-level objects 359 and subvert the security of the connection or skim passwords. When 360 implementing any application which prompts for a user's password or 361 sends and receives data which may be sensitive, the application must 362 be loaded from a safe context, such as a web page served over HTTPS, 363 and which loads no untrusted external resources. Certain operations 364 required for encryption, such as secure random number generation, may 365 require browser support such as the Web Cryptography API [WCAPI]. 367 7. Acknowledgements 369 Thanks to Pierre Garnero of Visteon for feedback during drafting. 371 8. References 372 8.1. Normative References 374 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 375 Requirement Levels", BCP 14, RFC 2119, March 1997. 377 [RFC6143] Richardson, T. and J. Levine, "The Remote Framebuffer 378 Protocol", RFC 6143, March 2011. 380 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 381 6455, December 2011. 383 8.2. Informative References 385 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 386 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 388 [WCAPI] Dahl, D., Ed. and R. Sleevi, Ed., "Web Cryptography API, 389 W3C Working Draft", June 2013. 391 [WSAPI] Hickson, I., Ed., "The WebSocket API", April 2013. 393 Author's Address 395 Nicholas Wilson 396 RealVNC Ltd. 397 Betjeman House, 104 Hills Road 398 Cambridge CB2 1LQ 399 UK 401 Phone: +44 1223 310411 402 Email: ncw@realvnc.com